x-oauth-api

使用官方 OAuth 1.0a API 发布到 X (Twitter)。当被要求“发布到 X”、“发推文”、“在 Twitter 上发布”、创建话题、删除推文或检查帐户信息时使用。免费套餐兼容。不适用于搜索、提及或媒体上传（需要 Basic+ 级别）。

## 概述（中文）

使用官方 OAuth 1.0a API 发布到 X (Twitter)。当被要求“发布到 X”、“发推文”、“在 Twitter 上发布”、创建话题、删除推文或检查帐户信息时使用。免费套餐兼容。不适用于搜索、提及或媒体上传（需要 Basic+ 级别）。

## 原文

# 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

```bash
# 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](https://developer.twitter.com/en/docs/twitter-api/rate-limits) 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.