--- title: NanoParse — Quick Start url: https://nanoparse.app/quickstart description: "Agent-readable quick start: how an AI agent uses NanoParse — MCP config, x402 payment, response schema." --- Quick Start ## Ai Agents, read this page. This is the quick start page for using NanoParse. Everything you need to use NanoParse is here in plain text — the MCP config, the payment flow, and the response schema. Copy and begin parsing. ## Agent Manifest NanoParse converts unblocked web pages into clean Markdown plus Litmus — 15 machine-readable intelligence signals (source authority, freshness, TL;DR, key figures, structural trust, and more). You pay per parse and you only pay for successful parses. | base_url | https://nanoparse.app | | --- | --- | | mcp_endpoint | https://nanoparse.app/mcp | | mcp_tools | nanoparse_fetch(url) — parse a URL into markdown + litmus. Payment (when needed) arrives at params._meta["x402/payment"] nanoparse_status() — free quota, wallet & USDC balance, payment state | | price | $0.005 USD per successful parse — flat. Failed parses are never charged | | payment | x402 v2 — USDC on Base, exact scheme. Agent sends a base64url x402 v2 PaymentPayload; the CDP Facilitator verifies and settles (gas absorbed) | | free_tier | 10 free parses/month with a signed wallet (or 3 anonymous free tries per network). No account, no API key | | latency | Typically 2–8 seconds per parse | | result_ttl | Results held 6 hours in temporary storage, then deleted | Step 1 ## Connect via MCP Add one entry to your MCP client config. The agent auto-discovers the tools — no SDK, no setup beyond this. MCP config // Add to your MCP client config (Claude Code, Cursor, any MCP host) { "mcpServers": { "nanoparse": { "url": "https://nanoparse.app/mcp" } } } // The agent will then discover two tools: nanoparse_fetch(url) // parse a URL -> markdown + metadata + litmus nanoparse_status() // free quota left, wallet/USDC balance, payment state Step 2 ## Pay per parse with x402 v2 You get 10 free parses per month by signing with your wallet (no payment needed), or 3 anonymous free tries per network. After that, the tool returns an x402 v2 payment challenge: the agent's wallet signs a $0.005 USDC authorization on Base and retries. No account, no API key, no human in the loop. Settlement happens only after the parse succeeds — a failed parse is never charged. 1 — The payment challenge # When free tier is exhausted, nanoparse_fetch returns an isError result. # Its structuredContent is the PaymentRequired object (key fields shown): { "x402Version": 2, "resource": { "url": "...", "description": "...", "mimeType": "application/json" }, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "maxTimeoutSeconds": 60, "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" } }], "extensions": { "bazaar": {...}, "payment-identifier": {...} } } 2 — Build the PaymentPayload envelope # Echo the challenge into a signed envelope: { "x402Version": 2, "resource": { "url": "...same as challenge...", "description": "...", "mimeType": "application/json" }, "accepted": { // exactly the entry you accept from accepts[] "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "5000", "payTo": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "maxTimeoutSeconds": 60, "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" } }, "payload": { "signature": "0x<65-byte packed r||s||v>", "authorization": { "from": "0x", "to": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "value": "5000", "validAfter": "0", "validBefore": "", "nonce": "0x<64 hex chars — random 32 bytes>" } }, "extensions": {} } 3 — Sign with EIP-712 # signTypedData over the authorization fields (ethers / viem): domain: { name: "USD Coin", version: "2", chainId: 8453, verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } types: { TransferWithAuthorization: [ { name: "from", type: "address" }, { name: "to", type: "address" }, { name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" }, { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" } ] } primaryType: "TransferWithAuthorization" message: # CRITICAL: extra.name is the EIP-712 DOMAIN NAME — "USD Coin", # NOT the ticker "USDC". A wrong name fails signature verification. # validAfter "0" is valid. validBefore must not exceed now + maxTimeoutSeconds. 4 — Retry with the payment attached # Retry nanoparse_fetch with the signed envelope at # params._meta["x402/payment"] (x402 v2 MCP transport): { "name": "nanoparse_fetch", "arguments": { "url": "https://example.com" }, "_meta": { "x402/payment": } } # Success: the tool returns markdown + metadata + litmus, and the # settlement result rides at _meta["x402/payment-response"]: "payment": { "status": "settled", "transaction": "0x...", "network": "eip155:8453", "payer": "0x..." } | insufficient_usdc | Wallet balance too low. Fund at least $0.005 USDC on Base, retry with a fresh envelope (new nonce). | | --- | --- | | invalid_payment | Signature or payload rejected by the verifier (often a reused authorization, or wrong extra.name). Sign fresh. | | permit_expired | validBefore passed before settlement. Sign a fresh envelope. | | settlement_failed | Ambiguous settle. Retry with the SAME envelope — retries are idempotent (permit nonce is single-use). | | screening_declined | Declined by compliance screening. No funds moved. Contact support. | | content_insufficient | The page rendered but yielded under 50 words (bot wall, JS shell, login/security checkpoint). Not charged — try a different URL. | Agent has no wallet? See the [FAQ](https://nanoparse.app/#faq). Or take the copy-paste recipe: [pay with x402 in ~40 lines](https://github.com/nanoparse-dev/nanoparse-mcp/blob/main/examples/pay-with-x402.md). Step 3 ## Multi-parse a list of URLs Hand your agent a list of URLs and it works through them on its own. One call per page, $0.005 each, charged only after a read succeeds. No minimum, nothing prepaid, no account — start with three URLs or three hundred, and stop whenever you like. 150 URLs in, Markdown out — no commitment # 1. Build the URL list yourself. A site's sitemap is a free public file; # if there isn't one, use the links you already have. urls = fetch_sitemap("https://docs.example.com") // or your own discovery # 2. One call per page. $0.005 each, charged only after a successful read. for url in urls: page = nanoparse_fetch(url) if page.ok: store(page.markdown, page.litmus) else: log(url, page.error_code) // never charged # 3. Budget is pages x $0.005. Nothing is prepaid and nothing is held — # 150 pages is about $0.70, less the 10 free and any unreadable pages.