# ReadX — X/Twitter JSON API

> A clean, read-only JSON mirror of X/Twitter — profiles, timelines, tweets, search, lists, followers and following. No API keys and no signup: each call is paid per request straight from an agent's own wallet (default $0.05 in USDC), via either [x402](https://x402.org) at `readx.sh` or [MPP](https://mpp.dev) at `mpp.readx.sh`.

## How to use it

- Every endpoint is a `GET` under `/api`, served on two hosts — pick the one your client speaks:
  - `https://readx.sh/api/…` — **x402**. No payment returns HTTP `402` + a `PAYMENT-REQUIRED` header; rails are USDC on Base or Solana.
  - `https://mpp.readx.sh/api/…` — **MPP**. No payment returns HTTP `402` + a `WWW-Authenticate: Payment …` header; the client retries with an `Authorization` credential and gets a `Payment-Receipt`. Rail is USDC on Base.
  - Both hosts serve identical JSON at the same price; swap the host for the same endpoint.
- Most responses are `{ "code": 0, "data": ... }` on success and `{ "code": -1, "error", "error_type" }` on error. The List endpoints return the bare object; GetXAPI routes (followers, following, articles) pass the upstream payload through verbatim.
- Paginate timelines by passing a response's `pagination.bottom` (or `replies.bottom`) cursor back as `?cursor=`. For followers/following, pass `next_cursor` as `?cursor=` until `has_more` is false. Append `?no-cache` to force fresh data.

## Machine-readable contracts

- [OpenAPI 3.1 spec — x402](https://readx.sh/openapi.json): the canonical description of every `/api` endpoint, schema, and price (`x-payment-info`), advertising the `x402` protocol.
- [OpenAPI 3.1 spec — MPP](https://mpp.readx.sh/openapi.json): the same endpoints on the MPP host, advertising the `mpp` protocol.
- [Agent skill](https://readx.sh/skill.md): a drop-in skill file. Point an x402- or MPP-capable agent at it and it learns every endpoint and the payment flow.

## Quick start

- Set up as a skill: `Set up ReadX at https://readx.sh/skill.md with x402 or MPP`
- One call over x402: `npx agentcash fetch https://readx.sh/api/jack/profile`
- One call over MPP: `npx agentcash fetch https://mpp.readx.sh/api/jack/profile`

## Key endpoints

- `GET /api/{name}/profile` — user object, photo rail, pinned tweet
- `GET /api/{name}/followers` — a user's followers (~200/page; paginate with `?cursor=` + `next_cursor`)
- `GET /api/{name}/following` — accounts a user follows (~200/page; paginate with `?cursor=` + `next_cursor`)
- `GET /api/{name}` — user timeline (also `/with_replies`, `/media`)
- `GET /api/{name}/status/{id}` — a tweet and its conversation (or `/api/status/{id}` for just the tweet)
- `GET /api/{name}/status/{id}/history` — a tweet's edit history (latest plus prior versions)
- `GET /api/search?q=...` — tweet search (a leading `@` or `f:user` returns users)
- `GET /api/lists/{id}` — a List (also `/timeline`, `/members`)
- `GET /api/articles/{id}` — an X article by wrapper tweet id (public)
- `GET /api/article-entities/{article_id}?auth_token=…` — an X article by entity rest_id (owner-only)
- `GET /api/{name}/id` — resolve an @handle to a numeric user id
- `GET /api/user/{id}` — resolve a numeric user id to a username