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_urlhttps://nanoparse.app
mcp_endpointhttps://nanoparse.app/mcp
mcp_toolsnanoparse_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.01 USD per successful parse — flat. Failed parses are never charged
paymentx402 v2 — USDC on Base, exact scheme. Agent sends a base64url x402 v2 PaymentPayload; the CDP Facilitator verifies and settles (gas absorbed)
free_tier10 free parses per network (subnet), lifetime. No account, no API key
latencyTypically 2–8 seconds per parse
result_ttlResults 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

The first 10 parses per network (subnet) are free. After that, the tool returns an x402 v2 payment challenge: the agent's wallet signs a $0.01 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": "10000", "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": "10000", "payTo": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "maxTimeoutSeconds": 60, "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" } }, "payload": { "signature": "0x<65-byte packed r||s||v>", "authorization": { "from": "0x<your wallet>", "to": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "value": "10000", "validAfter": "0", "validBefore": "<now + maxTimeoutSeconds from the challenge>", "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: <the authorization fields above> # 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": <envelope object> } } # 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_usdcWallet balance too low. Fund at least $0.01 USDC on Base, retry with a fresh envelope (new nonce).
invalid_paymentSignature or payload rejected by the verifier (often a reused authorization, or wrong extra.name). Sign fresh.
permit_expiredvalidBefore passed before settlement. Sign a fresh envelope.
settlement_failedAmbiguous settle. Retry with the SAME envelope — retries are idempotent (permit nonce is single-use).
screening_declinedDeclined by compliance screening. No funds moved. Contact support.
content_insufficientThe 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 homepage FAQ.