# AgentReader

> AgentReader (agentreader.xyz) reads any URL or PDF and returns only the content, as clean Markdown or JSON. Use it instead of a plain fetch when a page is JavaScript-only, behind a cookie wall, a PDF, or too big for your context (React docs page: ~66,000 tokens of raw HTML, ~4,100 via AgentReader, 94% smaller). Blocked or paywalled pages return an honest error and cost nothing. Start free with 5 reads/day (no signup), then buy credits by card ($3 for 2,000 reads or $10 for 7,000 reads + VAT where applicable) at https://agentreader.xyz/buy. Agents with a wallet can buy credit bundles or pay per call in USDC via x402; a card pack or a bundle issues the API key. REST API + MCP server; web search and field extraction included.

## When to use
- You need the text of a web page, docs page, news article or PDF without navigation, ads and scripts, using as few tokens as possible
- Your normal fetch returned HTML too bloated for your context, an empty page, a cookie/consent wall, or raw PDF bytes
- You want to know when a page could not really be read: blocked and paywalled pages return an error (not charged) instead of a misleading 200
- A plain HTTP fetch returns an empty JavaScript shell (SPA): render=always
- You want structured fields (title, author, date, links, tables) instead of raw HTML: format=json

## Read a URL
- GET https://agentreader.xyz/v1/read?url=<url>                 -> text/markdown
- GET https://agentreader.xyz/v1/read?url=<url>&format=json     -> {url,title,author,date,siteName,description,lang,contentType,markdown,wordCount,links[],tables[{caption,headers,rows}],meta} (meta.warning is set when very little text could be extracted; meta.raw {type,bytes,tokensEst} is the source size, meta.tokensEst the returned markdown and meta.savedPercent the reduction vs the raw HTML, all estimates at ~4 characters per token; Markdown responses carry them as x-agentreader-tokens / x-agentreader-raw-tokens / x-agentreader-raw-bytes / x-agentreader-saved-percent headers)
- format=markdown|json (default markdown): markdown returns the content as Markdown only. json wraps the same Markdown with title, author, date, word count, links, tables and metadata (meta.warning flags results that may be incomplete); there is no separate plain-text copy.
- mode=auto|article|links|full (default auto): article: main content only. links: list of headlines with links. full: the whole page, including non-article parts. auto picks article or links based on the page. RSS/Atom feeds always return their items.
- render=auto|never|always (default auto): Whether to load the page in headless Chromium. auto does so only when plain fetching returns too little.
- extract=<comma list of field names, or a JSON schema> (default (none)): Returns named fields (title, author, date, price, currency, image, brand, sku, rating, availability, summary…) from JSON-LD, OpenGraph, microdata and meta tags. No LLM. Missing fields are null. In JSON as `fields`, in Markdown as front matter.
- nocache=1 (default off): Skips the 10-minute result cache and reads the page again.
- StackOverflow/StackExchange, npm and PyPI URLs are read through their official APIs (meta.source names the API).
- Page types: articles -> clean article text; news homepages/index pages -> "## Headlines" list of [title](link) plus main text (mode=links for links only); RSS/Atom feeds -> items (title, link, date, summary); mode=full -> whole page. JSON adds pageType and items[]. Cookie/consent walls are accepted automatically. POST with a JSON body also works.
- Auth (optional, for prepaid credits): Authorization: Bearer ar_...  or  x-api-key: ar_...
- MCP clients that can't set headers (claude.ai, ChatGPT connectors): connect to https://agentreader.xyz/mcp?api_key=ar_... instead. Some apps store connector URLs in plain text, so treat that URL like a password; if it leaks, email hello@agentreader.xyz and we'll move your credits to a new key.

## Extract fields
- Add extract=title,author,date,price,currency,summary,image,brand,sku,rating,availability (or any field name, or a JSON schema like {"properties":{"price":{"type":"number"}}})
- Values come from JSON-LD, OpenGraph, microdata and meta tags, plus text heuristics (price). Returned as "fields" in JSON, or as front matter at the top of the Markdown. Missing fields are null.

