Set up X

Have an X account for the bot

The bot posts as an X account. You have two options:

• Use your main X account. Simpler. Thank-yous post under your own handle.
• Create a dedicated bot account. A separate X account for the bot (e.g. @yourname_bot). Thank-yous are visually distinct from your own tweets.

The account you choose must be in good standing — not suspended, not restricted, able to post tweets at the time you run through the developer-account application. You'll sign in as this account in the next step.

Apply for Developer access

X's developer platform is separate from the regular X product. You apply for access to it once per X account. Approval can be instant or take hours to days depending on X's current review queue.

1. Make sure you're signed in as the account from Step 1
2. Go to developer.x.com (the portal is also reachable from console.x.com)
3. Click Sign up or Get Started
4. Fill in the application form. X asks for:
   • What you'll use the API for — be honest. Say you're running a self-hosted stablecoin tipping bot that replies to mentions with a tip link and posts thank-yous when tips arrive. Don't inflate or obscure this; X rejects vague or suspicious applications.
   • Whether your app will post or retweet content on behalf of users — no, only on behalf of your own bot account
   • Whether you'll analyze X data, store user data, or use the API to display X content outside X — generally no for a tipping bot
   • A minimum number of characters in your written description (X's minimum changes; just write a clear honest paragraph)
5. Submit. Wait for approval via email.

Create a project and an app

Inside the developer portal, you organize work into projects, each containing one or more apps. An app is what your bot authenticates as.

1. In the portal, find the Projects & Apps section (usually in the left sidebar or dashboard)
2. Click Create Project (or use the default project if one was auto-created)
   • Name it anything — e.g. "Tipping bot"
   • Use case: pick the closest match to "bot automation"
   • Description: re-state what you wrote in Step 2
3. Inside the project, click Create App (or Add App)
   • Name the app — e.g. "mybot"

Set app permissions to Read AND Write

This is the most commonly-missed step. By default, new X apps are read-only. The bot can't post replies or tweets with read-only permissions.

1. Open your new app's settings
2. Find User authentication settings or App permissions (exact location varies by portal version)
3. Change permissions from Read to Read and Write
4. Save — you may need to regenerate tokens after changing permissions (X tells you this if so)

Generate the five credentials

In your app's Keys and Tokens tab, you'll generate five values. The names may appear slightly differently in X's portal versions; this page uses the names Just The Tips expects in config.env.

1. API Key and API Key Secret — sometimes labeled "Consumer Key" and "Consumer Secret." Click Regenerate in the API Key & Secret section. Copy both immediately to a password manager or scratchpad — the Secret is only shown once.
2. Bearer Token — a separate value. Click Generate in the Bearer Token section. Also shown once.
3. Access Token and Access Token Secret — in the Access Token section, click Generate. These authenticate the bot's account specifically (not just the app). Shown once.

If you change app permissions after generating tokens

Access Tokens inherit the permissions the app had at generation time. If you create tokens while the app is Read-only, then change the app to Read+Write, you must regenerate the Access Token and Access Token Secret. The old ones keep the old permissions even though the app has new ones.

Find the bot account's user ID and handle

Two last values before pasting:

• Handle — the bot account's visible username without the @. E.g. if the account appears as @mybot_ in tweets, the handle is mybot_.
• User ID — the numeric ID of the bot account. X uses this internally.

Option A — tweeterid.com

Go to tweeterid.com, paste the @handle, hit convert. Numeric ID comes back.

Option B — X API (if you already have credentials)

Once you have your Bearer Token from Step 4:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
     "https://api.x.com/2/users/by/username/YOUR_HANDLE"

The response has a data.id field — that's the numeric user ID.

Paste into config.env and restart

Open your bot's config.env. If you enabled X in the configurator, the X section is already there, commented out with explanatory headers. Uncomment the lines (remove the #) and fill in each value:

Save. Restart the bot (stop and start it locally; redeploy on Railway/Render/Fly).

Open /check. The X row should go green with a message like "polling for mentions of @yourbot every 60s". If it shows red, the detail text explains what's wrong — almost always an auth issue (revalidate the five credentials) or an access-level issue (your tier doesn't cover the endpoint the adapter is calling).

What happens next

The bot polls X every 60 seconds for mentions of your bot account. If a mention contains "tip" or !tip, the bot replies with your tip page URL. When a tip lands on-chain, the bot posts a top-level thank-you tweet in the bot account's feed. All stateless — on restart, it skips old mentions rather than replaying.

Recommended safety measure

Many platforms offer a spending cap or monthly limit feature on API usage. Check whether X currently does in your developer portal, and set one — this protects you from unexpected usage in case the bot somehow ends up polling far more aggressively than intended (a bug, a misconfiguration, or a loop). The poll interval defaults to 60 seconds and is bounded; setting a spending cap is a second layer.

If X exposes rate-limit headers in their API responses, the bot respects them automatically. The combination of the bot's built-in rate-respecting plus a platform-level cap is a belt-and-suspenders arrangement.

If you want to tune the poll interval, add X_MENTION_POLL_SECONDS=120 (or any higher integer) to config.env — longer interval = fewer API calls = slower response to mentions. 60 is the default; 15 is the minimum (enforced by the adapter).

Troubleshooting

X row shows "401 Unauthorized"

One or more credentials are wrong. Regenerate the API Key, API Key Secret, Bearer Token, Access Token, and Access Token Secret in X's developer portal. Make sure you copied each one completely — they're long strings and easy to truncate. Paste all five again and restart.

X row shows "403 Forbidden" or the adapter can't post replies

The app's permissions are Read-only, or the Access Token was generated when the app was Read-only and hasn't been regenerated since. Go to Step 3 and ensure the app is set to Read and Write, then regenerate the Access Token and Access Token Secret in Step 4 and paste the new values.

X row shows "403 Forbidden: endpoint not available at your access level"

Your current X Developer access level doesn't include the mentions-timeline endpoint. Check X's current access-level documentation; you may need to change levels. Until then, the bot runs fine on your other platforms — the X row stays red but nothing else is affected.

X row shows "429 Too Many Requests"

The bot is hitting a rate limit. Increase the poll interval in config.env with X_MENTION_POLL_SECONDS=120 (or higher) and restart. The adapter respects the X-RateLimit headers X sends, but a quieter poll loop is the safest fix.

Bot posts thank-yous but never replies to mentions

Verify the bot account's @handle is correct in X_BOT_HANDLE (no leading @). Verify the numeric user ID matches the handle. Test: tweet "@yourbot can I tip?" and wait 60-120 seconds — a reply should appear. If not, check the bot's logs for polling errors.

Something else

See the general troubleshooter. For X-specific behavior not covered here, the X developer documentation is the authoritative source.