# NanoParse — AI Agent Web Parser

NanoParse converts any URL into clean Markdown with a 15-signal intelligence layer for AI agents.
No accounts — POST a URL, get content + intelligence. Pay per parse via x402 (USDC on Base).

## Who This Is For
- **AI agents** that need to read and understand web pages as clean, structured text
- **Developers** building RAG pipelines, research tools, content analyzers, or agent workflows
- **Teams** that want web content without writing and maintaining Puppeteer scripts
- **Crypto-fluent users** comfortable with USDC on Base for per-parse x402 payments
- **Anyone** who wants to try it free: 10 parses per network (subnet), no wallet needed

## When to Use NanoParse
- You need **clean Markdown** from any URL, including JavaScript-heavy SPAs (full Chromium rendering)
- You want **intelligence signals** alongside content: source authority scoring, freshness detection, structural trust scoring, key figure extraction, syndication detection, paywall detection, and more
- You prefer **pay-per-parse pricing** ($0.01/parse) with no subscriptions, no accounts
- Your agent needs a **built-in MCP server** — same endpoint serves both API and MCP tool calls
- You want **compliance built in**: paywalls respected, DMCA-ready

## When NOT to Use NanoParse
- **Bulk scraping at scale** — NanoParse is designed for per-parse agent workflows, not mass crawling. If you need thousands of URLs per minute, consider a dedicated scraping pipeline.
- **Raw HTML or screenshots** — NanoParse returns Markdown only. If you need the original DOM, rendered images, or PDF exports, use a different tool.
- **Paywalled or auth-gated content** — NanoParse respects paywalls and login walls. It will not bypass subscription barriers.
- **Persistent storage of results** — Results are cached for up to 6 hours (R2) for performance, then discarded. NanoParse is not a content archive.

## How NanoParse Compares to Alternatives

| | NanoParse | Firecrawl | Jina Reader |
|---|---|---|---|
| **Pricing** | $0.01/parse (pay-per-use) | $16–599/mo (subscription) | Free (with limits) |
| **Account required** | No | Yes | No |
| **JS rendering** | Yes (Chromium) | Yes | No (static HTML only) |
| **Intelligence signals** | 15 litmus signals | None | None |
| **MCP server** | Built-in (same endpoint) | Via separate MCP | None |
| **Payment method** | x402 (USDC on Base) | Credit card | Free only |
| **Free tier** | 10 parses / network (subnet) | 1,000 credits / mo | Rate-limited |

## Base URL
https://nanoparse.app

## API Endpoint

POST /fetch

### Request
```json
{"url": "https://example.com/article", "debug": false}
```

### Response (202 Accepted — async)
```json
{
  "jobId": "9f2c1a3b...",
  "status": "queued",
  "statusUrl": "https://nanoparse.app/status?jobId=9f2c1a3b..."
}
```

Parsing is asynchronous (full Chromium render). Poll the status URL until the result is ready.

### GET /status?jobId=…
```json
{"status": "processing"}
```

```json
{
  "status": "completed",
  "markdown": "# Article Title

Full content in clean Markdown...",
  "metadata": {
    "title": "Article Title",
    "author": "Author Name",
    "description": "Meta description or OG description",
    "published": "2025-01-01T00:00:00Z",
    "image": "https://example.com/og-image.png",
    "site": "Example Site",
    "domain": "example.com",
    "wordCount": 1245
  },
  "litmus": {
    "source": { "type": "news", "authority": 0.85, "rationale": "known high-authority domain, news source" },
    "freshness": { "published": "2025-01-01", "age": "7 months ago", "stale_warning": null },
    "tldr": "A 250-char summary extracted from the page's meta description or leading paragraph.",
    "key_figures": [{"value": "$12.5M", "context": "raised in Series A..."}],
    "structural_trust_score": { "level": "high", "trust_factors": ["High-authority source"] },
    "content_type": "news_article",
    "syndication": { "detected": false, "note": null },
    "paywall": { "detected": false, "note": null }
  }
}
```

Note: results are single-read — the result object is deleted from R2 immediately after successful retrieval.

### Response (402 — Payment Required)
```json
{
  "success": false,
  "error": "payment_required",
  "price": "0.01",
  "token": "USDC",
  "network": "base",
  "recipient": "0x57a1d06873db575baeae1f6af30862a75c7bd570",
  "free_calls_used": 10,
  "free_calls_limit": 10
}
```

## Free Tier
- 10 free parses per network (subnet)
- After 10: "$0.01" per call via x402 (USDC on Base)
- No account creation required

