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: the wallet is the account, or use an API key with a card balance. Agents plug in over HTTP or MCP.

01 — quickstart

Quickstart

Three steps: install the skills into your agent, connect a wallet, and ask. Pick your agent and your wallet — everything below updates to that combination. Building against the raw API instead? The HTTP flow is under Machine specs.

your agent

your wallet

recommended — Base · Solana · Tempo

1
Add the skills
```
npx skills add lnvestor/twitr-skills
```
Restart the Claude Code session after installing so the skills load. Running scheduled cycles on Claude Code web routines? Include the AgentCash connector — see the scheduling reference inside the x-presence skill.
2
Connect the wallet
Add AgentCash as an MCP server (available in every session):
```
claude mcp add agentcash --scope user -- npx -y agentcash@latest
```
New to AgentCash? Visit agentcash.dev/onboard first — connecting GitHub/X/LinkedIn earns a claim code worth up to $25 in free USDC.
3
Say this to your agent
“What is my AgentCash balance?”— confirms the wallet is wired up
“What's trending in tech right now?”
“What is @vercel posting about this week?”
“Watch @competitor and tell me when they announce something.”
The first paid call answers with a 402 quoting the exact price — that's the quote, not an error; your wallet signs it and the data comes back. Failed calls are never charged.

02 — payment

How payment works

You pay per request — no subscription. Two on-chain rails in USDC, plus an optional API key backed by a card balance:

x402

USDC on Base · Solana

The client signs a payment authorization into the X-PAYMENT header; we verify, run the call, and settle.

MPP

USDC on Tempo

Answered via the Authorization: Payment challenge; same pay-and-retry loop.

API key

Card balance

Send Authorization: Bearer tw_live_…; each call is charged to the balance you add in the dashboard.

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 never charged. Validation happens before payment, and a failed data fetch refunds the attempt — the wallet only pays for data that arrives.

Sign in (free) with your wallet or Google to see your run history, balance and API keys in the dashboard or over the API.

03 — tools

Tools

14 tools, each priced per call or per returned item. Per-result reads use Base, charge only returned records, and cost $0 when empty ($0.0024 minimum otherwise). Full input schemas live in the OpenAPI spec.

X/Twitter 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.0024–$1.20

X/Twitter 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.0024–$1.20

X/Twitter 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.0024–$1.20

X/Twitter 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.0024–$1.20

X/Twitter 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.0024–$1.20

X/Twitter Bulk Export

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.0024–$60.00

X/Twitter 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.0264–$4.2348

X/Twitter Giveaway 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.0024–$84.0012

X/Twitter 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.006–$0.036

X/Twitter 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.0024–$12.00

X/Twitter Profile Editor

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.012

X/Twitter Community Manager

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.012–$0.036

Trend 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.0024

AI Tweet Composer

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.0024

04 — monitors

Monitors

A monitor watches one X account or one keyword query in real time. 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.

Monitors are prepaid by the hour (about $0.025/hr) and stop at expires_at unless extended — no open-ended billing, and early deletion does not refund. Max 168 hours per purchase, 720 hours of forward window.

say this to your agent

“Watch @vercel for the next 24 hours and tell me the moment they post.”

“Monitor the phrase “launch week” for a day and summarize what shows up.”

“Extend my monitor by 48 hours before it expires.”

under the hood — raw HTTP

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

05 — events

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

pull

Poll the events feed

GET /api/monitors/{id}/events?after=… — strictly newer events, oldest first. 500 events / 24h retained, 60 reads/min.

push

Signed webhooks

say this to your agent

“Register a webhook at https://my-agent.example/hooks for my monitor's new-tweet events.”

“Check my monitor's events from the last hour and summarize them.”— polling is free

Verify every delivery. Recompute HMAC-SHA256(secret, timestamp.rawBody) and constant-time-compare to X-Twitr-Signature; reject timestamps older than 5 minutes; dedupe on delivery_id and id; respond 2xx within 10 seconds. Retries back off over ~36 minutes; 50 consecutive failures auto-pause the webhook and a successful /test re-activates it.

under the hood — a signed delivery

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

06 — accounts

Connecting an X account

Write tools (post, like, follow, DM, profile, community) act through an X account you connect once. Here is exactly what happens:

say this to your agent

“Connect my X account @yourhandle.”— free — your agent replies with a link to sign in

“Post “shipping day” as @yourhandle.”

“Reply to that tweet as @yourhandle and thank them.”

Your agent should never ask for your X password — if one ever does, stop. The real flow is a link you open yourself; any verification code X emails you is entered on that same page. A write that answers pending_confirmation is still running: wait, never resend. One handle belongs to exactly one wallet, and ownership is re-checked server-side on every write.

under the hood — raw HTTP

# 1) mint a connect link (free, wallet-signed). NO credentials here, ever.
POST /api/x-accounts/start   {"username":"yourhandle"}
# -> 200 {connect_url:"https://twitr.sh/connect/<token>", expires_in:1800}
#    show connect_url to the user — they sign in to X in their own browser

# 2) poll until the handle links (the user may enter an emailed code on that page)
GET  /api/x-accounts
# -> {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"}

07 — errors

Errors & retries

Every non-2xx body is an RFC 9457 Problem (application/problem+json) extended with two machine-actionable fields: retryable — whether the same request, unchanged, may succeed if retried later — and hint, one concrete next step.

Failed calls are never charged, so retrying on retryable: true is always safe. 429s carry a Retry-After header; a 404 for a wrong tool name lists valid_tools so a bad guess self-heals in one read.

example: 400 on a volume tool without resultsLimit

{
  "type": "https://paymentauth.org/problems/records-cap-required",
  "title": "Records Cap Required",
  "status": 400,
  "detail": "This operation is billed per returned item and requires resultsLimit…",
  "retryable": false,
  "hint": "Add resultsLimit (integer 1-10000) to the request body."
}

An unknown tool name is rare in practice: the MCP tool names (x_radar, x_draws, x_compose) are accepted as aliases of their route paths, so the natural guess resolves.

08 — specs

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

raw HTTP — for API builders

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