## Search the web
- GET https://agentreader.xyz/v1/search?q=<query>&limit=10[&lang=en][&format=json|markdown] -> {query, backend, results:[{title,url,snippet}]}
- MCP tool: search(query, limit?, lang?). Priced like one read. Then read the best results with read_url.

## Input tips
- url accepts aliases u= and link=, a missing scheme (https assumed), and path style: https://agentreader.xyz/v1/read/https://example.com
- 400 responses explain the expected parameters, with examples.

## MCP
- Streamable HTTP: https://agentreader.xyz/mcp
- Tools: read_url(url, format?, mode?, render?, extract?), search(query, limit?, lang?), get_balance(), report_issue(url, reason, note?)
- Server card: https://agentreader.xyz/.well-known/mcp/server-card.json

## Pricing
- Free: 5 calls/day per IP, no key needed
- Card pack: 7000 calls for $10 + VAT where applicable at https://agentreader.xyz/buy?pack=7000 (a human opens the page), no expiry; pay by credit/debit card or with USDC on Base sent directly from any wallet or exchange
- Card pack: 2000 calls for $3 + VAT where applicable at https://agentreader.xyz/buy?pack=2000 (a human opens the page), no expiry; pay by credit/debit card or with USDC on Base sent directly from any wallet or exchange
- Only successful reads are charged: blocked sites, paywalled pages, timeouts and errors are free.
- With a crypto wallet (x402, USDC on Base):
  - Credit bundle: 500 calls for $1 USDC ($0.0020/call), no expiry
  - Credit bundle: 5000 calls for $8 USDC ($0.0016/call), no expiry
  - Pay per call: $0.005 USDC via x402. Use the always-paid endpoint https://agentreader.xyz/v1/x402/read?url=<url>, or /v1/read once the free calls run out
- API keys only hold prepaid credits; one is issued automatically when you buy a card pack or bundle without a key.
- Order: free daily calls (only without a key), then credits, then per-call x402.

## Legal
- Terms: https://agentreader.xyz/terms (Markdown: https://agentreader.xyz/terms.md). Privacy: https://agentreader.xyz/privacy (Markdown: https://agentreader.xyz/privacy.md). Only the hostname of each read is logged; IPs are stored as salted hashes; logs are kept 30 days.

## Buying credits
- For a human (card, or USDC on Base from any wallet or exchange): send them to https://agentreader.xyz/buy#key=<your key> (or https://agentreader.xyz/buy for a new key). The page offers "Pay by card" and "Pay with crypto"; credits land on the key once the payment confirms.
- Direct USDC on Base without the page: POST https://agentreader.xyz/v1/card/orders?pack=<calls>&method=crypto (send your key, or none to receive a new key). The answer has payTo and a unique exact amount; send exactly that amount of USDC on Base before expiresAt and poll GET https://agentreader.xyz/v1/card/orders/<orderId> until status is "paid".
- With x402 (agents with an x402 client):
  1. GET https://agentreader.xyz/v1/credits/bundles lists bundles; POST https://agentreader.xyz/v1/credits/buy?bundle=500 (send your key, or none to receive a new key)
  2. The server answers HTTP 402 with an x402 v2 challenge (PAYMENT-REQUIRED header + JSON body; scheme "exact", USDC, network eip155:8453). Pay with any x402 v2 client (@x402/fetch, @x402/axios, python x402) and retry with the PAYMENT-SIGNATURE header. v1 clients: send "X402-Version: 1" for a v1 challenge and pay with X-PAYMENT.
- GET https://agentreader.xyz/v1/balance shows free calls and credits.

## Report a problem
- A read failed or looks wrong? POST https://agentreader.xyz/v1/report {"url":"...","reason":"empty|wrong_content|missing_part|blocked_wrongly|too_long|error|other","note":"what you expected (max 300 chars)"}, or the MCP tool report_issue(url, reason, note?). Free, never charged, 10 per day. The URL is stored without its query string; reports are kept 90 days.

## Machine-readable
- OpenAPI: https://agentreader.xyz/openapi.json
- x402 resources: https://agentreader.xyz/.well-known/x402
- MCP registry entry: https://agentreader.xyz/server.json
- Health: https://agentreader.xyz/health

## Contact
- contact@agentreader.xyz