AgentRead

AgentRead

Clean web content for AI agents, paid per request.

AgentRead is a Cloudflare Worker that turns public web pages into clean, structured Markdown for LLMs and autonomous agents. It is exposed as both an HTTP API and a remote MCP server. Paid operations are charged per successful request with x402 micropayments (USDC on Base). There are no accounts, API keys or subscriptions.

Free allowance: the first 5 successful extractions per day per client are free; just call without payment. Only successful extractions count, and the x-free-tier-remaining response header (MCP: _meta["agentread/free-tier"]) shows what's left. A global cap of 1,000 free calls per day protects the service. Prices and allowances are configuration, not code (see Configuration).

Use it now

Service: https://agentread.omar-cv.workers.dev · MCP: https://agentread.omar-cv.workers.dev/mcp · Listed in the official MCP Registry as io.github.omarhassanatef/agentread and on x402scan

Try the free inspection:

curl -s -X POST https://agentread.omar-cv.workers.dev/v1/inspect \

-H 'content-type: application/json' -d '{"url":"https://example.com/"}'

Add it to an MCP client (inspect_url works in any client; the paid tools need an x402-capable client such as @x402/mcp):

claude mcp add --transport http agentread https://agentread.omar-cv.workers.dev/mcp

{ "mcpServers": { "agentread": { "url": "https://agentread.omar-cv.workers.dev/mcp" } } }

Pay per call from code with an x402 client: see Paying with an x402 client and MCP. Agent-readable docs: /llms.txt, /openapi.json, /.well-known/x402.

Status: MVP, live.

- Production (Base mainnet, real USDC): https://agentread.omar-cv.workers.dev. Payments settle via the CDP facilitator to 0xb866dD8C8401438Efb29b538ec4df11b6b407Ce6.

- Testnet: no hosted testnet. npm run dev runs locally against Base Sepolia and the free x402.org facilitator.

What has been verified:

- Automated tests: all pass (237 tests, run inside the Workers runtime).

- Directory checks: both paid endpoints pass the CDP Bazaar validator (all preflight checks) and the AgentCash/x402scan discovery audit, and are registered on x402scan.

- Local smoke test (9/9): run against wrangler dev using the live x402.org facilitator. A genuinely signed payment from an unfunded wallet passes signature and requirement checks and is rejected for insufficient_balance, so the live wire path is proven up to the transfer itself.

- Production deployment: passes all smoke checks from GitHub Actions (gh workflow run CI). The live CDP facilitator authenticates AgentRead and verifies signed payments. The development network blocks the workers.dev IP range, hence the CI vantage point.

- Runs on the Workers Free plan. The deployed lite engine had no CPU-limit kills in about 180 benchmark requests on Cloudflare's edge (Free account); the readability engine was killed in up to 84% of them. See Extraction engines.

- Not yet exercised on the deployed edge: a *paid* extraction through the product Worker. The same extraction code was benchmarked on the edge, but no funded payment has gone through.

A funded payment has not yet been made (see Testnet payment demo). Read Limitations before relying on it.

---

Why an agent would pay for this

Raw HTML is mostly noise: navigation, cookie banners, ads, scripts, styling. An agent that fetches pages itself wastes tokens and has to maintain HTML cleaning, SSRF protection, encoding detection, redirect handling and size limits. AgentRead does that once and returns predictable, versioned JSON.

x402 lets an agent pay a fraction of a cent per call from its own wallet. There is no sign-up and no stored credentials. Failed extractions are not charged.

That is a hypothesis to validate, not a proven market. The service logs the numbers needed to test it (see Observability).

Architecture

AI agent ──HTTP (x402 headers)──┐          ┌── POST /v1/inspect ──────────────┐

▼ │ │ Cloudflare Worker (Hono) ▼ AI agent ──MCP Streamable HTTP──► /mcp ────┤ validate input + URL policy + DNS guard (x402 in _meta) │ (rejects bad input BEFORE any 402) │ │ ├── POST /v1/extract[/structured] │ │ └─ @x402/hono paymentMiddleware ──► facilitator /verify │ │ └── MCP paid tools ▼ └─ @x402/mcp wrapper shared operations (inspectUrl / extractUrl / extractUrlStructured) │ bounded fetch (manual redirects, re-validated each hop, timeout, byte cap) → linkedom → boilerplate removal → Readability → Turndown │ handler OK (2xx) → facilitator /settle → result + PAYMENT-RESPONSE handler failed → settlement cancelled → error (not charged)

