# twitr.sh

> Pay-per-call X/Twitter API for AI agents. No signup, no API keys — the wallet
> is the account. Every call is paid in USDC via x402 (Base, Solana) or MPP
> (Tempo) through the HTTP 402 flow.

## How payment works

1. POST any tool endpoint without credentials → HTTP 402 with an x402
   `PAYMENT-REQUIRED` header AND an MPP `WWW-Authenticate: Payment` header.
2. Pay the quoted amount with either protocol.
3. Retry with the payment credential → data + settlement receipt.
4. Volume tools (search, timelines, lists, community reads) REQUIRE
   `resultsLimit` (1–10000) and bill per returned item; the cap is enforced
   so you never pay for more than requested. draws, x_extract + x_monitor
   require an `Idempotency-Key` header. x_extract is async → poll
   `GET /api/snapshots/{id}` (free, SIWX) for the dataset. 4xx/5xx responses
   are never charged.

## Tools (POST https://twitr.sh/api/tools/{tool})

- `x_read` — Fetch a single tweet, user profile, article, follow relationship, trends, media downloads, or a batch of up to 100 tweets or users. ($0.001200–$1.200000 USD / call)
- `x_search` — Search tweets with the full operator filter set, or search user profiles by keyword. ($0.001200–$1.200000 USD / call)
- `x_timeline` — User timelines (tweets, replies, likes, media, mentions), follower graphs, and tweet engagement lists. ($0.001200–$1.200000 USD / call)
- `x_lists` — Read X list timelines, members, and followers. ($0.001200–$1.200000 USD / call)
- `x_communities` — Community info, members, moderators, tweets, and in-community search. ($0.001200–$1.200000 USD / call)
- `x_extract` — Bulk extraction jobs (followers, replies, quotes, threads, lists, communities, spaces, people/tweet search) returned as downloadable datasets. ($0.001200–$60.000000 USD / call)
- `x_monitor` — Real-time monitors on X accounts or keyword queries — prepaid by the hour; events arrive via free polling or your signed webhook. ($0.026400–$4.234800 USD / call)
- `x_draws` — Pick crypto-random giveaway winners from a tweet's replies, with retweet/follow/filter conditions. ($0.002400–$84.001200 USD / call)
- `x_write` — 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. ($0.006000–$0.036000 USD / call)
- `x_inbox` — Read a connected account's private feed — bookmarks, bookmark folders, notifications, and DM history. ($0.001200–$12.000000 USD / call)
- `x_profile` — Edit a connected account's profile — display name, bio, location, website, avatar, and banner. ($0.012000 USD / call)
- `x_community` — Create, join, leave, or delete an X community as a connected account. ($0.012000–$0.036000 USD / call)
- `x_radar` — Trending news and topics across regions and categories. ($0.001000 USD / call)
- `x_compose` — AI tweet drafting: generate, refine, and score tweet text in a 3-step flow. ($0.001000 USD / call)

## Monitors (real-time, prepaid hours)

1. Create: POST https://twitr.sh/api/tools/x_monitor `{"action":"create","username":"vercel","hours":24}`
   (or `"query":"..."` for keyword monitors). PREPAID — the monitor stops at
   `expires_at` unless extended (`{"action":"extend","monitorId":"mn_...","hours":N}`).
   Early deletion does not refund. Pay on Base (x402) or Tempo (MPP); Solana
   is not offered for monitors.
2. Read events (free, SIWX): GET https://twitr.sh/api/monitors/{id}/events?after={last_event_id}
   — bounded retention (500 events / 24h); poll at most 1/s.
3. Push delivery: register your HTTPS endpoint once at POST https://twitr.sh/api/webhooks
   (free, SIWX; secret shown once). Every delivery is signed:
   `X-Twitr-Signature: sha256=HMAC-SHA256(secret, "{X-Twitr-Timestamp}.{rawBody}")`
   — verify in constant time, reject timestamps older than 5 min, dedupe on
   `delivery_id` + `id`, respond 2xx within 10s. Delivery log:
   GET https://twitr.sh/api/webhooks/{id}/deliveries.
4. Manage (free, SIWX): GET https://twitr.sh/api/monitors · DELETE https://twitr.sh/api/monitors/{id}

## Other interfaces

- Agent skill (install into your skills directory for the full playbook —
  monitors, webhooks, connected-account writes): https://twitr.sh/skill.md
- MCP (JSON-RPC, payment-gated with -32042): POST https://twitr.sh/api/mcp
- OpenAPI 3.1 + payment discovery (draft-payment-discovery-00): https://twitr.sh/openapi.json
- x402 legacy discovery: https://twitr.sh/.well-known/x402
- MPP discovery: https://twitr.sh/.well-known/mpp.json
- Wallet history (free, SIWX): GET https://twitr.sh/api/snapshots · GET https://twitr.sh/api/monitors
- Dashboard: https://twitr.sh/dashboard