documentation

The X API,
sold by the call.

Reads, search, timelines, extractions, real-time monitors, signed webhooks, and write actions — paid per request in USDC. No signup, no keys: the wallet is the account. Agents plug in over HTTP or MCP.

Quickstart

Every tool is POST /api/tools/{tool}. The first call returns 402 Payment Required with the price; pay in USDC and retry the identical request to get your data.

# 1) probe the price (unpaid) — returns 402 with the amount
curl -X POST https://twitr.sh/api/tools/x_read \
  -H 'Content-Type: application/json' \
  -d '{"resource":"get-tweet","id":"2079908425904042170"}'

# 2) pay the 402 in USDC and retry the same request → 200 + data
#    (x402-aware clients do steps 1–2 automatically)

How payment works

You pay per request — no subscription, no prepaid balance. Two rails, both settling on-chain in USDC:

  • x402 — USDC on Base (and Solana). The client signs a payment authorization and sends it in the X-PAYMENT header; we verify, run the call, and settle.
  • MPP — USDC on Tempo, via the Authorization: Payment challenge.

Volume tools bill per returned item and require resultsLimit, so you never pay for more than you asked for. Resource-creating calls (extractions, monitors, writes, draws) require an Idempotency-Key — a retry replays the original result instead of charging twice. Failed calls are not charged.

The wallet is the account: signing in (free) with the same wallet shows your run history and balance in the dashboard or over the API.

Tools

14 tools, each priced per call or per returned item. Full input schemas live in the OpenAPI spec.

X ReadFetch a single tweet, user profile, article, follow relationship, trends, media downloads, or a batch of up to 100 tweets or users.
$0.0012–$1.20
X SearchSearch tweets with the full operator filter set, or search user profiles by keyword.
$0.0012–$1.20
X TimelineUser timelines (tweets, replies, likes, media, mentions), follower graphs, and tweet engagement lists.
$0.0012–$1.20
X ListsRead X list timelines, members, and followers.
$0.0012–$1.20
X CommunitiesCommunity info, members, moderators, tweets, and in-community search.
$0.0012–$1.20
X ExtractBulk extraction jobs (followers, replies, quotes, threads, lists, communities, spaces, people/tweet search) returned as downloadable datasets.
$0.0012–$60.00
X MonitorReal-time monitors on X accounts or keyword queries — prepaid by the hour; events arrive via free polling or your signed webhook.
$0.0264–$4.2348
Giveaway DrawsPick crypto-random giveaway winners from a tweet's replies, with retweet/follow/filter conditions.
$0.0024–$84.0012
X WritePost, reply, like/unlike, retweet/unretweet, follow/unfollow, DM, delete a tweet, remove a follower, or upload media — through an X account you've connected.
$0.006–$0.036
X InboxRead a connected account's private feed — bookmarks, bookmark folders, notifications, and DM history.
$0.0012–$12.00
X ProfileEdit a connected account's profile — display name, bio, location, website, avatar, and banner.
$0.012
X CommunityCreate, join, leave, or delete an X community as a connected account.
$0.012–$0.036
Trend RadarTrending news and topics across regions and categories.
$0.001
Tweet ComposerAI tweet drafting: generate, refine, and score tweet text in a 3-step flow.
$0.001

Monitors

A monitor watches one X account or one keyword query in real time. Monitors are prepaid by the hour (about $0.025/hr) and stop at expires_at unless extended — early deletion does not refund. Maximum 168 hours per purchase, 720 hours of forward window.

Pay on Base (x402) or Tempo (MPP): a monitor is a stateful resource that needs a recoverable owner wallet, so Solana is not offered for it.

POST /api/tools/x_monitor
Idempotency-Key: <uuid>

{ "action": "create", "username": "vercel", "hours": 24 }
{ "action": "create", "query": "\"launch week\"", "hours": 24 }
{ "action": "extend", "monitorId": "mn_…", "hours": 48 }

GET    /api/monitors        # free, wallet-signed — list + status
DELETE /api/monitors/{id}   # free, wallet-signed

Events → your agent

Monitors emit 21 event types — post events (new posts, replies, reposts, quotes, media, links, polls, mentions, hashtags, long posts) for any monitor, plus profile-change events (avatar, banner, name, bio, verification, and more) for account monitors. A terminal monitor.expired / monitor.deleted event fires once when a monitor ends, so silence is never ambiguous. Two ways to receive them — both free:

  • Events (pull) — poll GET /api/monitors/{id}/events?after={last_event_id}. You get strictly newer events, oldest first. 500 events / 24h retained per monitor, 60 reads/min.
  • Webhooks (push) — register an HTTPS endpoint and we POST a signed event the moment it fires. Max 3 webhooks per wallet.

Every delivery is signed. Verify all of them: recompute HMAC-SHA256(secret, `${X-Twitr-Timestamp}.${rawBody}`) and constant-time-compare to X-Twitr-Signature. Reject timestamps older than 5 minutes, dedupe on delivery_id and id, and respond 2xx within 10 seconds. Retries back off over ~36 minutes (6 attempts); 50 consecutive failures auto-pause the webhook, and a successful /test re-activates it.

delivery
# headers: X-Twitr-Signature, -Timestamp, -Delivery, -Event
{
  "type": "tweet.new",
  "id": "ev_…",
  "delivery_id": "dl_…",
  "monitor_id": "mn_…",
  "occurred_at": "2026-07-26T10:00:00Z",
  "received_at": "2026-07-26T10:00:01Z",
  "source": { "username": "vercel" },
  "data": { "text": "…", "url": "https://x.com/…" }
}

# register one (free, wallet-signed) — secret is returned ONCE:
POST /api/webhooks  {"url":"https://your-agent/hooks","eventTypes":["tweet.new"]}
GET  /api/webhooks/{id}/deliveries    # delivery log
POST /api/webhooks/{id}/rotate        # new secret
POST /api/webhooks/{id}/test          # signed test + un-pause

Connecting an X account

Write tools (post, like, follow, DM, profile, community) act through an X account you connect once. Credentials are relayed for the login and are never stored here, never placed in a URL, and never exposed to the calling agent. One handle belongs to exactly one wallet, and ownership is re-checked server-side on every write.

# 1) connect (free, wallet-signed). include totp_secret if the account has 2FA.
POST /api/x-accounts/connect
{"username":"yourhandle","email":"you@example.com","password":"…","totp_secret":"…"}
# -> 202 {status:"connecting"} — the login runs in the background (30–50s)

# 2) poll until linked; if an email code is required, confirm it
GET  /api/x-accounts
POST /api/x-accounts/confirm  {"challenge_id":"…","code":"123456"}
# -> {status:"linked"} — now x_write can act as this handle

# 3) write (paid). a 202 pending_confirmation means DO NOT resend.
POST /api/tools/x_write
Idempotency-Key: <uuid>
{"action":"post","account":"yourhandle","text":"shipping day"}

Machine specs

  • /openapi.json — full OpenAPI 3.1 with per-tool schemas + payment discovery.
  • /llms.txt — LLM-friendly index.
  • /skill.md — installable agent skill: the full automation playbook (monitors, webhooks, connected-account writes).
  • POST /api/mcp — MCP endpoint; tools are payment-gated with a JSON-RPC 402. (tools/list is free — only tools/call is gated.)
  • /.well-known/x402 · /.well-known/mpp.json — payment-protocol discovery.