# Avo Cado Read API

Web page to clean Markdown for AI agents, paid per call with USDC on Base via x402 (no account, no API key).

## Endpoints
- `GET https://avocado-read-api.a-347.workers.dev/read?url=<public http(s) URL>`: $0.003 per call. Returns JSON: url, finalUrl, title, byline, siteName, lang, excerpt, markdown, wordCount, links[{text,href}], fetchedAt, truncated, cached.
- `GET https://avocado-read-api.a-347.workers.dev/ping`: $0.001, paid connectivity test.

## MCP (remote server)
Streamable HTTP MCP endpoint: `https://avocado-read-api.a-347.workers.dev/mcp` (stateless, JSON responses). Tools:
- `read_url` {url}: $0.003 via x402 MCP payments (payment in `_meta["x402/payment"]`; use @x402/mcp `createx402MCPClient`). Not charged if the page cannot be read.
- `pricing`: free.

```js
import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const mcp = createx402MCPClient({ name: "my-agent", version: "1.0.0", schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }], autoPayment: true });
await mcp.connect(new StreamableHTTPClientTransport(new URL("https://avocado-read-api.a-347.workers.dev/mcp")));
const r = await mcp.callTool("read_url", { url: "https://example.com" });
```

## Paying (HTTP)
Call without payment to get HTTP 402 with a PAYMENT-REQUIRED header (x402 v2, scheme "exact", network eip155:8453, USDC). Retry with a PAYMENT-SIGNATURE header using any x402 client, e.g. @x402/fetch:

```js
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
const f = wrapFetchWithPayment(fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
const page = await (await f("https://avocado-read-api.a-347.workers.dev/read?url=https://example.com")).json();
```

## Policy
- Respects robots.txt (user-agent token AvoCadoReader). No logins, paywalls or captcha bypass.
- Private/internal addresses are refused. Refused or failed fetches are free (4xx/5xx are never settled).
- Limits: 8 s fetch timeout, 2 MB page size, results cached for 1 h.

Discovery: https://avocado-read-api.a-347.workers.dev/openapi.json · https://avocado-read-api.a-347.workers.dev/.well-known/x402 · https://avocado-read-api.a-347.workers.dev/.well-known/mcp/server-card.json