## MCP Server
- Endpoint: https://nanoparse.app/mcp
- Tools: nanoparse_fetch(url: string, payment_signature?: string) — parse a URL into clean markdown + litmus signals; nanoparse_status() — free quota, wallet & USDC balance, payment state
- Add to MCP client config for automatic tool discovery
- Payment works in every MCP client: when free tier is exhausted the tool returns a payment_required error with payment_terms — sign them and retry with the payment_signature argument (no custom headers required)

## Performance
- **Typical latency:** 2–8 seconds per parse (Chromium rendering + content extraction)
- **Timeout:** 15-second render per request; queued jobs older than 5 minutes are dropped
- **Caching:** Results cached for up to 6 hours (R2); repeat requests for the same URL return instantly
- **Concurrency:** No hard cap, but heavy concurrent load may experience queuing

## Features
- Full Chromium rendering (handles JavaScript SPAs)
- 15-signal intelligence layer: source authority scoring, freshness detection, structural trust scoring, hedge language density, content density scoring, syndication detection, paywall detection, key figure extraction, TL;DR generation, content-type classification, correction tracking, reading time, archive availability, outbound-authority scoring
- Intelligent content scoring — removes navigation, footers, ads, and boilerplate
- Rich metadata extraction: OpenGraph, Twitter Cards, schema.org JSON-LD
- Content-Type: application/json

## Usage Example
```bash
curl -X POST https://nanoparse.app/fetch \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "debug": true}'
```

## Payment (x402)
After 10 free parses, the API returns HTTP 402 with:
- Payment-Required header: base64-encoded payment requirements (x402 standard)
- Payment-Signature header: base64url-encoded x402 v2 PaymentPayload, validated and settled by the CDP Facilitator
- MCP clients without header support: pass the same payload as the payment_signature argument
- Any Ethereum wallet works (ethers/viem signTypedData, EIP-712 domain: "USD Coin" v2, chainId 8453); x402 v2 SDK envelopes also accepted
- Failed parses are never charged — settlement happens only after a successful render

## Compliance & Trust
- **Paywall and login-wall detection** — NanoParse never bypasses subscription or login walls
- **Paywalled content blocked** — no bypassing subscription or login walls
- **DMCA:** dmca@nanoparse.app
- **No persistent storage** — Markdown results cached for up to 6 hours (R2) for performance; no permanent storage, no data resale
- **No user tracking** — no accounts means no personal data collection


## Product Catalog — Single Source of Truth

Five x402 products. Every agent-facing surface (MCP tool list, 402 payment
menu, docs) must mirror this section. Prices below are USD, paid per use via
x402 (USDC on Base). For "live" prices see pricing.ts — this file imports it.

| MCP tool | Endpoint | Method | Price | Use when |
|---|---|---|---|---|
| nanoparse_fetch | https://nanoparse.app/fetch | POST | $0.01 per parse (live) | Use nanoparse_fetch when you need to read a web page as clean, structured Markdown — articles, docs, news, SPA content — with litmus trust signals attached. |
| nanoparse_extract | https://nanoparse.app/extract | POST | $0.035 per call (live) | Use nanoparse_extract when you need structured, typed fields pulled out of a page (products, articles, records) for RAG ingestion or tool arguments — not just Markdown. |
| nanoparse_litmus | https://nanoparse.app/litmus | GET | unpriced | Use nanoparse_litmus when you must filter sources BEFORE spending a full parse — RAG pipelines that skip AI-generated, spam, or low-trust content at a fraction of parse cost. |
| nanoparse_search | https://nanoparse.app/search | GET | $0.01 per 10 results (1 credit; 11–20 results = 2 credits) (proposed) | Use nanoparse_search when you need fresh search results with clean, readable content per hit — research and competitive lookup — cheaper than Firecrawl /search. |
| nanoparse_monitor | https://nanoparse.app/monitor | POST | unpriced | Use nanoparse_monitor when you must be alerted that a page changed — prices, docs, competitor pages, listings — without polling it yourself. |

### Status key
- **live** — billed in production today.
- **approved** — Kevin-approved price; billing wiring still landing.
- **proposed** — recommendation awaiting final sign-off; not final.
- **unpriced** — no price decided; do not quote a number.