• One Worker, no database, no queues, no containers.
• The HTTP API and MCP tools call the same operation functions and validate with the same zod schemas.
• Payments use the official x402 v2 SDKs: @x402/hono for HTTP, @x402/mcp for MCP, and @x402/evm for the exact EVM scheme. No x402 protocol logic is reimplemented here.

More detail: docs/architecture.md · docs/payments.md · docs/security.md · docs/demo.md

API

Machine-readable docs: GET / (discovery: operations, prices, limits) and GET /openapi.json (OpenAPI 3.1, generated from the zod schemas the service validates with).

All errors use one shape:

{ "error": { "code": "blocked_destination", "message": "Internal, reserved, or loopback hostnames are not allowed.", "details": {} } }

GET /health

curl -s http://localhost:8787/health

{"status":"ok","service":"agentread","version":"0.1.0","environment":"development",

"payments":{"enabled":true,"network":"eip155:84532","networkName":"Base Sepolia"}}

POST /v1/inspect: free

Checks reachability and extractability before you pay. It downloads at most 64 KB and builds no DOM. Upstream problems (timeouts, 404s, non-HTML) are reported in the 200 body as reachable: false or a limitation. Only invalid or blocked URLs return 4xx.

curl -s -X POST http://localhost:8787/v1/inspect \

-H 'content-type: application/json' \ -d '{"url":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402"}'

{

"schemaVersion": "1.0", "operation": "inspect_url", "requestedUrl": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402", "normalizedUrl": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402", "hostname": "developer.mozilla.org", "reachable": true, "statusCode": 200, "finalUrl": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/402", "redirects": 1, "contentType": "text/html", "contentLength": 209180, "isHtml": true, "title": "402 Payment Required - HTTP | MDN", "mayRequireJavaScript": false, "extractionSupported": true, "limitation": null }

POST /v1/extract: paid

Request body (JSON, max 8 KB; unknown fields are rejected):

Without payment, the response is HTTP 402. The PAYMENT-REQUIRED header carries the base64 x402 PaymentRequired object; the JSON body is a human/agent-readable summary:

curl -si -X POST http://localhost:8787/v1/extract \

-H 'content-type: application/json' -d '{"url":"https://example.com/"}'

HTTP/1.1 402 Payment Required

payment-required: eyJ4NDAyVmVyc2lvbiI6Miwi...

{"error":{"code":"payment_required","message":"This operation costs $0.003 (USDC on Base Sepolia). ...",

"details":{"operation":"extract_url","price":"$0.003","network":"eip155:84532","x402Version":2}}}

Decoded PAYMENT-REQUIRED (accepts[0]): {"scheme":"exact","network":"eip155:84532","amount":"3000","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","payTo":" ","maxTimeoutSeconds":120,...}. 3000 is $0.003 in 6-decimal USDC.

With a valid PAYMENT-SIGNATURE header, the response is 200 with a PAYMENT-RESPONSE header containing the settlement receipt:

Real output for https://example.com/ (captured Oct 2026 by running the operation code directly):

{

"schemaVersion": "1.0", "operation": "extract_url", "requestedUrl": "https://example.com/", "finalUrl": "https://example.com/", "title": "Example Domain", "description": null, "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.", "headings": [], "truncated": false, "extraction": { "method": "readability", "statusCode": 200, "contentType": "text/html", "charset": "utf-8", "redirects": 0, "bytesFetched": 577, "characters": 156, "totalCharacters": 156, "words": 25, "warnings": [], "durationMs": 854 } }

extraction.method is one of readability, main-content-fallback, body-fallback, plain-text.

POST /v1/extract/structured: paid

Same request body as /v1/extract. Returns metadata, Markdown, headings and links separately:

{

"schemaVersion": "1.0", "operation": "extract_url_structured", "requestedUrl": "...", "finalUrl": "...", "metadata": { "title": "...", "description": "...", "canonicalUrl": "...", "language": "en-GB", "siteName": "...", "byline": "...", "publishedTime": "2026-03-14T09:00:00Z" }, "markdown": "...", "headings": [{ "level": 2, "text": "Zones of the intertidal" }], "headingsTruncated": false, "links": [{ "text": "official tide tables", "url": "https://example.org/tide-tables" }], "linksTruncated": false, "truncated": false, "extraction": { "...": "same as extract_url" } }

Missing metadata is null; nothing is guessed. includeLinks affects only the Markdown; links is always returned (max 200, deduplicated, absol