# x402 Parse Service

> Multi-format document to structure extraction for AI agents. Pay fractions of a cent in USDC (x402) to parse 13 formats into token-compressed JSON. Raw content is NEVER stored.

Base URL: https://parseapi.info
Docs: /docs   OpenAPI: /openapi.json

## Payment (x402 v2, HTTP 402 transport)
Send a request with no X-PAYMENT header. The server returns HTTP 402 with a base64 `PAYMENT-REQUIRED` response header (scheme exact, network eip155:8453, amount, asset USDC, payTo, maxTimeoutSeconds). Sign a USDC micropayment to payTo and retry with an `X-PAYMENT` header. Settlement result is returned in an `X-PAYMENT-RESPONSE` header.

## Endpoints
- POST /parse/document - PDF, DOCX, PPTX, CSV/XLSX, HTML, EML, MSG, LOG -> structure JSON
- POST /parse/image   - image -> OCR words, confidence, coordinates
- POST /parse/audio   - audio -> timestamped transcript (priced per minute)
- POST /parse/video   - video -> audio-track transcript (priced per minute)
- POST /parse/archive - ZIP -> recursive file inventory + structures
- POST /search - raw file bytes -> top-5 similar stored structures
- GET  /memory - recall your tenant last 20 structures
- GET  /health - liveness

## Headers
- Authorization: Bearer <tenant_secret> (required for isolation; else an isolated ephemeral tenant)
- X-Filename: format hint
- X-PAYMENT: payment proof

## Formats and prices (USDC)
- pdf = $0.001
- docx = $0.001
- pptx = $0.001
- xlsx = $0.001
- csv = $0.001
- html = $0.001
- eml = $0.001
- msg = $0.001
- log = $0.001
- image = $0.002
- zip = $0.002
- audio = $0.005 / min
- video = $0.01 / min

Reads (search, memory) = $0.001. Max upload 200 MB.

## Response shapes by type (JSON)
POST /parse/document  ($0.001, PDF/DOCX/PPTX/CSV/XLSX/HTML/EML/MSG/LOG) -> {"ok": true, "format": "pdf", "doc_kind": "invoice_like", "fields": ["currency", "invoice_terms", "totals", "dates"], "tokens": 120, "content": "Invoice #A-1042 Total: $1,250.00 Due: 2026-02-01", "structure": {"pages": 1, "fields": ["currency", "totals", "dates"]}, "x402": {"paid": true, "format": "pdf", "price": 0.001}}
POST /parse/image     ($0.002, OCR) -> {"ok": true, "format": "image", "doc_kind": "document_like", "tokens": 128, "content": "RECEIPT TOTAL $42.99 THANK YOU", "structure": {"words": 128, "confidence": 0.82, "blocks": 7, "coordinates": [{"t": "RECEIPT", "x": 40, "y": 12}, {"t": "TOTAL", "x": 40, "y": 210}]}, "meta": {"engine": "tesseract", "ocr": true}, "x402": {"paid": true, "format": "image", "price": 0.002}}
POST /parse/audio     ($0.005/min) -> {"ok": true, "format": "audio", "doc_kind": "document_like", "tokens": 9, "content": "Your total for this billing period is one thousand two hundred fifty dollars.", "structure": {"segments": 8, "duration": 143, "timestamps": [{"start": 120, "end": 122}]}, "meta": {"engine": "faster-whisper", "transcript": true}, "x402": {"paid": true, "format": "audio", "price": 0.015, "duration_min": 3, "duration_sec": 146}}
POST /parse/video     ($0.01/min, audio track only) -> {"ok": true, "format": "video", "doc_kind": "document_like", "tokens": 6, "content": "Welcome back to the quarterly earnings call.", "structure": {"segments": 1, "duration": 38, "timestamps": [{"start": 0, "end": 38}]}, "meta": {"engine": "faster-whisper", "transcript": true}, "x402": {"paid": true, "format": "video", "price": 0.01, "duration_min": 1}}
POST /parse/archive   ($0.002, ZIP recursive) -> {"ok": true, "format": "zip", "doc_kind": "document_like", "tokens": 340, "content": "Invoice #A-1042 Total: $1,250.00", "structure": {"files": 12, "total_bytes": 20480, "inventory": ["invoice.pdf", "data.csv", "notes.txt"], "parsed": ["invoice.pdf", "data.csv"]}, "meta": {"engine": "adm-zip", "recursive": true}, "x402": {"paid": true, "format": "zip", "price": 0.002}}
POST /search          ($0.001) -> {"ok": true, "format": "pdf", "matches": [{"id": 7, "doc_kind": "invoice_like", "similarity": 0.98, "confirmations": 3, "source": "private"}]}
GET  /memory          ($0.001, your tenant last 20 structures) -> {"ok": true, "tenant": "acme", "authed": true, "items": [{"id": 7, "doc_kind": "invoice_like", "schema_hint": {"format": "pdf"}, "confirmations": 3, "created_at": "2026-10-06T09:12:00Z"}]}

## Privacy
- Raw content never persisted; temp files are RAM-only (tmpfs) and deleted after parse.
- Only a non-PII structure fingerprint + schema hint + doc-kind are stored (no text, no PII).
- Tenant isolation enforced by DB row-level security AND bearer-secret authorization.

## Discovery
This service publishes /llms.txt, /openapi.json, and an MCP server to help agents discover and use it. Each paid endpoint also advertises x402 Bazaar discovery metadata (an extensions.bazaar block in its HTTP 402 response) describing its method, input, output schema and example, served through the authenticated Coinbase CDP facilitator. Presence on a domain does NOT automatically connect AI clients: discovery depends on agents using search engines or compatible registries (e.g. the x402 Bazaar, MCP Registry). The endpoints pass Coinbase x402 validation, but Bazaar indexing requires at least one settled payment and is not guaranteed by this service alone.

## MCP
An MCP server (stdio, Node) exposes tools parse_file, search_structures, list_memory. Client config: command=node, args=["mcp-server.js"], env X402_API_URL=https://parseapi.info, X402_TENANT_ID=<tenant>, X402_PAYMENT=<x402 payment proof>. See /docs for the full config.