### Machine-readable catalog
```json
{
  "schema_version": 1,
  "catalog": "nanoparse x402 product family — single source of truth",
  "currency": "USD",
  "payment": {
    "protocol": "x402",
    "token": "USDC",
    "network": "base"
  },
  "price_status_key": {
    "live": "billed in production",
    "approved": "Kevin-approved, billing not yet wired",
    "proposed": "recommended, pending final sign-off",
    "unpriced": "no price decided — do not quote"
  },
  "products": [
    {
      "id": "nanoparse_fetch",
      "mcp_tool": "nanoparse_fetch",
      "endpoint": "/fetch",
      "method": "POST",
      "endpoint_url": "https://nanoparse.app/fetch",
      "price_usd": "0.01",
      "price_unit": "per parse",
      "price_status": "live",
      "price_note": "Kevin-approved 2026-08-23 (cut from $0.0175). Settled live via x402.",
      "status": "live",
      "use_case": "Turn any URL into clean Markdown with metadata and the full 15-signal litmus intelligence layer. Full Chromium rendering for JS-heavy SPAs.",
      "use_when": "Use nanoparse_fetch when you need to read a web page as clean, structured Markdown — articles, docs, news, SPA content — with litmus trust signals attached.",
      "free_tier": "10 free parses per network (subnet)"
    },
    {
      "id": "nanoparse_extract",
      "mcp_tool": "nanoparse_extract",
      "endpoint": "/extract",
      "method": "POST",
      "endpoint_url": "https://nanoparse.app/extract",
      "price_usd": "0.035",
      "price_unit": "per call",
      "price_status": "live",
      "price_note": "Billed in production at $0.035/call via x402 (EXTRACT_PRICE_USD, pricing.ts). Final number still subject to ops/growth sign-off (cost model t_88f0b67c, positioning t_cfcd68ba).",
      "status": "live",
      "use_case": "Schema-guided JSON extraction: POST a URL + JSON Schema, get back typed, validated JSON conforming to your schema instead of prose Markdown.",
      "use_when": "Use nanoparse_extract when you need structured, typed fields pulled out of a page (products, articles, records) for RAG ingestion or tool arguments — not just Markdown.",
      "free_tier": null
    },
    {
      "id": "nanoparse_litmus",
      "mcp_tool": "nanoparse_litmus",
      "endpoint": "/litmus",
      "method": "GET",
      "endpoint_url": "https://nanoparse.app/litmus",
      "price_usd": null,
      "price_unit": null,
      "price_status": "unpriced",
      "price_note": "PAUSED by Kevin 2026-09-02 — no standalone paid Litmus product yet; litmus ships inside the $0.01 parse. Do not quote.",
      "status": "planned",
      "use_case": "Pre-parse trust screening: zero-ML source-intel signals (is_ai_generated, is_spam, is_low_trust, trust_score) computed on the same path every parse already runs.",
      "use_when": "Use nanoparse_litmus when you must filter sources BEFORE spending a full parse — RAG pipelines that skip AI-generated, spam, or low-trust content at a fraction of parse cost.",
      "free_tier": null
    },
    {
      "id": "nanoparse_search",
      "mcp_tool": "nanoparse_search",
      "endpoint": "/search",
      "method": "GET",
      "endpoint_url": "https://nanoparse.app/search",
      "price_usd": "0.01",
      "price_unit": "per 10 results (1 credit; 11–20 results = 2 credits)",
      "price_status": "proposed",
      "price_note": "Pricing spec t_b635460e (done): 1 credit/$0.01 per 10 results — half Firecrawl's 2-credit charge. 3 decision points flagged for Kevin sign-off.",
      "status": "in_build",
      "use_case": "Agent-friendly SERP: search a query, get results with title, URL, raw snippet, and a clean Markdown excerpt per result via the markdown-excerpt service.",
      "use_when": "Use nanoparse_search when you need fresh search results with clean, readable content per hit — research and competitive lookup — cheaper than Firecrawl /search.",
      "free_tier": "10 free calls per network (subnet) (proposed — pending sign-off)"
    },
    {
      "id": "nanoparse_monitor",
      "mcp_tool": "nanoparse_monitor",
      "endpoint": "/monitor",
      "method": "POST",
      "endpoint_url": "https://nanoparse.app/monitor",
      "price_usd": null,
      "price_unit": null,
      "price_status": "unpriced",
      "price_note": "No price decided. Billing mode set (x402 per check OR prepaid balance — t_d8da902d/t_b0c54b8a); the per-check amount awaits Kevin's pricing decision.",
      "status": "in_build",
      "use_case": "Watch a page on a schedule and get a signed webhook when meaningful content changes: diff engine + snapshot store + cron schedule + webhook delivery.",
      "use_when": "Use nanoparse_monitor when you must be alerted that a page changed — prices, docs, competitor pages, listings — without polling it yourself.",
      "free_tier": null
    }
  ]
}
```