X Twitter Data

X data — reads, search, timelines

| Task | Tool | |---|---| | One tweet, profile, article, follow-check, trends | POST /api/tools/x_read | | Search tweets or users | POST /api/tools/x_search | | Timelines, follower graphs, engagement lists | POST /api/tools/x_timeline | | List timelines, members, followers | POST /api/tools/x_lists | | Community info, members, posts, in-community search | POST /api/tools/x_communities | | Trending topics by region/category | POST /api/tools/radar (tool name x_radar; category: general\|tech\|dev\|science\|culture\|politics\|business\|entertainment) |

Base URL https://twitr.sh. Every call is one POST. Prices are per returned item on the volume tools, ~$0.0012 per unit, floor $0.001.

Calling it

The first request returns 402 with the exact price; an x402 client pays and retries automatically. With AgentCash MCP:

mcp__agentcash__fetch({
  url: "https://twitr.sh/api/tools/x_search",
  method: "POST",
  body: { kind: "tweets", q: "from:vercel launch", resultsLimit: 50 }
})

Read amount and breakdown from the 402 before signing. Tell the user the cost for anything non-trivial, and confirm above ~$0.10.

Gotchas

• resultsLimit is mandatory on volume tools (search, timelines, lists, some reads) — the

call is rejected before charging without it. It's also the spend rail: you pay per returned item, so resultsLimit: 1000 is a ~$1.20 call.

• Failed calls are never charged. A 4xx/5xx costs nothing, so retry freely on errors.
• User ids are numeric, not handles. Anything taking a user id wants the numeric form —

get it from x_read {"resource":"get-user","username":"..."}.

• x_read batch mode takes up to 100 ids in one call, far cheaper than 100 single calls.
• x_radar is priced at the floor ($0.001), so trend checks are effectively free — use it

before search when the question is "what's happening".

Avoid

• Don't paginate blindly to "get everything" — set resultsLimit to what's actually needed.
• Don't call a read repeatedly for the same id in one session; cache it in context.
• Don't use this for datasets over a few hundred rows — x-twitter-research runs those async and

returns a downloadable file instead of flooding context.

Full API: https://twitr.sh/skill.md · https://twitr.sh/docs · https://twitr.sh/openapi.json

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lnvestor
• Source: lnvestor/twitr-skills
• License: MIT
• Homepage: twitr.sh

Install and usage instructions live in the source repository linked above.