twitter-research

A read-only research toolkit for Twitter/X, backed by SELAT's own first-party Twitter API (catalog.selat.ai). The manifest wires 9 GET reads at $0.001 each. selat skill run always runs all 9 (about $0.009). When a request needs only one or two reads, the agent pays just those with individual selat-pay calls. No API keys, keyless pay-per-call.

When To Use

Use for read/lookup tasks on X: profiling an account, pulling someone's recent posts, seeing who mentions or follows them, analyzing how a specific tweet landed (replies + retweeters), searching for a topic/keyword, or checking regional trends. Read-only — it does not post, like, or follow, and cannot see protected/private accounts.

Workflow

selat skill run twitter-research runs all 9 steps, every time. The runner has no step-selection flag. Any param you don't pass falls back to its default (openai, AI agents, tweet 20, worldwide trends), so a full run also pays for reads you didn't ask about. Pick the path that fits the request.

1. Install: selat skill install twitter-research
2. Map the request to the reads it needs (table below), then tell the user the cost and wait for a yes — "this is N SELAT-native Twitter reads, about $0.00N — go ahead?"
3. Run it one of two ways:
   • All 9 reads (~$0.009): use this for a broad sweep, or when the request touches most of the table. Pass every param so no default leaks in: selat skill run twitter-research --handle <handle> --query "<query>" --tweetId <id> --woeid <woeid>
   • Only the reads you need ($0.001 each): pay each selected URL from the table in references/endpoints.md with its own selat-pay call. For example: selat-pay GET "https://catalog.selat.ai/twitter/user/info?userName=<handle>" --chain <chain holding your Gateway balance> --max-amount 0.01 A paid selat-pay call needs an armed session budget (selat budget start). Its --chain names the chain holding your Gateway balance; don't hardcode one.
4. Synthesize for the user in plain language: give the answer, not the JSON. Lead with the finding and the dollar cost. Keep endpoint URLs, wallet addresses, and tweet IDs out of what you relay.

• Start with the one read that answers the ask. Add a second (e.g. user/mentions after user/info) only if the user wants more.
• advanced_search accepts the full X operator surface in query (from:, to:, #tag, $CASHTAG, min_faves:, since:/until:, lang:en).

Inputs And Outputs

Output: per-step JSON (all 9 on a full run, or just the reads you paid for), which the agent distills into a short answer for the user (profile summary, tweet list with engagement, mention/follower read, tweet-reception breakdown, topic chatter, or trend list — whichever was asked).

Gotchas

• selat skill run pays all 9 reads. The 9 steps are independent reads, but the runner executes every step and has no way to skip one. To pay for a subset, make the individual selat-pay calls (Workflow step 3).
• Params are per-endpoint. handle drives the user/* reads, tweetId the tweet/* reads, query the search, woeid the trends. On a full run, any param you omit uses its default, and that step still pays for the default target.
• Tweet-id param names differ per endpoint (live API, not the OpenAPI): tweets takes tweet_ids (snake_case, comma-separated batch); tweet/replies and tweet/retweeters take tweetId (camelCase). The OpenAPI's tweet_id for the latter two 400s ("tweetId is required") — the manifest uses tweetId.
• woeid is a Yahoo Where-On-Earth ID, not a country code (1 = worldwide).
• Handles have no leading @. Strip it before passing handle (the API param is userName; the manifest maps ${handle} → userName=).
• tweets batches — tweet_ids is comma-separated (20,21,22). The manifest passes one id; hand-build the call for a batch.
• Paginate via cursor. last_tweets, mentions, followers, and the reply/retweeter reads return a cursor; to fetch the next page, issue a hand-built selat-pay GET …&cursor=<token> — each page is another ~$0.001. cursor is not a manifest param. Full per-param schema (pinned from catalog.selat.ai/twitter/openapi.json) is in references/endpoints.md.
• All steps need the SELAT Router. catalog.selat.ai settles x402 via Circle Gateway through the SELAT Router, so SELAT_ROUTER_URL must be reachable.
• Read-only + public-only. No posting/engagement; protected accounts error.

Validation

--chain base in the probe commands below is only the flag selat-pay requires today — a probe reads a free, chain-independent quote and never settles. A real paid run resolves the settlement chain from your funded Circle Gateway balance, not the manifest.

• selat skill validate ./skills/twitter-research → passes.
• selat skill verify ./skills/twitter-research --live-probe → all 9 steps reachable and ≤ maxAmount (writes the verify receipt). Adding --pay runs all 9 as a settled smoke test (~$0.009).
• npm run validate → 0 errors (whole-repo + index.json consistency).

Free single-step probe (what verify runs per step — no wallet, no spend):

selat-pay GET "https://catalog.selat.ai/twitter/user/info?userName=openai" \
  --chain base --probe-only --live-probe
selat-pay GET "https://catalog.selat.ai/twitter/tweet/advanced_search?query=AI%20agents" \
  --chain base --probe-only --live-probe
# success prints: detected: x402=yes … mode=routed-x402, then price=$0.001000

References

• manifest.json — the machine-readable payment recipe this skill runs.
• references/endpoints.md — the 9 endpoints, params, rails, and live prices. Read it before building an individual selat-pay call.
• references/agent-skill-authoring-sop.md — authoring standard.
• selat-pay — https://github.com/SELAT-AI/selat-pay