agentbox-twitter

# Twitter Research Paid Twitter/X data API at `https://twitter.x402.agentbox.fyi`. Costs $0.003 USDC per call via x402 on Solana. Use the `x402_payment` tool for all requests. ## Endpoints ### Search Tweets Find tweets matching a query with 50+ advanced operators. ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/search", "method": "GET", "params": "{\"q\": \"from:elonmusk AI\", \"type\": \"Latest\", \"limit\": 20}" }) ``` **Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | q | string | required | Search query with operators | | type | "Latest" or "Top" | Latest | Sort by recency or popularity | | limit | 1-200 | 20 | Max tweets to return | | cursor | string | - | Pagination cursor from previous response | **Search operators:** | Operator | Example | Description | |----------|---------|-------------| | from:user | `from:elonmusk` | Tweets by user | | to:user | `to:elonmusk` | Replies to user | | @user | `@solana` | Mentioning user | | min_faves:N | `min_faves:100` | Minimum likes | | min_retweets:N | `min_retweets:50` | Minimum retweets | | min_replies:N | `min_replies:10` | Minimum replies | | filter:media | `filter:media` | Has media | | filter:images | `filter:images` | Has images | | filter:videos | `filter:videos` | Has video | | filter:links | `filter:links` | Has links | | filter:replies | `filter:replies` | Only replies | | -filter:replies | `-filter:replies` | Exclude replies | | since:date | `since:2025-01-01` | After date | | until:date | `until:2025-12-31` | Before date | | within_time:Nh | `within_time:24h` | Last N hours | | lang:code | `lang:en` | Language filter | | conversation_id:ID | `conversation_id:123` | In conversation | | filter:self_threads | `from:user filter:self_threads` | User's thread replies | Combine operators: `from:elonmusk AI min_faves:100 -filter:replies within_time:7d` **Response:** `{ query, tweets[], count, hasMore, nextCursor, summary }` The `summary` object includes: `totalLikes`, `totalRetweets`, `totalReplies`, `avgLikes`, `maxLikes`, `topTweetId`. ### Fetch Tweets Get tweet(s) by ID or URL with optional thread, replies, and quotes. ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/tweet/1585841080431321088", "method": "GET", "params": "{\"include\": \"thread,replies\", \"limit\": 50}" }) ``` **URL format:** `/tweet/{ref}` where ref is: - Tweet ID: `1585841080431321088` - Comma-separated IDs: `123,456,789` (batch fetch, no includes) **Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | include | string | - | Comma-separated: `thread`, `replies`, `quotes` | | limit | 1-200 | 50 | Max replies/quotes to return | **Include options (single tweet only):** - `thread` - author's self-reply chain in the conversation - `replies` - replies from other users - `quotes` - quote tweets of this tweet **Response:** `{ tweets[], count, parent?, thread?, replies?, quotes? }` If the fetched tweet is a reply, `parent` is auto-included with the replied-to tweet. ### Fetch Users Get user profile(s) with optional tweets, followers, or following. ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/user/elonmusk", "method": "GET", "params": "{\"include\": \"tweets\", \"limit\": 20}" }) ``` **URL format:** `/user/{ref}` where ref is: - Username: `elonmusk` or `@elonmusk` - User ID: `44196397` - Comma-separated IDs: `123,456` (batch fetch, no includes) **Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | include | string | - | Comma-separated: `tweets`, `followers`, `following` | | limit | 1-200 | 50 | Max tweets/followers/following to return | | include_replies | boolean | false | Include replies in user's tweets | **Response (single):** `{ user, tweets?, followers?, following? }` **Response (batch):** `{ users[], count, hasMore }` ## Usage Patterns ### Monitor a topic ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/search", "method": "GET", "params": "{\"q\": \"x402 OR \\\"402 payment\\\" min_faves:5 within_time:24h\", \"type\": \"Latest\"}" }) ``` ### Get a tweet with full context ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/tweet/1585841080431321088", "method": "GET", "params": "{\"include\": \"thread,replies,quotes\", \"limit\": 20}" }) ``` ### Research a user ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/user/CoinbaseDev", "method": "GET", "params": "{\"include\": \"tweets\", \"limit\": 50}" }) ``` ### Paginate results Use `nextCursor` from a previous response: ``` x402_payment({ "url": "https://twitter.x402.agentbox.fyi/search", "method": "GET", "params": "{\"q\": \"from:elonmusk\", \"cursor\": \"DAABCgAB...\"}" }) ``` ## Cost Every call costs $0.003 USDC on Solana mainnet. Each paginated request is a separate call. Plan queries to minimize calls - use specific operators and reasonable limits. ## Errors | HTTP | Meaning | |------|---------| | 400 | Invalid parameters (check query syntax) | | 402 | Payment required (handled automatically by x402_payment) | | 404 | Tweet or user not found | | 502 | Upstream API error |