# Mart402 - Agent Guide

Pay-per-call APIs for AI agents in three lines: documents & web, Japan statutory calculations, calibrated vision. No signup. Pay per request via x402 (USDC on Base).

## Try it free first
Same API on testnet: https://mart402.dev (Base Sepolia; get free test USDC from https://faucet.circle.com). Note: LLM-backed products (ocr/enrich/structured/jp-company/meal-vision/portrait-analysis) are production-only; on the sandbox they return recorded samples (sample:true) or 503 before any payment. Deterministic products (pdf utilities and the whole jp-statutory line) run FULLY on the sandbox - same engine, same numbers as production.

Client compatibility (measured, not assumed): verified end-to-end with @x402/fetch v2.21.0 - the standard x402 client used by the Cloudflare Agents SDK - on 2026-08-11: 402 challenge parsed, EIP-3009 payment signed, settled and delivered (Base Sepolia sandbox; the production API speaks the identical x402 v2 protocol). Minimal setup: wrapFetchWithPaymentFromConfig(fetch, {schemes: [{network: "eip155:8453", client: new ExactEvmScheme(account)}]}).

## Quick start
1. GET /catalog - read products, prices, and payment config.
2. POST /v1/extract with JSON body: {"url": "https://...", "mode": "auto"}
3. If you receive HTTP 402, pay per the `accepts` requirements (x402, USDC on Base) and retry with the X-PAYMENT header.

## Behavior you can rely on
- `robots.txt` of target sites is respected (403-equivalent response with reason "disallowed_by_robots").
- Extract modes and prices: `fast` $0.005 (HTTP fetch + readability), `heavy` $0.01 (headless-browser render for JS-heavy pages), `auto` = fast with automatic heavy fallback (billed at the price quoted in the 402 you paid).
- Cached results (24h default TTL) are half price; `cache_hit: true` marks them.
- Every paid response carries an `X-Receipt-Id` header; GET /v1/receipts/{that value} re-fetches the result free, forever within retention.
- `text_len` tells you extracted content size before you decide to fetch more pages.
- No bot detection is used against you. Paid endpoints have no fixed rate limit (per-call payment plus abuse protection); free endpoints list their limits in /catalog.rate_limits.

## Hallucination-guarded OCR (why agents pick /v1/parse)
OCR engines fail silently: a vision-language model reading messy handwriting can output
fluent text in the wrong language or a plausible-looking rewrite - and you, the agent,
cannot taste-test the result. Mart402 treats that as a first-class API problem:
- Every /v1/parse result on the OCR route includes `ocr_quality`: {confidence, hallucination_suspected, flags, chars}.
  Script-mismatch (e.g. Devanagari appearing in a Japanese document) and excessive
  repetition are detected and flagged - the two dominant silent-failure modes we measured.
- When available, a second independent engine (traditional OCR, orthogonal failure modes
  to the VLM) cross-checks the read: `consensus`: {verdict, confidence, agreement, flags,
  best_engine}. On detected hallucination the output is replaced with the verified read.
- `verdict` values are honest: "high_consensus" / "partial_consensus" /
  "low_consensus_review_recommended" / "all_engines_suspected_hallucination" - we never
  sell overconfidence. If engines disagree, you are told, with the agreement score.
Act on it mechanically: trust `confidence >= 0.7`; queue `hallucination_suspected`,
"low_consensus_review_recommended" or "all_engines_suspected_hallucination" for human
review or a re-scan. Method and the measured failure modes: /ocr.

## Runnable examples (sandbox, free - https://mart402.dev on Base Sepolia)
```bash
# 1) Quote a PDF (free), then see the 402 challenge for parse
curl -s https://mart402.dev/v1/parse/quote -H "Content-Type: application/json"   -d '{"url":"https://mart402.com/samples/assets/doc.pdf"}'

# 1b) OCR a single image (flat $0.05, production; LLM-backed, so not on the
#     sandbox. Without payment this safely shows the 402 challenge with exact terms)
curl -i -s https://mart402.com/v1/ocr -H "Content-Type: application/json"   -d '{"image_url":"https://mart402.com/samples/assets/receipt.png","lang":"japanese"}'

# 1c) Enrich a company (flat $0.03, production). Name, domain, or URL as input;
#     resolution failures return a machine-readable error BEFORE any payment
curl -i -s https://mart402.com/v1/enrich -H "Content-Type: application/json"   -d '{"company":"sakura.ad.jp"}'

# 2) Extract a URL - returns 402 with x402 accepts; pay, then resend with X-PAYMENT
curl -i -s https://mart402.dev/v1/extract -H "Content-Type: application/json"   -d '{"url":"https://mart402.com/samples/assets/article.html","mode":"auto"}'

# 3) After paying, every result carries X-Receipt-Id. Re-fetch for free anytime:
curl -s https://mart402.dev/v1/receipts/rcpt_XXXXXXXX
# production: curl -s https://mart402.com/v1/receipts/rcpt_XXXXXXXX  (free, 30 days)
```
Errors are machine-readable: {ok:false, code, retryable(bool), action}. See /catalog.errors.
Billing: a call that does not succeed is never charged (payment is verified first, settled only after success; since 2026-09-27). If settlement fails after success, the result is held 1h and you get a fresh 402 - repeat the same request with a new payment to receive it without re-execution.
Signed terms: 402 = signed offer (validUntil = +300 s, a terms-hold declaration, not a payment deadline), settled 200 = signed receipt (x402 offer-receipt extension, JWS/EdDSA, key at /.well-known/did.json). Receipts re-fetch free for 30 days: GET https://mart402.com/v1/receipts/{id}. See /catalog signed_offer_receipt.

## Fair use & terms
- Rights to target-site content remain the caller's responsibility. See /catalog policy.