# twitr.sh

> Pay-per-call X/Twitter API for AI agents. No signup — the wallet is the
> account. Every call is paid in USDC via x402 (Base, Solana) or MPP (Tempo)
> through the HTTP 402 flow, or with an API key against a prepaid card balance.

## Per-result billing

Searches, timelines, list and community reads use x402 upto on Base. The 402 amount is a maximum authorization; payment.amount is the actual charge. Empty results cost $0; non-empty reads have a $0.0024 minimum at $0.0012 per record. Use current AgentCash for gasless approval. Other operations retain their advertised fixed/prepaid payment options.
For "this week", calculate Monday and state that date window. If empty, say no matching posts; any older timeline context must be labeled with its dates. Never silently change filters.

Run paid calls sequentially from one wallet; an overlapping call receives HTTP 429 before dispatch and costs zero. Wait for the other call, then retry with a fresh credential. Start research with 3–5 results to keep rich post data within context limits.

## How payment works

1. POST any tool endpoint without credentials → HTTP 402 with an x402
   `PAYMENT-REQUIRED` header; fixed-price operations may also offer an MPP `WWW-Authenticate: Payment` header.
2. Authorize the maximum for per-result reads on Base; use an offered protocol for fixed-price operations.
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. x402 reads settle after success; prepaid operations may fail after payment.

## API key + card balance (optional)

Sign in at https://twitr.sh/dashboard (wallet or Google), add a card balance, create a key, and send
`Authorization: Bearer tw_live_…` on any tool call (HTTP or MCP). Same prices; per-result
reads charge only returned records; `payment.balance_remaining_usd` is in every response.
Short balance → 402 `payment-insufficient` (nothing charged); unknown/revoked key → 401.

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

