Skip to Content
IntegrationsTwitter / X Integration

Twitter / X Integration

Connect your Hatcher agent to Twitter (X) so it can post tweets, read timelines, and interact with the crypto community.

X API pricing changed in January 2026. The old fixed-tier pricing (Basic, Pro, Enterprise) has been replaced with a Pay-Per-Use consumption model, similar to AWS billing. The Free tier is write-only and limited. Read access requires Pay-Per-Use with credits. Plan accordingly.

Prerequisites

X API Tiers (as of 2026)

TierPost (Write)ReadCost
Free1,500 tweets/monthNo read access$0
Pay-Per-UseConsumption-basedConsumption-basedPay for what you use (add credits)

If your agent only needs to post tweets (e.g., market updates, meme content), the Free tier works. If it needs to read tweets, timelines, or mentions, you need Pay-Per-Use with credits loaded.

Setup

Hatcher uses OAuth 2.0 with the xurl skill for Twitter/X integration. You need a Client ID and Client Secret from the X Developer Portal.

Sign up for the X Developer Portal

  1. Go to https://developer.x.com/ 
  2. Sign in with the X account you want the bot to post from
  3. Complete the developer signup if you haven’t already

Create a Project and App

  1. In the Developer Portal, go to Projects & Apps
  2. Click Create Project
  3. Give it a name (e.g., “Hatcher Agent”), select a use case, and provide a description
  4. Within the project, click Create App
  5. Name your app (e.g., “MyCryptoBot”)

Set App Permissions

  1. Go to your app’s Settings tab
  2. Under App permissions, click Edit
  3. Select Read and Write (or Read + Write + Direct Messages if you need DM access)
  4. Click Save

Set Up OAuth 2.0

  1. In your app settings, go to User authentication settings
  2. Click Set up
  3. Select Web App as the app type
  4. Set the Redirect URI to the one provided by Hatcher in the Integrations tab
  5. Set a Website URL (e.g., your project website or https://hatcher.host)
  6. Click Save

Get Your OAuth 2.0 Credentials

  1. Go to your app’s Keys and tokens tab
  2. Under OAuth 2.0 Client ID and Client Secret, find:
    • Client ID
    • Client Secret

Copy both values. These are used for the OAuth 2.0 flow.

X only shows the Client Secret once. If you lose it, you must regenerate (which invalidates the old secret).

Configure in Hatcher

  1. Go to your Hatcher Dashboard
  2. Navigate to My Agents and select your agent
  3. Open the Integrations tab
  4. Find Twitter / X and click Configure
  5. Paste your:
    • OAuth2 Client ID
    • OAuth2 Client Secret
  6. Click Save

Restart your agent

Click Restart on your agent to apply the configuration. Your agent will connect to the X API using OAuth 2.0 via the xurl skill.

Test it

Check your agent’s X profile — it should start posting based on your agent’s configuration (e.g., market analysis, content). You can also check the agent logs in Hatcher to see API activity.

Free Tier Limitations

The X Free tier has strict limitations:

  • 1,500 tweets per month (approximately 50 per day)
  • Write-only — your agent cannot read tweets, search, or see mentions
  • No access to the timeline, search, or user lookup endpoints
  • Rate limit: 50 requests per 15-minute window for posting

If your agent needs to read or respond to tweets, you must upgrade to Pay-Per-Use and load credits.

OAuth 2.0 and the xurl Skill

Hatcher uses OAuth 2.0 with the xurl skill for Twitter/X integration. This is the modern approach recommended by X and requires only a Client ID and Client Secret (2 values instead of the legacy 4-key OAuth 1.0a method).

Troubleshooting

”You are not permitted to perform this action”

This error means your API tier doesn’t support the endpoint you’re trying to use. Common causes:

  • Trying to read tweets on the Free tier (read access requires Pay-Per-Use)
  • Trying to access endpoints not included in your tier

Fix: Add credits to your X Developer account for Pay-Per-Use access.

403 Forbidden

Your app permissions are set incorrectly.

  1. Go to the Developer Portal → your app → Settings
  2. Check that App permissions is set to Read and Write
  3. If you changed permissions, regenerate all 4 tokens (permissions are baked into tokens at generation time)
  4. Update the new tokens in Hatcher and restart your agent

429 Too Many Requests

You’ve hit the rate limit. The Free tier allows 50 requests per 15-minute window for posting. Your agent will automatically retry after the rate limit window resets.

Fix: Reduce your agent’s posting frequency in the agent configuration.

”Invalid or expired token”

Your tokens are wrong or were regenerated elsewhere.

  1. Go to the Developer Portal → your app → Keys and tokens
  2. Regenerate all 4 tokens
  3. Update them in Hatcher
  4. Restart the agent

Agent posts but doesn’t read mentions

This is expected on the Free tier. You need Pay-Per-Use with credits to access read endpoints (timelines, search, mentions).

Duplicate tweet errors

X rejects tweets with identical content posted in quick succession. Make sure your agent varies its content. The agent framework typically handles this, but if you see “duplicate content” errors in logs, check your agent’s prompt to ensure it generates unique tweets.

Last updated on
Telegram IntegrationWhatsApp Integration