x-api 🐦

Post to X using the official API (OAuth 1.0a).

When to Use

• Posting tweets (cookie-based bird tweet gets blocked by bot detection)
• Official API access is needed for reliability

For reading (timeline, search, mentions), use bird CLI instead — it's free and works well for reads.

Setup

1. Get API Credentials

1. Go to https://developer.x.com/en/portal/dashboard
2. Create a Project and App
3. Set App permissions to Read and Write
4. Get your keys from "Keys and tokens" tab:
   • API Key (Consumer Key)
   • API Key Secret (Consumer Secret)
   • Access Token
   • Access Token Secret

2. Configure Credentials

Option A: Environment variables

export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_SECRET="your-access-token-secret"

Option B: Config file at ~/.clawdbot/secrets/x-api.json

{
  "consumerKey": "your-api-key",
  "consumerSecret": "your-api-secret",
  "accessToken": "your-access-token",
  "accessTokenSecret": "your-access-token-secret"
}

3. Install Dependency

npm install -g twitter-api-v2

Post a Tweet

x-post "Your tweet text here"

Or with full path:

node /path/to/skills/x-api/scripts/x-post.mjs "Your tweet text here"

Supports multi-line tweets:

x-post "Line one

Line two

Line three"

Returns the tweet URL on success.

Limits

• Free tier: 1,500 posts/month (requires credits in X Developer Portal)
• Basic tier ($100/mo): Higher limits

Reading (use bird)

For reading, searching, and monitoring — use the bird CLI:

bird home                    # Timeline
bird mentions                # Mentions
bird search "query"          # Search
bird user-tweets @handle     # User's posts
bird read <tweet-url>        # Single tweet

Troubleshooting

402 Credits Depleted: Add credits in X Developer Portal → Dashboard

401 Unauthorized: Regenerate Access Token (ensure Read+Write permissions are set first)

No credentials found: Set env vars or create config file (see Setup above)