---
title: Quickstart — connect your agent to NanoParse
url: https://www.nanoparse.app/quickstart
description: "The full NanoParse agent manifest: MCP config, x402 payment loop, EIP-3009 signing, error codes and batch parsing. $0.002 per successful parse."
---

Quickstart · agent manifest

# Everything your agent needs,in plain text.

The MCP config, the payment flow and the response schema. Have your agent read this page and begin parsing. No SDK, no account, no setup beyond one entry.

[Try the live demo](https://www.nanoparse.app/#parse)[MCP repo](https://github.com/nanoparse-dev/nanoparse-mcp)

Paste thisMCP

mcp.json

Copy

```
{ "mcpServers": { "nanoparse": { "type": "http", "url": "https://nanoparse.app/mcp" } }}// The agent then discovers two tools:// nanoparse_fetch(url) -> markdown + metadata + litmus// nanoparse_status() -> free quota, wallet, payment state
```

base_url

https://nanoparse.app

mcp_endpoint

https://nanoparse.app/mcp

tools

nanoparse_fetch · nanoparse_status

price

$0.002 / successful parse

payment

x402 v2 · USDC on Base

free_tier

10 parses / month

latency

typically 2–8 seconds

result_ttl

6 hours, then deleted

On this page

Endpoint

https://nanoparse.app/mcp

01

## Connect via MCP

Add one entry to your MCP client config. The agent auto-discovers the tools — no SDK, no setup beyond this. Works with Claude Code, Cursor, Windsurf and any MCP host.

mcp.json

Copy

```
{ "mcpServers": { "nanoparse": { "type": "http", "url": "https://nanoparse.app/mcp" } }}// The agent then discovers two tools:// nanoparse_fetch(url) -> markdown + metadata + litmus// nanoparse_status() -> free quota, wallet, payment state
```

`nanoparse_fetch(url)`

Parse a URL into Markdown + Litmus. Payment, when needed, arrives at params._meta['x402/payment'].

`nanoparse_status()`

Free quota, wallet and USDC balance, payment state.

02

## Pay per parse with x402

You get 10 free parses a month with no account and no key. After that, the tool returns an x402 v2 payment challenge: the wallet signs a $0.002 USDC authorization on Base and retries. No checkout page, no human in the loop. Settlement happens only after the parse succeeds.

Claim the 10 free parses

Sign this exact string with any Ethereum wallet (EIP-191 personal_sign). No payment, no account, no key — the signature is the proof of identity.

nanoparse.app free tier: sign this message to claim 10 free parses (no payment).

1

### The payment challenge

When the free tier is exhausted, nanoparse_fetch returns an isError result whose structuredContent is the PaymentRequired object.

402 response

Copy

```
{ "x402Version": 2, "resource": { "url": "https://nanoparse.app/fetch", "mimeType": "application/json" }, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "2000", "payTo": "0x57a1d06873db575baeae1f6af30862a75c7bd570", "maxTimeoutSeconds": 60, "extra": { "assetTransferMethod": "eip3009", "name": "USD Coin", "version": "2" } }]}
```

2

### Sign with EIP-712

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.

sign.ts

Copy

```
// signTypedData over the authorization fields (viem shown)const domain = { name: "USD Coin", // extra.name — NOT the ticker "USDC" version: "2", chainId: 8453, verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",};const 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" }, ],};const signature = await wallet.signTypedData({ domain, types, primaryType: "TransferWithAuthorization", message: authorization,});
```

3

### Retry with the payment attached

Send the signed envelope at params._meta['x402/payment'] (x402 v2 MCP transport). Settlement rides back at _meta['x402/payment-response'].

retry.json

Copy

```
// x402 v2 MCP transport: attach the envelope at params._meta{ "name": "nanoparse_fetch", "arguments": { "url": "https://example.com" }, "_meta": { "x402/payment": <signed PaymentPayload> }}// Success returns markdown + metadata + litmus, with settlement at// _meta["x402/payment-response"]:"payment": { "status": "settled", "transaction": "0x…", "network": "eip155:8453", "payer": "0x…"}
```

No wallet? Run `npx @coinbase/payments-mcp`. The agent gets a Coinbase wallet, funds it via Apple Pay, and pays automatically.

03

## Multi-parse a list of URLs

Hand your agent a list and it works through it on its own. One call per page, $0.002 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.

batch.py

Copy

```
# 1. Build the URL list. A sitemap is a free public file.urls = fetch_sitemap("https://docs.example.com")# 2. One call per page. $0.002 each, charged only after a 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 = pages x $0.002. Nothing prepaid, nothing held.
```

150 pages ≈ $0.3010 free includedno commitment

Refusals

## Error codes, in plain words.

Every failure is explicit. Failed parses are never charged, and retries with the same envelope are idempotent.

`insufficient_usdc`

Wallet balance too low. Fund at least $0.002 USDC on Base.

`invalid_payment`

Signature or payload rejected. Often a reused authorization, or wrong extra.name.

`permit_expired`

validBefore passed before settlement. Sign a fresh envelope.

`settlement_failed`

Ambiguous settle. Retry with the same envelope — retries are idempotent.

`screening_declined`

Declined by compliance screening. No funds moved.

`content_insufficient`

Page rendered but yielded under 50 words. Not charged — try another URL.

Ready to run it?

Three free demos in the browser, no wallet needed.

[Open the demo](https://www.nanoparse.app/#parse)

![](https://www.nanoparse.app/brand/nanoparse-logo-official.svg)

## Your agent can start in one config.

Add the MCP server. Ten free parses a month. Then $0.002 per successful parse, settled in USDC on Base.

[Run a free test](https://www.nanoparse.app/#parse)[See the 20 signals](https://www.nanoparse.app/litmus)

10 free parses a month · no account · no API key
