x-oauth-api

name	x-oauth-api
description	Post to X (Twitter) using the official OAuth 1.0a API. Use when asked to "post to X", "tweet this", "post on Twitter", create threads, delete tweets, or check account info. Free tier compatible. NOT for search, mentions, or media uploads (requires Basic+ tier).
metadata	{"openclaw":{"requires":{"env":["X_API_KEY","X_API_SECRET","X_ACCESS_TOKEN","X_ACCESS_TOKEN_SECRET"]}}}

X OAuth API Skill

Post to X (formerly Twitter) using the official X API with OAuth 1.0a authentication.

Overview

This skill provides direct access to X API v2 for posting tweets, managing threads, and monitoring mentions. No proxy or third-party service required — uses your X API credentials directly.

Use when:

• User says "post to X", "tweet this", "post on Twitter"
• Need to create threads or media posts
• Want to check mentions or engage with replies

Quick Start

1. Configure X API Credentials

Store these environment variables (from your X Developer Account):

X_API_KEY              # Consumer Key (API Key)
X_API_SECRET           # Consumer Secret
X_ACCESS_TOKEN         # Access Token
X_ACCESS_TOKEN_SECRET  # Access Token Secret
X_USER_ID              # Optional: Your numeric user ID (speeds up mentions)

Free Tier vs Paid Tier

Free tier supports:

• ✅ Posting tweets and threads
• ✅ Deleting tweets
• ✅ Account info lookup (x me)

Requires Basic+ tier:

• 🔒 Search tweets
• 🔒 Fetch mentions
• 🔒 Media uploads

2. Basic Usage

# Post a simple tweet
x post "Hello from X API"

# Post a thread
x thread "First tweet" "Second tweet" "Third tweet"

# Check mentions
x mentions --limit 10

# Search recent tweets
x search "AI agents" --limit 5

Commands

x post <text>

Post a single tweet.

Options:

• --reply-to <tweet-id> - Reply to a specific tweet
• --quote <tweet-id> - Quote tweet
• --media <file> - Attach image/video

x thread <tweet1> <tweet2> ...

Post a tweet thread.

x mentions [options]

Get recent mentions of your account.

Options:

• --limit <n> - Number of mentions (default: 10, max: 100)
• --since <tweet-id> - Only mentions after this ID
• --format json - Output as JSON

x search <query> [options]

Search recent tweets.

Options:

• --limit <n> - Number of results (default: 10, max: 100)
• --format json - Output as JSON

x delete <tweet-id>

Delete a tweet.

x me

Show current account info (name, username, follower counts, user ID).

API Rate Limits

Endpoint	Limit	Window
POST /2/tweets	200	15 min (Free tier)
GET /2/tweets/search/recent	100	15 min (Free tier)
GET /2/users/:id/mentions	100	15 min (Free tier)

Rate limits vary by access tier. See X API documentation for details.

Authentication

OAuth 1.0a is handled transparently. Just provide your credentials via environment variables. The skill will sign all requests automatically.

Troubleshooting

"Unauthorized" error

• Check X API credentials are correct
• Verify credentials are set in environment
• Ensure your app has write permissions in X Developer Portal

"Rate limit exceeded"

• Wait 15 minutes for limit to reset
• Reduce request frequency

"This endpoint requires a paid X API tier"

• Search and mentions require Basic+ tier on X API
• Free tier only supports posting, deleting, and account lookup

Requirements

• X Developer Account with API access
• OAuth 1.0a credentials configured
• Network access to api.twitter.com

Cost

Free. X API is free for basic usage. Check your app's rate limits in X Developer Portal.

Gotchas

• Free tier only supports posting, deleting, and account lookup — search, mentions, and media uploads require Basic+ tier ($100/month). Don't attempt these on free tier; you'll get a clear "requires paid tier" error.
• "Unauthorized" after credential rotation — X API keys are invalidated when you regenerate them in the Developer Portal. All 4 env vars must be updated together (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET).
• Trailing newlines in env vars break auth — If you copy/paste credentials and include a trailing \n, OAuth signing will fail silently with a 401. Always verify with echo -n "$X_API_KEY" | xxd to confirm no whitespace.
• Rate limit 429s are per-endpoint — Hitting the limit on POST /2/tweets doesn't affect GET /2/users. Each endpoint has its own 15-minute window. Back off only the failing endpoint.
• App write permissions must be set before generating tokens — If you generate access tokens before enabling "Read and Write" in the Developer Portal, the tokens will be read-only. Regenerate tokens after changing permissions.