# readfetch — read the web, per call

`https://readfetch.com` — a reading service for agents. No account, no API key: pay per call in USDC
over x402, and only when content is delivered.

## Pick by intent

Prices are in the next table, generated from the catalog — never trust a price you saw in
prose.

| You want | Call |
|---|---|
| the article on one URL | `POST /v1/text` |
| to know whether a page is worth reading | `POST /v1/probe` |
| the links on a site | `POST /v1/map` |
| a page that only renders with JavaScript | `POST /v1/scrape` |
| a page that blocks datacentres | `POST /v1/scrape/residential` |
| the raw response, status included | `POST /v1/fetch` |
| many URLs in one call | `POST /v1/batch` |
| text out of a PDF | `POST /v1/pdf` |
| one section of a page | `POST /v1/section` |
| what changed between two fetches | `POST /v1/diff` |
| a picture of the page | `POST /v1/screenshot` |
| web search results | `POST /v1/search` |
| a whole site, a few pages deep | `POST /v1/crawl` |

Start cheap: `/v1/probe` is free and tells you the status, title, size and whether a bot wall
will answer. If it says `challenge: true`, go to `/v1/scrape` (or `/v1/scrape/residential`),
not `/v1/text`.

## Every endpoint

| `/v1/text` | POST | $0.005 | Article text and metadata, boilerplate stripped. No browser by default; falls back to one when a page blocks plain HTTP. |
| `/v1/map` | POST | $0.005 | Sitemaps, robots rules, feeds and link counts for a whole site, in one call. Plan a crawl before paying for it. |
| `/v1/scrape` | POST | $0.005 | Chromium renders the page, runs interactions, and returns Markdown, text or HTML with its links. |
| `/v1/scrape/residential` | POST | $0.02 | Scrape through a rotating residential exit, for targets that refuse a datacentre address. Same contract as /v1/scrape, one attempt, priced for the bandwidth. |
| `/v1/fetch` | POST | $0.003 | Raw HTTP through the same egress. JSON APIs, GraphQL, PDFs, byte ranges - anything that is not a page. |
| `/v1/batch` | POST | $0.0015/page | Up to 50 URLs in one call and one payment. Results in input order; undelivered pages come back as credit. |
| `/v1/pdf` | POST | $0.005/document | Documents, not pages: page text plus one Markdown body, priced per document rather than per page. |
| `/v1/section` | POST | $0.003 | Read one heading or one selector instead of the whole page - ten to a hundred times fewer tokens. |
| `/v1/diff` | POST | $0.003 | Stateless change detection. Send the hash you hold, get back whether it changed and a bounded diff. |
| `/v1/screenshot` | POST | $0.003 | PNG, JPEG or PDF of a rendered page: viewport, full page, or a single element. |
| `/v1/search` | POST | $0.005 | Web search without a search subscription, returning titles, URLs and snippets. |
| `/v1/crawl` | POST | $0.003/page | Bounded async crawl with a job id, a page cap quoted up front, and per-page Markdown. |
| `/v1/probe` | POST | free | Metadata before spending: status, type, title, size, language, whether a bot wall is waiting. No page body. |

Full request fields and examples: `https://readfetch.com/llms.txt`, `https://readfetch.com/openapi.json`.
The same endpoints are exposed as MCP tools at `https://readfetch.com/mcp` (see below).

## Paying

1. Call without payment. You get `402` plus a `PAYMENT-REQUIRED` header: base64 JSON with an
   `accepts[]` entry quoting `amount` (atomic USDC), `payTo`, `asset`, `network`, `resource`.
2. Sign an EIP-3009 `TransferWithAuthorization` for exactly that amount and resend the same call
   with `PAYMENT-SIGNATURE: base64(json)`.
3. A delivered response carries `PAYMENT-RESPONSE` (settlement, with `transaction`) and `RECEIPT`
   (our signed receipt, needed for claims).
4. A response with `billed: false` was **not charged**. Read its `hint`.

In test mode (`payment.status: "test-mode"`) any non-empty `x-payment-proof` header passes and
nothing settles. Use that while building.

## Free tier

There is no free daily tier on this instance: every published endpoint except
`/v1/probe` answers 402 first and is charged on delivery. The `X-FREE-TIER: <left>/<n>`
header only appears on an instance that has a tier enabled.

## When a call fails

| Symptom | What it means | Next call |
|---|---|---|
| `billed: false` with `hint` | not charged; the hint names the fix | follow the hint |
| `402` | payment required | sign `accepts[0]` and retry |
| `429` with `Retry-After` | rate limited | wait, then retry the same call |
| `502` / `503` | upstream or us, nothing charged | retry once; then `/v1/probe` |
| `challenge: true` in a 200 | a bot wall answered | `/v1/scrape`, then `/v1/scrape/residential` |
| `text` empty or nav-only | the page needs JavaScript | `/v1/scrape` |
| `used_browser: true` | the HTTP path was blocked and one render rescued it | nothing, it delivered |
| wrong language / geo | the exit is one region | accept `accept_language`, or use `advanced.locale` on `/v1/scrape` |
| a PDF answered as HTML | it is not a PDF | `/v1/pdf` only accepts `%PDF-` bodies |
| one page is too big | capped, `truncated: true` | ask for less: `/v1/section` |
| "already used" on a payment | nonce replay | sign a new authorization |
| empty delivery you paid for | provable from the receipt | `POST /v1/claims` for a credit |

Claims: send `{receipt, reason, address, signature}` where the signature is EIP-191 over
`sha256(receipt || rid)`. Auto-approved reasons are `empty` and `truncated`; `wrong_content`
needs a human. A credit is a single-use `X-CREDIT` header worth one call.

## MCP

`POST https://readfetch.com/mcp` — streamable HTTP, JSON-RPC 2.0, one tool per endpoint, named
`readfetch_<endpoint>` (`readfetch_text`, `readfetch_scrape`, `readfetch_probe`, …).
`tools/list` is generated from the same catalog as the REST surface, so the two cannot drift.
Tool calls ride the same 402 flow: an unpaid call returns `isError` with the quote in
`structuredContent`, and the retry carries `PAYMENT-SIGNATURE` on the MCP HTTP request.
Tool list: `https://readfetch.com/.well-known/mcp.json`.

## Limits that matter

- Body: 1 MiB request, JSON only.
- `/v1/batch`: 50 URLs, 8 in flight, 120 s.
- `/v1/pdf`: 50 pages by default, 200 max, 20 MB.
- `/v1/probe`: 30/min and 2/s per IP; free.
- `/v1/crawl`: bounded by `max_pages`; billed per delivered page.
- Receipts and credits last 30 days; claims are capped at 5 per address per day, $0.05 each.