{"openapi":"3.1.0","info":{"title":"twitr.sh","version":"1.0.0","contact":{"email":"support@twitr.sh"},"description":"Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup, no keys — the wallet is the account. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.","x-guidance":"All tools are POST /api/tools/{tool} and return 402 with x402 + MPP challenges on first call; pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet's history for free."},"servers":[{"url":"https://twitr.sh"}],"x-ux-hints":"Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.","x-service-info":{"categories":["data","social","search","developer-tools"],"docs":{"homepage":"https://twitr.sh","apiReference":"https://twitr.sh/openapi.json","llms":"https://twitr.sh/llms.txt"}},"x-discovery":{"ownershipProofs":[]},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored."},"publicRead":{"type":"apiKey","in":"query","name":"_public","description":"No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at."}}},"paths":{"/api/snapshots":{"get":{"operationId":"list_my_snapshots","summary":"List snapshots owned by the caller's wallet","description":"Returns every extraction snapshot the caller's wallet has paid for. Wallet identity is proven via SIWX (Sign-In-With-X, CAIP-122). Pending snapshots are reconciled against the live job state on read.","tags":["Snapshots"],"x-guidance":"Call this when the user asks about their extraction history or progress on prior async runs. Free, no payment — just a SIWX signature.","security":[{"siwx":[]}],"responses":{"200":{"description":"List of snapshots for the signing wallet.","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","description":"Recovered signer address (lowercased)."},"count":{"type":"integer"},"snapshots":{"type":"array","items":{"type":"object","properties":{"snapshot_id":{"type":"string"},"actor_id":{"type":"string","enum":["x_read","x_search","x_timeline","x_lists","x_communities","x_extract","x_monitor","draws","radar","compose"]},"mode":{"type":"string"},"status":{"type":"string","enum":["pending","ready","failed"]},"created_at":{"type":"integer","description":"Unix ms."},"record_count":{"type":"integer","description":"Only set when status=ready."},"paid_amount":{"type":"string","description":"USD decimal string."},"paid_protocol":{"type":"string","enum":["x402","mpp"]}},"required":["snapshot_id","actor_id","status","created_at"]}}},"required":["wallet","count","snapshots"]}}}},"402":{"description":"Identity Required. Response advertises the `sign-in-with-x` extension; sign a CAIP-122 message with the user's wallet and retry with `SIGN-IN-WITH-X` header."}}}},"/api/snapshots/{id}":{"get":{"operationId":"get_snapshot","summary":"Fetch one snapshot's status + records","description":"Returns a single snapshot. If pending, it is reconciled against the live extraction job first; if ready, includes all records (cached 24h for free re-fetches). Wallet-gated via SIWX — only the wallet that paid for this snapshot can read it.","tags":["Snapshots"],"x-guidance":"Call when the user asks 'is my extraction done?' and you have the snapshot_id. Free (SIWX-signed).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^sd_[a-zA-Z0-9]+$"}}],"security":[{"siwx":[]}],"responses":{"200":{"description":"Snapshot is ready (includes `download_url` for the JSON blob) OR failed (includes `error`). Rate-limited to 10 download_url issuances per wallet per hour.","content":{"application/json":{"schema":{"type":"object","properties":{"snapshot_id":{"type":"string"},"status":{"type":"string","enum":["ready","failed"]},"actor_id":{"type":"string"},"mode":{"type":"string"},"record_count":{"type":"integer"},"bytes":{"type":"integer","description":"Size of the blob in bytes."},"download_url":{"type":"string","description":"Vercel Blob URL. Fetch with plain GET; no additional auth required. URL is stable until blob expiry (24h by default)."},"expires_at_estimate":{"type":"integer","description":"Unix ms when the blob will expire (estimate — blob retention is 24h after creation)."},"error":{"type":"string","description":"Only when status=failed."}},"required":["snapshot_id","status"]}}}},"202":{"description":"Snapshot still pending — the extraction job is still running.","content":{"application/json":{"schema":{"type":"object","properties":{"snapshot_id":{"type":"string"},"status":{"type":"string","enum":["pending"]},"actor_id":{"type":"string"},"mode":{"type":"string"},"elapsed_seconds":{"type":"integer"},"message":{"type":"string"}},"required":["snapshot_id","status"]}}}},"402":{"description":"Identity Required — sign SIWX and retry."},"403":{"description":"Signing wallet doesn't own this snapshot."},"404":{"description":"Snapshot unknown or expired."},"429":{"description":"60 downloads/hour per wallet exceeded. Includes Retry-After header."}}}},"/api/monitors":{"get":{"operationId":"list_my_monitors","summary":"List monitors owned by the caller's wallet","description":"Every real-time monitor this wallet has paid for, with prepaid-expiry state. Free — identity via SIWX (CAIP-122). Create/extend monitors via the paid endpoint POST /api/tools/x_monitor.","tags":["Monitors"],"x-guidance":"Call when the user asks about their monitors or remaining prepaid hours. Free, SIWX-signed. To keep a monitor running, extend it via /api/tools/x_monitor BEFORE expires_at.","security":[{"siwx":[]}],"responses":{"200":{"description":"Monitors owned by the signing wallet.","content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string"},"count":{"type":"integer"},"monitors":{"type":"array","items":{"type":"object","properties":{"monitor_id":{"type":"string","pattern":"^mn_[a-z0-9]+$"},"type":{"type":"string","enum":["account","keyword"]},"target":{"type":"string","description":"Monitored username or search query."},"event_types":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expired","deleted"]},"created_at":{"type":"integer","description":"Unix ms."},"expires_at":{"type":"integer","description":"Unix ms — end of the prepaid window. The monitor stops here unless extended."},"remaining_seconds":{"type":"integer"},"hours_purchased":{"type":"integer"},"paid_total_usd":{"type":"string"}},"required":["monitor_id","type","target","status","expires_at"]}}},"required":["wallet","count","monitors"]}}}},"402":{"description":"Identity Required — sign SIWX and retry."}}}},"/api/monitors/{id}":{"get":{"operationId":"get_monitor","summary":"Monitor detail","tags":["Monitors"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^mn_[a-z0-9]+$"}}],"responses":{"200":{"description":"Monitor detail + events_url + extend hint.","content":{"application/json":{"schema":{"type":"object","properties":{"monitor":{"type":"object","properties":{"monitor_id":{"type":"string","pattern":"^mn_[a-z0-9]+$"},"type":{"type":"string","enum":["account","keyword"]},"target":{"type":"string","description":"Monitored username or search query."},"event_types":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","expired","deleted"]},"created_at":{"type":"integer","description":"Unix ms."},"expires_at":{"type":"integer","description":"Unix ms — end of the prepaid window. The monitor stops here unless extended."},"remaining_seconds":{"type":"integer"},"hours_purchased":{"type":"integer"},"paid_total_usd":{"type":"string"}},"required":["monitor_id","type","target","status","expires_at"]}}}}}},"402":{"description":"Identity Required — sign SIWX and retry."},"403":{"description":"Signing wallet doesn't own this monitor."},"404":{"description":"Monitor unknown or expired out of retention."}}},"delete":{"operationId":"delete_monitor","summary":"Delete a monitor immediately","description":"Stops the monitor now. Remaining prepaid hours are NOT refunded.","tags":["Monitors"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^mn_[a-z0-9]+$"}}],"responses":{"200":{"description":"Deleted. `{ok, monitor_id, status}`."},"402":{"description":"Identity Required — sign SIWX and retry."},"403":{"description":"Signing wallet doesn't own this monitor."},"404":{"description":"Monitor unknown."},"503":{"description":"Teardown briefly contended — retry in a few seconds."}}}},"/api/monitors/{id}/events":{"get":{"operationId":"poll_monitor_events","summary":"Poll a monitor's events (free)","description":"Events captured by this monitor, oldest→newest. Pass the last event id you processed as `after` to receive only newer events. Bounded retention (500 events / 24h per monitor) — register a webhook for guaranteed delivery. Rate limit: 60 reads/minute per wallet.","tags":["Monitors"],"x-guidance":"Poll at most once per second, ideally on user demand. Persist next_cursor between polls. For push delivery instead, register a webhook at POST /api/webhooks.","security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^mn_[a-z0-9]+$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Last event id you processed — response contains strictly newer events."},{"name":"type","in":"query","schema":{"type":"string","enum":["tweet.new","tweet.reply","tweet.retweet","tweet.quote","tweet.media","tweet.link","tweet.poll","tweet.mention","tweet.hashtag","tweet.longform","profile.avatar.changed","profile.banner.changed","profile.name.changed","profile.username.changed","profile.bio.changed","profile.location.changed","profile.url.changed","profile.verified.changed","profile.protected.changed","profile.pinned_tweet.changed","profile.unavailable.changed","monitor.expired","monitor.deleted"]}}],"responses":{"200":{"description":"Event page.","content":{"application/json":{"schema":{"type":"object","properties":{"monitor_id":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"occurred_at":{"type":"string"},"received_at":{"type":"string"},"source":{"type":"object"},"data":{"type":"object"}},"required":["id","type","occurred_at","data"]}},"next_cursor":{"type":"string"},"has_more":{"type":"boolean"},"retention":{"type":"object"}},"required":["monitor_id","events","has_more"]}}}},"402":{"description":"Identity Required — sign SIWX and retry."},"403":{"description":"Signing wallet doesn't own this monitor."},"429":{"description":"Polling too fast — includes Retry-After."}}}},"/api/webhooks":{"get":{"operationId":"list_my_webhooks","summary":"List this wallet's webhooks","tags":["Webhooks"],"security":[{"siwx":[]}],"responses":{"200":{"description":"Webhooks (signing secrets are never included).","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^wh_[a-z0-9]+$"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"description":"Empty = all types."},"status":{"type":"string","enum":["active","paused"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"integer"},"deliveries_url":{"type":"string"}},"required":["id","url","status"]}}}}}}},"402":{"description":"Identity Required — sign SIWX and retry."}}},"post":{"operationId":"register_webhook","summary":"Register a webhook so your AI agent receives real-time monitor events","description":"Push delivery for event-driven agents (Claude, OpenClaw, Hermes, or any HTTPS service): we POST a signed event to your endpoint the moment a monitored account posts (tweet.new), replies, retweets, or quotes — so your agent reacts in real time instead of polling. A terminal monitor.expired / monitor.deleted event fires once when a monitor ends, so silence is never ambiguous. Free (SIWX). Your HTTPS endpoint receives a signed POST for every event from every monitor this wallet owns (optionally filtered by eventTypes). VERIFY EVERY DELIVERY: recompute sha256=HMAC-SHA256(secret, `${X-Twitr-Timestamp}.${rawBody}`) and constant-time-compare against the X-Twitr-Signature header; reject timestamps older than 5 minutes; dedupe on the envelope's delivery_id (per retry) and id (per event). Respond 2xx within 10 seconds — do slow work async. Delivery envelope: {type, id, delivery_id, monitor_id, occurred_at, received_at, source, data}. Retries back off over ~36 minutes (max 6 attempts) before marking the delivery failed; 50 consecutive failures auto-pause the webhook (a successful /test re-activates it). Max 3 webhooks per wallet.","tags":["Webhooks"],"x-guidance":"The 201 response contains the signing secret EXACTLY ONCE — store it immediately. Use /rotate if it is ever lost or leaked.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public HTTPS endpoint your agent listens on (hostnames only — no IPs/localhost)."},"eventTypes":{"type":"array","items":{"type":"string","enum":["tweet.new","tweet.reply","tweet.retweet","tweet.quote","tweet.media","tweet.link","tweet.poll","tweet.mention","tweet.hashtag","tweet.longform","profile.avatar.changed","profile.banner.changed","profile.name.changed","profile.username.changed","profile.bio.changed","profile.location.changed","profile.url.changed","profile.verified.changed","profile.protected.changed","profile.pinned_tweet.changed","profile.unavailable.changed","monitor.expired","monitor.deleted"]},"description":"Which events to receive (default: all). Post events (tweet.*) fire for any monitor; profile-change events (profile.*.changed) fire for account monitors only. Lifecycle events (monitor.expired, monitor.deleted) fire once when a monitor ends."}},"required":["url"]},"example":{"url":"https://agent.example.com/hooks/x-events","eventTypes":["tweet.new"]}}}},"responses":{"201":{"description":"Created — body carries {webhook, secret (once), note}."},"400":{"description":"Invalid url or eventTypes."},"402":{"description":"Identity Required — sign SIWX and retry."},"409":{"description":"Webhook limit reached (3 per wallet)."},"429":{"description":"Too many configuration changes — Retry-After set."}}}},"/api/webhooks/{id}":{"get":{"operationId":"get_webhook","summary":"Webhook detail (never the secret)","tags":["Webhooks"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wh_[a-z0-9]+$"}}],"responses":{"200":{"description":"Webhook detail."},"402":{"description":"Identity Required."},"403":{"description":"Not your webhook."},"404":{"description":"Unknown webhook."}}},"delete":{"operationId":"delete_webhook","summary":"Delete a webhook and its delivery log","tags":["Webhooks"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wh_[a-z0-9]+$"}}],"responses":{"200":{"description":"Deleted."},"402":{"description":"Identity Required."},"403":{"description":"Not your webhook."},"404":{"description":"Unknown webhook."}}}},"/api/webhooks/{id}/rotate":{"post":{"operationId":"rotate_webhook_secret","summary":"Rotate the signing secret (shown once)","description":"The old secret stops verifying immediately.","tags":["Webhooks"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wh_[a-z0-9]+$"}}],"responses":{"200":{"description":"{id, secret, rotated_at} — store the secret now."},"402":{"description":"Identity Required."},"403":{"description":"Not your webhook."}}}},"/api/webhooks/{id}/test":{"post":{"operationId":"test_webhook","summary":"Send a signed webhook.test delivery","description":"Verifies reachability + your signature handling. A 2xx from your receiver re-activates a paused webhook.","tags":["Webhooks"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wh_[a-z0-9]+$"}}],"responses":{"200":{"description":"{success, status_code, webhook}."},"402":{"description":"Identity Required."},"403":{"description":"Not your webhook."}}}},"/api/webhooks/{id}/deliveries":{"get":{"operationId":"list_webhook_deliveries","summary":"Recent delivery log (7 days)","tags":["Webhooks"],"security":[{"siwx":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wh_[a-z0-9]+$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"after","in":"query","schema":{"type":"string"},"description":"Cursor — last delivery id seen."}],"responses":{"200":{"description":"Deliveries, newest first: {id, event_id, event_type, status (pending|delivered|retrying|failed|test), attempts, last_status_code, last_error, created_at, delivered_at}."},"402":{"description":"Identity Required."},"403":{"description":"Not your webhook."}}}},"/api/x-accounts":{"get":{"operationId":"list_connected_accounts","summary":"List the wallet's connected X accounts","tags":["Accounts"],"security":[{"siwx":[]}],"responses":{"200":{"description":"{accounts: [{handle, status (pending_code|linked), created_at, linked_at}]}."},"402":{"description":"Identity Required (sign in with your wallet)."}}}},"/api/x-accounts/connect":{"post":{"operationId":"connect_account","summary":"Connect an X account (free, SIWX)","description":"REQUIRED before x_write. Free — SIWX identity, not payment. Relays credentials to the platform (encrypted at rest; never stored here) and binds the handle to your wallet. If the account has two-factor auth, you MUST include totp_secret (the authenticator setup secret, e.g. JBSWY3D… — not the 6-digit code) or the login is rejected. Returns status=linked when done, or status=pending_code + challenge_id when an email code is needed — then call /api/x-accounts/confirm. On 429 login_cooldown the account is temporarily paused: wait the Retry-After seconds, do NOT retry sooner (it extends the pause).","tags":["Accounts"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"X handle, no @."},"email":{"type":"string","description":"Email on the X account (may receive a verification code)."},"password":{"type":"string","description":"X account password."},"totp_secret":{"type":"string","description":"REQUIRED if the account has 2FA: the authenticator secret key, not the 6-digit code."}},"required":["username","email","password"]}}}},"responses":{"200":{"description":"{handle, status: 'linked'} or {handle, status: 'pending_code', challenge_id}."},"402":{"description":"Identity Required."},"429":{"description":"Login temporarily paused (login_cooldown) — wait Retry-After seconds; retrying extends it."}}}},"/api/x-accounts/confirm":{"post":{"operationId":"confirm_account","summary":"Submit the email verification code (free, SIWX)","tags":["Accounts"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"challenge_id":{"type":"string","description":"From the connect response."},"code":{"type":"string","description":"The code emailed to the account."}},"required":["challenge_id","code"]}}}},"responses":{"200":{"description":"{handle, status: 'linked'} — the handle is now usable for x_write."},"402":{"description":"Identity Required."}}}},"/api/x-accounts/{handle}":{"delete":{"operationId":"disconnect_account","summary":"Disconnect an X account (free, SIWX)","tags":["Accounts"],"security":[{"siwx":[]}],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ok: true, handle}."},"402":{"description":"Identity Required."},"404":{"description":"This wallet has no such connected account."}}}},"/api/tools/x_read":{"post":{"operationId":"x_read","summary":"X Read","description":"Fetch a single tweet, user profile, article, follow relationship, trends, media downloads, or a batch of up to 100 tweets or users.","tags":["Social"],"x-guidance":"resource=get-tweet|get-user (id), batch-tweets|batch-users (ids array, ≤100), check-follower (source+target usernames), trends (optional woeid/count), article (tweet id), followers-you-know (id + mandatory resultsLimit), download-media (id or ids ≤50 — returns media file URLs on THIS origin; links live 7 days). Fixed-price per call/id except followers-you-know which is per-result.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"1.200000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string","description":"Which read operation to run.","enum":["get-tweet","get-user","batch-tweets","batch-users","check-follower","trends","article","followers-you-know","download-media"]},"id":{"type":"string","description":"Tweet ID, user ID, or username (depends on resource)."},"ids":{"type":"array","description":"batch-tweets|batch-users: up to 100 tweet IDs or user IDs/usernames.","items":{"type":"string"}},"source":{"type":"string","description":"check-follower: source username."},"target":{"type":"string","description":"check-follower: target username."},"woeid":{"type":"integer","description":"trends: region WOEID (default 1 = worldwide)."},"count":{"type":"integer","description":"trends: number of trends to return."},"resultsLimit":{"type":"integer","description":"Mandatory for followers-you-know: max results, billed per result.","minimum":1,"maximum":10000}},"required":["resource"]},"example":{"resource":"get-tweet","id":"2079908425904042170"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"2079908425904042170","text":"Ship early, ship often.","authorUsername":"vercel","likeCount":4210,"retweetCount":512,"createdAt":"2026-02-24T10:05:00.000Z"}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.001200","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_search":{"post":{"operationId":"x_search","summary":"X Search","description":"Search tweets with the full operator filter set, or search user profiles by keyword.","tags":["Search"],"x-guidance":"type=search-tweets (default): q required, resultsLimit MANDATORY (billed per tweet returned). Supports the full filter set: fromUser, language, sinceDate/untilDate, mediaType, minFaves, verifiedOnly, exactPhrase, excludeWords, advancedQuery, and more. type=search-users: q required; returns one results page per call — follow report.next_cursor for the next page (each page is a separate paid call).","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"1.200000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Search tweets (default) or users.","enum":["search-tweets","search-users"]},"q":{"type":"string","description":"Search query (X operator syntax supported for tweets)."},"resultsLimit":{"type":"integer","description":"search-tweets: MANDATORY max tweets returned, billed per tweet.","minimum":1,"maximum":10000},"cursor":{"type":"string","description":"search-users: pagination cursor from a previous call's report.next_cursor."},"fromUser":{"type":"string"},"language":{"type":"string"},"sinceDate":{"type":"string","description":"YYYY-MM-DD"},"untilDate":{"type":"string","description":"YYYY-MM-DD"},"mediaType":{"type":"string","enum":["images","videos","gifs","media"]},"minFaves":{"type":"integer"},"minRetweets":{"type":"integer"},"minReplies":{"type":"integer"},"verifiedOnly":{"type":"boolean"},"exactPhrase":{"type":"string"},"excludeWords":{"type":"string"},"advancedQuery":{"type":"string","description":"Raw X search operator string appended to q."}},"required":["q"]},"example":{"q":"artificial intelligence","type":"search-tweets","resultsLimit":50,"language":"en","minFaves":100}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1893710452812718080","text":"This is a great thread, thanks for sharing.","authorUsername":"elonmusk","likeCount":1180,"createdAt":"2026-02-24T10:05:00.000Z"}],"runId":"tw_example","duration":2,"payment":{"protocol":"x402","amount":"0.060000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_timeline":{"post":{"operationId":"x_timeline","summary":"X Timeline","description":"User timelines (tweets, replies, likes, media, mentions), follower graphs, and tweet engagement lists.","tags":["Social"],"x-guidance":"kind selects the timeline: user-tweets|user-replies|user-likes|user-media|user-mentions|followers|following|verified-followers (id = user) or tweet-replies|tweet-quotes|tweet-thread|tweet-favoriters|tweet-retweeters (id = tweet). resultsLimit is MANDATORY — billed per item returned. Search-operator filters (fromUser, language, mediaType, minFaves, …) apply to tweet timelines.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"1.200000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"Which timeline to fetch.","enum":["user-tweets","user-replies","user-likes","user-media","user-mentions","followers","following","verified-followers","tweet-replies","tweet-quotes","tweet-thread","tweet-favoriters","tweet-retweeters"]},"id":{"type":"string","description":"User ID/username or tweet ID (depends on kind)."},"resultsLimit":{"type":"integer","description":"MANDATORY: max items returned, billed per item.","minimum":1,"maximum":10000},"includeReplies":{"type":"boolean"},"includeParentTweet":{"type":"boolean"},"language":{"type":"string"},"mediaType":{"type":"string","enum":["images","videos","gifs","media"]},"minFaves":{"type":"integer"},"verifiedOnly":{"type":"boolean"}},"required":["kind","id","resultsLimit"]},"example":{"kind":"user-tweets","id":"elonmusk","resultsLimit":100}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1893710452812718080","text":"This is a great thread, thanks for sharing.","authorUsername":"elonmusk","likeCount":1180,"createdAt":"2026-02-24T10:05:00.000Z"}],"runId":"tw_example","duration":3,"payment":{"protocol":"x402","amount":"0.120000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_lists":{"post":{"operationId":"x_lists","summary":"X Lists","description":"Read X list timelines, members, and followers.","tags":["Social"],"x-guidance":"kind=tweets|members|followers; id = list ID. resultsLimit is MANDATORY — billed per item returned. tweets supports sinceTime/untilTime and includeReplies.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"1.200000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"What to read from the list.","enum":["tweets","members","followers"]},"id":{"type":"string","description":"List ID."},"resultsLimit":{"type":"integer","description":"MANDATORY: max items returned, billed per item.","minimum":1,"maximum":10000},"sinceTime":{"type":"string"},"untilTime":{"type":"string"},"includeReplies":{"type":"boolean"}},"required":["kind","id","resultsLimit"]},"example":{"kind":"tweets","id":"2079908425904042170","resultsLimit":100}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1893710452812718080","text":"This is a great thread, thanks for sharing.","authorUsername":"elonmusk","likeCount":1180,"createdAt":"2026-02-24T10:05:00.000Z"}],"runId":"tw_example","duration":2,"payment":{"protocol":"x402","amount":"0.120000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_communities":{"post":{"operationId":"x_communities","summary":"X Communities","description":"Community info, members, moderators, tweets, and in-community search.","tags":["Social"],"x-guidance":"kind=info (fixed price) or members|moderators|tweets|search (per-item — resultsLimit MANDATORY). id = community ID. search additionally requires q.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"1.200000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"What to read.","enum":["info","members","moderators","tweets","search"]},"id":{"type":"string","description":"Community ID."},"q":{"type":"string","description":"search: query within the community."},"resultsLimit":{"type":"integer","description":"Mandatory for members/moderators/tweets/search: max items, billed per item.","minimum":1,"maximum":10000}},"required":["kind","id"]},"example":{"kind":"info","id":"2079908425904042170"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"2079908425904042170","name":"Build in Public","memberCount":48210,"description":"Founders sharing progress, metrics, and lessons."}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.001200","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_extract":{"post":{"operationId":"x_extract","summary":"X Extract","description":"Bulk extraction jobs (followers, replies, quotes, threads, lists, communities, spaces, people/tweet search) returned as downloadable datasets.","tags":["Intelligence"],"x-guidance":"tool selects the extractor (23 options). Provide the matching target: targetTweetId (reply/repost/quote/thread/article/favoriters extractors), targetUsername (follower/following/verified/post/mention/likes/media), targetCommunityId, targetListId, targetSpaceId, or searchQuery (people_search, tweet_search_extractor). resultsLimit is MANDATORY — billed per result (article_extractor bills 5× per result). Runs ASYNC: the response is a claim check {snapshot_id, status_url}; poll status_url (free, SIWX) until status=ready for the download link. Idempotency-Key header is required so retries reuse the same job.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"60.000000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","description":"Which extractor to run.","enum":["follower_explorer","following_explorer","verified_follower_explorer","post_extractor","reply_extractor","repost_extractor","quote_extractor","thread_extractor","article_extractor","favoriters","mention_extractor","user_likes","user_media","community_extractor","community_moderator_explorer","community_post_extractor","community_search","list_member_extractor","list_post_extractor","list_follower_explorer","space_explorer","people_search","tweet_search_extractor"]},"resultsLimit":{"type":"integer","description":"MANDATORY: max results extracted, billed per result.","minimum":1,"maximum":10000},"targetTweetId":{"type":"string"},"targetUsername":{"type":"string"},"targetCommunityId":{"type":"string"},"targetListId":{"type":"string"},"targetSpaceId":{"type":"string"},"searchQuery":{"type":"string"},"language":{"type":"string"},"sinceDate":{"type":"string"},"untilDate":{"type":"string"},"mediaType":{"type":"string","enum":["images","videos","gifs","media"]},"minFaves":{"type":"integer"},"verifiedOnly":{"type":"boolean"}},"required":["tool","resultsLimit"]},"example":{"tool":"follower_explorer","targetUsername":"elonmusk","resultsLimit":500}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"snapshot_id":"sd_ex_a1b2c3d4e5f67890abcdef1234567890","status":"pending","status_url":"/api/snapshots/sd_ex_a1b2c3d4e5f67890abcdef1234567890","message":"Extraction accepted — poll status_url until status='ready' to fetch the dataset.","payment":{"protocol":"x402","amount":"0.600000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_monitor":{"post":{"operationId":"x_monitor","summary":"X Monitor","description":"Real-time monitors on X accounts or keyword queries — prepaid by the hour; events arrive via free polling or your signed webhook.","tags":["Intelligence"],"x-guidance":"action=create needs username (account monitor, e.g. \"vercel\") OR query (keyword monitor, X search syntax, ≤512 chars), optional eventTypes — 21 available: post events (tweet.new, .reply, .retweet, .quote, .media, .link, .poll, .mention, .hashtag, .longform) for any monitor, plus profile-change events (profile.avatar/banner/name/username/bio/location/url/verified/protected/pinned_tweet/unavailable.changed) for ACCOUNT monitors only; default all applicable — and hours (1–168, default 1). action=extend needs monitorId + hours; hours append to the current expiry (total prepaid window ≤ 720h). Extend at least 5 minutes BEFORE expiry — extends inside the final 5 minutes are refused (unpaid) to keep settlement from racing the expiry teardown. PREPAID: the monitor stops and is removed at expires_at unless extended — no open-ended billing; early deletion does not refund remaining hours. Idempotency-Key header REQUIRED — retries replay the original monitor instead of re-charging (on the MCP door, retries are protected by single-use payment credentials instead). Pay with USDC on Base (x402) or Tempo (MPP); Solana is not offered for monitors (stateful resources need a recoverable owner wallet). After creation: poll events at /api/monitors/{id}/events (free — SIWX sign-in with the paying wallet; do NOT poll in a tight loop) or register an HTTPS webhook once at /api/webhooks to push signed events straight to your AI agent (Claude, OpenClaw, Hermes, or any endpoint) in real time. Manage monitors at /api/monitors (SIWX).","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.026400","max":"4.234800"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Create a new monitor or extend an existing one.","enum":["create","extend"]},"type":{"type":"string","description":"Monitor kind (create). Inferred from username/query when omitted.","enum":["account","keyword"]},"username":{"type":"string","description":"X handle to monitor, without @ (create, type=account)."},"query":{"type":"string","description":"X search query to monitor (create, type=keyword).","maxLength":512},"eventTypes":{"type":"array","description":"Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only.","items":{"type":"string","enum":["tweet.new","tweet.reply","tweet.retweet","tweet.quote","tweet.media","tweet.link","tweet.poll","tweet.mention","tweet.hashtag","tweet.longform","profile.avatar.changed","profile.banner.changed","profile.name.changed","profile.username.changed","profile.bio.changed","profile.location.changed","profile.url.changed","profile.verified.changed","profile.protected.changed","profile.pinned_tweet.changed","profile.unavailable.changed"]}},"hours":{"type":"integer","description":"Prepaid hours to purchase (default 1).","minimum":1,"maximum":168},"monitorId":{"type":"string","description":"Monitor to extend (extend only)."}},"required":["action"]},"example":{"action":"create","username":"vercel","eventTypes":["tweet.new"],"hours":24}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"monitor":{"monitor_id":"mn_a1b2c3d4e5f6g7h8","type":"account","target":"vercel","event_types":["tweet.new"],"status":"active","expires_at":1785000000000,"remaining_seconds":86400,"hours_purchased":24,"paid_total_usd":"0.605100"},"events_url":"/api/monitors/mn_a1b2c3d4e5f6g7h8/events","manage_url":"/api/monitors/mn_a1b2c3d4e5f6g7h8","message":"Monitor active for 24 hours.","payment":{"protocol":"x402","amount":"0.605100","currency":"USD"}}}}},"201":{"description":"Monitor created — body carries {monitor, events_url, manage_url, extend}. Poll events_url (free, SIWX) or register a webhook at /api/webhooks."},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"409":{"description":"Active-monitor cap reached — never charged."},"410":{"description":"Extend target already expired — create a new monitor; never charged."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/draws":{"post":{"operationId":"x_draws","summary":"Giveaway Draws","description":"Pick crypto-random giveaway winners from a tweet's replies, with retweet/follow/filter conditions.","tags":["Social"],"x-guidance":"tweetUrl required. Optional: winnerCount (default 1), backupCount, uniqueAuthorsOnly, mustRetweet, mustFollowUsername, filterMinFollowers, filterAccountAgeDays, filterLanguage, requiredHashtags/Keywords/Mentions. Pricing is fixed upfront from the estimatedEntries you set (default 1000, max 10000) — set it near the tweet's reply count; that number is enforced as a hard cap. Payment settles before the draw runs, so pay only when you intend to run it; a failed draw does not auto-refund (contact support). Idempotency-Key header required — retries with the same key replay the original result instead of re-charging.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.002400","max":"84.001200"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tweetUrl":{"type":"string","description":"Full tweet URL (https://x.com/user/status/ID)."},"winnerCount":{"type":"integer","minimum":1},"backupCount":{"type":"integer"},"uniqueAuthorsOnly":{"type":"boolean"},"mustRetweet":{"type":"boolean"},"mustFollowUsername":{"type":"string"},"filterMinFollowers":{"type":"integer"},"filterAccountAgeDays":{"type":"integer"},"filterLanguage":{"type":"string"},"requiredHashtags":{"type":"array","items":{"type":"string"}},"requiredKeywords":{"type":"array","items":{"type":"string"}},"requiredMentions":{"type":"array","items":{"type":"string"}},"estimatedEntries":{"type":"integer","description":"Expected replies inspected — drives the fixed price (default 1000).","minimum":1,"maximum":10000}},"required":["tweetUrl"]},"example":{"tweetUrl":"https://x.com/vercel/status/2079908425904042170","winnerCount":3,"estimatedEntries":500}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"a1b2c3d4e5f67890","tweetId":"2079908425904042170","totalEntries":512,"validEntries":498,"winners":[{"username":"builders_gonna","tweetId":"1893710452812718080"}]}],"runId":"tw_example","duration":6,"payment":{"protocol":"x402","amount":"0.601200","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_write":{"post":{"operationId":"x_write","summary":"X Write","description":"Post, reply, like/unlike, retweet/unretweet, follow/unfollow, DM, delete a tweet, remove a follower, or upload media — through an X account you've connected.","tags":["Social"],"x-guidance":"PREREQUISITE: connect an X account first — POST /api/x-accounts/connect (free, SIWX) with {username, email, password, and totp_secret if the account has 2FA}; finish any email code via /api/x-accounts/confirm. Then reference the linked handle in `account`. Actions: post (text) | reply (text + reply_to_tweet_id) | like|unlike|retweet|unretweet|delete_tweet (target_tweet_id) | follow|unfollow (target_user_id — the NUMERIC user id, get it from x_read get-user) | remove_follower (target_user_id of the follower) | send_dm (target_user_id + text) | upload_media (media_url → returns media_id). You can only write as a handle THIS wallet connected (checked server-side; the input account is not trusted). Payment settles before the action runs and is non-refundable; a write may return status=pending_confirmation with an actionId to poll — do NOT resend. Idempotency-Key header is required so a retry replays the original result instead of acting twice.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.006000","max":"0.036000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Which write to perform.","enum":["post","reply","like","unlike","retweet","unretweet","follow","unfollow","delete_tweet","send_dm","remove_follower","upload_media"]},"account":{"type":"string","description":"A connected X handle owned by this wallet (no @)."},"text":{"type":"string","description":"post|reply|send_dm: the message body."},"reply_to_tweet_id":{"type":"string","description":"reply: the tweet being replied to."},"target_tweet_id":{"type":"string","description":"like|unlike|retweet|unretweet|delete_tweet: the target tweet ID."},"target_user_id":{"type":"string","description":"follow|unfollow|send_dm|remove_follower: the numeric X user id of the target (not the @handle). Get it from x_read get-user."},"media_url":{"type":"string","description":"upload_media: public URL of the file to upload; returns a media_id."},"media_ids":{"type":"array","description":"send_dm: optional uploaded media ids to attach.","items":{"type":"string"}},"community_id":{"type":"string","description":"post: optional community to post into."},"is_note_tweet":{"type":"boolean","description":"post: long-form note tweet."}},"required":["action","account"]},"example":{"action":"post","account":"myhandle","text":"gm from my agent"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1893710452812718080","url":"https://x.com/myhandle/status/1893710452812718080"}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.036000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_inbox":{"post":{"operationId":"x_inbox","summary":"X Inbox","description":"Read a connected account's private feed — bookmarks, bookmark folders, notifications, and DM history.","tags":["Social"],"x-guidance":"PREREQUISITE: connect an X account (see /api/x-accounts/connect). Reads act AS that account, so you can only read the inbox of a handle THIS wallet connected. action=bookmarks (optional folderId) | bookmark_folders | notifications (optional type) | dm_history (target_user_id required). bookmarks/notifications/dm_history are billed per item — set resultsLimit (1–10000). account (the connected handle) is required.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001200","max":"12.000000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Which inbox read to run.","enum":["bookmarks","bookmark_folders","notifications","dm_history"]},"account":{"type":"string","description":"A connected X handle owned by this wallet (no @)."},"resultsLimit":{"type":"integer","description":"Max items to return (billed per item); ignored for bookmark_folders.","minimum":1,"maximum":10000},"folderId":{"type":"string","description":"bookmarks: optional folder to read."},"type":{"type":"string","description":"notifications: optional filter (e.g. mentions)."},"target_user_id":{"type":"string","description":"dm_history: the other party's user id."},"maxId":{"type":"string","description":"dm_history: paginate before this message id."}},"required":["action","account"]},"example":{"action":"bookmarks","account":"myhandle","resultsLimit":50}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1893710452812718080","text":"saved this thread","createdAt":"2026-02-24T10:05:00.000Z"}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.060000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_profile":{"post":{"operationId":"x_profile","summary":"X Profile","description":"Edit a connected account's profile — display name, bio, location, website, avatar, and banner.","tags":["Social"],"x-guidance":"PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=update_profile (any of name, description, location, url) | set_avatar (media_url) | set_banner (media_url). account required. Payment settles before the change; Idempotency-Key required.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.012000","max":"0.012000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Which profile edit to make.","enum":["update_profile","set_avatar","set_banner"]},"account":{"type":"string","description":"A connected X handle owned by this wallet (no @)."},"name":{"type":"string","description":"update_profile: new display name."},"description":{"type":"string","description":"update_profile: new bio."},"location":{"type":"string","description":"update_profile: new location."},"url":{"type":"string","description":"update_profile: new website URL."},"media_url":{"type":"string","description":"set_avatar|set_banner: public image URL."}},"required":["action","account"]},"example":{"action":"update_profile","account":"myhandle","description":"building in public 🛠️"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"updated":true}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.012000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/x_community":{"post":{"operationId":"x_community","summary":"X Community","description":"Create, join, leave, or delete an X community as a connected account.","tags":["Social"],"x-guidance":"PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=create (name, optional description) | join|leave (community_id) | delete (community_id + community_name confirmation). account required. Payment settles before the action; Idempotency-Key required.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.012000","max":"0.036000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Which community action.","enum":["create","join","leave","delete"]},"account":{"type":"string","description":"A connected X handle owned by this wallet (no @)."},"name":{"type":"string","description":"create: the community name."},"description":{"type":"string","description":"create: optional community description."},"community_id":{"type":"string","description":"join|leave|delete: the community ID."},"community_name":{"type":"string","description":"delete: the community name, as confirmation."}},"required":["action","account"]},"example":{"action":"join","account":"myhandle","community_id":"1493446837214187523"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"id":"1493446837214187523","joined":true}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.012000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/radar":{"post":{"operationId":"x_radar","summary":"Trend Radar","description":"Trending news and topics across regions and categories.","tags":["Intelligence"],"x-guidance":"Optional filters: category, region, hours (lookback), limit, source. Use report.next_cursor via `after` for the next page. Flat floor price per call.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001000","max":"0.001000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","description":"Topic category filter.","enum":["general","tech","dev","science","culture","politics","business","entertainment"]},"region":{"type":"string"},"hours":{"type":"integer"},"limit":{"type":"integer"},"source":{"type":"string","description":"Trend source filter.","enum":["github","google_trends","hacker_news","polymarket","reddit","trustmrr","wikipedia"]},"after":{"type":"string","description":"Pagination cursor."}}},"example":{"category":"tech","hours":24,"limit":20}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"title":"AI agents start paying for their own API calls","category":"tech","score":982,"url":"https://example.com/story"}],"runId":"tw_example","duration":1,"payment":{"protocol":"x402","amount":"0.001000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}},"/api/tools/compose":{"post":{"operationId":"x_compose","summary":"Tweet Composer","description":"AI tweet drafting: generate, refine, and score tweet text in a 3-step flow.","tags":["Creator"],"x-guidance":"step=generate (topic + goal required; optional tone/styleUsername/additionalContext/callToAction/mediaType/hasLink/hasMedia), refine (draft required), or score (draft required). Returns text variants with scores and suggestions. Flat floor price per call.","x-ux-hints":"Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. A 424 (partial) or 5xx is never charged.","x-payment-info":{"authMode":"paid","price":{"mode":"dynamic","currency":"USD","min":"0.001000","max":"0.001000"},"protocols":[{"x402":{"network":"base","asset":"USDC"}},{"x402":{"network":"solana","asset":"USDC"}},{"mpp":{"method":"usdc","intent":"charge","currency":"USD"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"step":{"type":"string","description":"Composer step.","enum":["generate","refine","score"]},"topic":{"type":"string"},"goal":{"type":"string"},"draft":{"type":"string"},"tone":{"type":"string"},"styleUsername":{"type":"string"},"additionalContext":{"type":"string"},"callToAction":{"type":"string"},"mediaType":{"type":"string"},"hasLink":{"type":"boolean"},"hasMedia":{"type":"boolean"}},"required":["step"]},"example":{"step":"generate","topic":"pay-per-call APIs for AI agents","goal":"announce launch","tone":"punchy"}}}},"responses":{"200":{"description":"Result dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Array of returned items. Shape varies per tool — see each tool's documentation.","items":{"type":"object"}},"runId":{"type":"string","description":"Run ID for debugging/audit."},"duration":{"type":"integer","description":"Run duration in seconds."}},"required":["items"]},"example":{"items":[{"text":"Your agent can now pay for its own API calls. No signup, no keys — just a wallet.","score":87,"suggestions":["Add a concrete number for credibility"]}],"runId":"tw_example","duration":2,"payment":{"protocol":"x402","amount":"0.001000","currency":"USD"}}}}},"202":{"description":"Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only)."},"400":{"description":"Bad request — missing resultsLimit or Idempotency-Key where required."},"402":{"description":"Payment Required. The response includes an x402 `PAYMENT-REQUIRED` header and an MPP `WWW-Authenticate: Payment` header; pick whichever protocol your wallet supports."},"429":{"description":"Rate limited — includes Retry-After header."},"503":{"description":"Service capacity temporarily unavailable — retry later; never charged."}}}}}}