- `x_read` — Read live X/Twitter data: look up a single tweet or user profile, batch-read up to 100 tweets or users at once, check whether one account follows another, fetch trending topics by region, extract a long-form article, or download tweet media. Pay per call in USDC — no API key, no signup; failed calls are never charged. ($0.002400–$1.200000 USD / call · docs: https://twitr.sh/tools/x_read)
- `x_search` — Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time. ($0.002400–$1.200000 USD / call · docs: https://twitr.sh/tools/x_search)
- `x_timeline` — Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity. ($0.002400–$1.200000 USD / call · docs: https://twitr.sh/tools/x_timeline)
- `x_lists` — Read an X/Twitter List: its combined tweet timeline, its member roster, or its followers. Billed per item returned. Useful for following a curated set of accounts as one feed. ($0.002400–$1.200000 USD / call · docs: https://twitr.sh/tools/x_lists)
- `x_communities` — Read an X/Twitter Community: profile info, member and moderator rosters, the community's tweets, or keyword search inside the community. Fixed price for info; billed per item for rosters, tweets, and search. ($0.002400–$1.200000 USD / call · docs: https://twitr.sh/tools/x_communities)
- `x_extract` — Bulk-export X/Twitter data as downloadable datasets: followers, following, repliers, quoters, reposters, likers, mentions, full threads, list and community members, spaces, or people/tweet search results — 23 extractors. Runs async: you get a claim check immediately and poll a free status URL for the download link. Billed per result. ($0.002400–$60.000000 USD / call · docs: https://twitr.sh/tools/x_extract)
- `x_monitor` — Watch an X/Twitter account or keyword query in real time: new tweets, replies, quotes, mentions, hashtags, and profile changes, delivered to your agent by free polling or HMAC-signed webhooks. Prepaid by the hour with a hard stop at expiry — no open-ended billing. The way to track a brand, competitor, or topic without re-polling paid reads. ($0.026400–$4.234800 USD / call · docs: https://twitr.sh/tools/x_monitor)
- `x_draws` — Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies, with retweet, follow, hashtag, keyword, minimum-follower, and account-age conditions. Fixed price set upfront from your estimated entry count. ($0.002400–$84.001200 USD / call · docs: https://twitr.sh/tools/draws)
- `x_write` — Act on X/Twitter through an account you connect: post a tweet, reply, like, retweet, follow or unfollow, send a DM, delete a tweet, remove a follower, or upload media. Ownership is checked server-side — an agent can only write as a handle its own wallet connected. ($0.006000–$0.036000 USD / call · docs: https://twitr.sh/tools/x_write)
- `x_inbox` — Read a connected X/Twitter account's private surfaces: bookmarks and bookmark folders, notifications, and DM history. Billed per item returned; readable only for handles this wallet connected. ($0.002400–$12.000000 USD / call · docs: https://twitr.sh/tools/x_inbox)
- `x_profile` — Edit a connected X/Twitter account's profile: display name, bio, location, website link, avatar image, and banner image. Acts only on handles this wallet connected. ($0.012000 USD / call · docs: https://twitr.sh/tools/x_profile)
- `x_community` — Manage X/Twitter Communities as a connected account: create a new community, join or leave an existing one, or delete a community you own. ($0.012000–$0.036000 USD / call · docs: https://twitr.sh/tools/x_community)
- `x_radar` — Trending topics and breaking stories across tech, dev, science, business, culture, politics, and entertainment — aggregated from multiple public sources with regional and time-window filters. Flat sub-cent price per call; the cheap first stop for what is happening right now. ($0.002400 USD / call · docs: https://twitr.sh/tools/radar)
- `x_compose` — Draft tweets with AI: generate variants from a topic and goal, refine an existing draft, or score a draft for likely engagement — with tone, call-to-action, and style-matching options. Flat sub-cent price per step. ($0.002400 USD / call · docs: https://twitr.sh/tools/compose)

## 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

- Full tool reference (params, prices, examples): https://twitr.sh/llms-full.txt
- 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

## Free tools (for people, in the browser)

- [Twitter shadowban checker](https://twitr.sh/twitter-shadowban-checker) — Check any X account for a search ban, search suggestion ban, ghost ban, suspension, sensitive-media label and country blocks. Six checks, each with a link to verify it on X.
- [X algorithm checker](https://twitr.sh/x-algorithm-checker) — Is the X algorithm working for you? Your last 40 posts scored by Jev on what the For You ranker rewards, plus your reach trend and what to fix first.
- [Twitter viewer](https://twitr.sh/twitter-viewer) — View any public X (Twitter) profile without an account: bio, follower counts and the latest 20 posts with views, likes, replies and reposts. Free, no login.
- [Twitter trends](https://twitr.sh/twitter-trends) — Live X (Twitter) trends for the world and 19 countries: the top topics ranked by X, each linked to its search on X. Refreshed about every hour, no login.
- [Twitter advanced search](https://twitr.sh/twitter-advanced-search) — Build any X advanced search in seconds: dates, accounts, exact phrases, minimum likes, language and media. Open it on X, copy it, or run it here without an account.
- [Twitter follow checker](https://twitr.sh/twitter-follow-checker) — Does @a follow @b? Check any two X accounts in both directions and spot mutuals. Nobody is notified, no login.
- [Twitter thread reader](https://twitr.sh/twitter-thread-reader) — Paste a post link and read the whole X thread as clean, numbered text: the author's posts only, in order, media noted, and one click to copy it all.
- [Twitter ID finder](https://twitr.sh/twitter-id-finder) — Turn any X username or profile link into its permanent numeric user ID, or an ID back into the current handle. Copy it as text or JSON.
- [Twitter giveaway picker](https://twitr.sh/twitter-giveaway-picker) — Pick random, provably fair winners from a post's replies, with repost, follow, keyword, follower and account-age rules. Priced before you run it.
- [x402 doctor](https://twitr.sh/products/x402-doctor) — Paste any x402 seller's origin and grade its 402 challenge — CAIP-2 legality, Solana feePayer, spend caps, and whether anything can discover it. Read-only; never sends a payment.

## Guides

- [How to search tweets by date](https://twitr.sh/how-to-search-tweets-by-date)
- [How to search old tweets and your archive](https://twitr.sh/how-to-search-old-tweets)
- [How to see deleted tweets](https://twitr.sh/how-to-see-deleted-tweets)
- [Does X show who viewed your profile?](https://twitr.sh/does-x-show-who-viewed-your-profile)
- [Who blocked me on X?](https://twitr.sh/who-blocked-me-on-x)
- [X rate limit exceeded: what it means](https://twitr.sh/x-rate-limit-exceeded)
- [X API pricing in 2026](https://twitr.sh/x-api-pricing)
- [Twitter API vs twitr.sh](https://twitr.sh/twitter-api-vs-twitr)
- [X API alternatives](https://twitr.sh/x-api-alternatives)
- [twitterapi.io alternative](https://twitr.sh/twitterapi-io-alternative)
- [Apify Twitter scraper alternative](https://twitr.sh/apify-twitter-scraper-alternative)
- [Tweet Binder alternative](https://twitr.sh/tweetbinder-alternative)
- [Twitter scraper API](https://twitr.sh/twitter-scraper-api)
- [Connect Claude to Twitter (X)](https://twitr.sh/connect-claude-to-twitter)
- [Twitter monitoring tool and keyword alerts](https://twitr.sh/twitter-monitoring-tool)
- [How to get an X API key (or skip it)](https://twitr.sh/x-api-key)
- [The Twitter/X API for AI agents](https://twitr.sh/twitter-api-for-ai-agents)
- [x402 Twitter API](https://twitr.sh/x402-twitter-api)