{"skill":{"slug":"x-oauth-api","displayName":"X OAuth API","summary":"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 chec...","description":"---\nname: x-oauth-api\ndescription: 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).\nmetadata:\n  { \"openclaw\": { \"requires\": { \"env\": [\"X_API_KEY\", \"X_API_SECRET\", \"X_ACCESS_TOKEN\", \"X_ACCESS_TOKEN_SECRET\"] } } }\n---\n\n# X OAuth API Skill\n\nPost to X (formerly Twitter) using the official X API with OAuth 1.0a authentication.\n\n## Overview\n\nThis 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.\n\n**Use when:**\n- User says \"post to X\", \"tweet this\", \"post on Twitter\"\n- Need to create threads or media posts\n- Want to check mentions or engage with replies\n\n## Quick Start\n\n### 1. Configure X API Credentials\n\nStore these environment variables (from your X Developer Account):\n```\nX_API_KEY              # Consumer Key (API Key)\nX_API_SECRET           # Consumer Secret\nX_ACCESS_TOKEN         # Access Token\nX_ACCESS_TOKEN_SECRET  # Access Token Secret\nX_USER_ID              # Optional: Your numeric user ID (speeds up mentions)\n```\n\n### Free Tier vs Paid Tier\n\n**Free tier supports:**\n- ✅ Posting tweets and threads\n- ✅ Deleting tweets\n- ✅ Account info lookup (`x me`)\n\n**Requires Basic+ tier:**\n- 🔒 Search tweets\n- 🔒 Fetch mentions\n- 🔒 Media uploads\n\n### 2. Basic Usage\n\n```bash\n# Post a simple tweet\nx post \"Hello from X API\"\n\n# Post a thread\nx thread \"First tweet\" \"Second tweet\" \"Third tweet\"\n\n# Check mentions\nx mentions --limit 10\n\n# Search recent tweets\nx search \"AI agents\" --limit 5\n```\n\n## Commands\n\n### `x post <text>`\nPost a single tweet.\n\n**Options:**\n- `--reply-to <tweet-id>` - Reply to a specific tweet\n- `--quote <tweet-id>` - Quote tweet\n- `--media <file>` - Attach image/video\n\n### `x thread <tweet1> <tweet2> ...`\nPost a tweet thread.\n\n### `x mentions [options]`\nGet recent mentions of your account.\n\n**Options:**\n- `--limit <n>` - Number of mentions (default: 10, max: 100)\n- `--since <tweet-id>` - Only mentions after this ID\n- `--format json` - Output as JSON\n\n### `x search <query> [options]`\nSearch recent tweets.\n\n**Options:**\n- `--limit <n>` - Number of results (default: 10, max: 100)\n- `--format json` - Output as JSON\n\n### `x delete <tweet-id>`\nDelete a tweet.\n\n### `x me`\nShow current account info (name, username, follower counts, user ID).\n\n## API Rate Limits\n\n| Endpoint | Limit | Window |\n|----------|-------|--------|\n| POST /2/tweets | 200 | 15 min (Free tier) |\n| GET /2/tweets/search/recent | 100 | 15 min (Free tier) |\n| GET /2/users/:id/mentions | 100 | 15 min (Free tier) |\n\nRate limits vary by access tier. See [X API documentation](https://developer.twitter.com/en/docs/twitter-api/rate-limits) for details.\n\n## Authentication\n\nOAuth 1.0a is handled transparently. Just provide your credentials via environment variables. The skill will sign all requests automatically.\n\n## Troubleshooting\n\n**\"Unauthorized\" error**\n- Check X API credentials are correct\n- Verify credentials are set in environment\n- Ensure your app has write permissions in X Developer Portal\n\n**\"Rate limit exceeded\"**\n- Wait 15 minutes for limit to reset\n- Reduce request frequency\n\n**\"This endpoint requires a paid X API tier\"**\n- Search and mentions require Basic+ tier on X API\n- Free tier only supports posting, deleting, and account lookup\n\n## Requirements\n\n- X Developer Account with API access\n- OAuth 1.0a credentials configured\n- Network access to api.twitter.com\n\n## Cost\n\nFree. X API is free for basic usage. Check your app's rate limits in X Developer Portal.\n\n## Gotchas\n- **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.\n- **\"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`).\n- **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.\n- **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.\n- **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.\n","tags":{"latest":"1.1.0"},"stats":{"comments":0,"downloads":1822,"installsAllTime":2,"installsCurrent":2,"stars":2,"versions":2},"createdAt":1770863976613,"updatedAt":1778487906275},"latestVersion":{"version":"1.1.0","createdAt":1773787191050,"changelog":"Fix YAML description to use trigger-phrase format (Use when/NOT for). Add Gotchas: free tier limits, credential rotation, trailing newline auth failures, per-endpoint rate limits, permissions order.","license":"MIT-0"},"metadata":{"setup":[{"key":"X_API_KEY","required":true},{"key":"X_API_SECRET","required":true},{"key":"X_ACCESS_TOKEN","required":true},{"key":"X_ACCESS_TOKEN_SECRET","required":true}],"os":null,"systems":null},"owner":{"handle":"ngmeyer","userId":"s17b4ynykgfggp4dyqsnh504fs885m7j","displayName":"Neal Meyer","image":"https://avatars.githubusercontent.com/u/3868701?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779971693244}}