# Mart402
> Pay-per-call APIs for AI agents with verifiable results, in three lines: documents & web (extract, PDF parse, hallucination-guarded OCR, invoice verification, company enrichment), Japan statutory calculations (payroll, social insurance, tax - deterministic, primary-source cited, never billed on unverified rules) and calibrated vision (meal nutrition, personal color). Pay per call with x402 (USDC on Base) - no account, no API key.

## Try it free
- Sandbox with the same API on Base Sepolia (free test USDC): https://mart402.dev - deterministic products (PDF utilities, the whole jp-statutory line) run for real; LLM-backed products return recorded samples marked sample:true

## Docs
- /agents.md: How to use this service as an agent
- /llms-full.txt: this file + the full agent guide in one fetch
- /catalog: Machine-readable product & pricing catalog (JSON)
- /mcp: hosted MCP endpoint (Streamable HTTP JSON-RPC; speaks MCP 2026-07-28 per-request _meta and legacy initialize 2024-11-05..2025-06-18; smaller line-specific tool sets at /mcp/docs, /mcp/jp, /mcp/vision, /mcp/market; free read-only tools only at /mcp/free). Free tools (catalog, samples, parse quote, portrait precheck, receipt re-fetch, x402 service search, operator history - all 7 at /mcp/free) work immediately; paid tools called without x_payment return the exact payment terms instead of charging
- /faq: plain-language answers (how agents pay without API keys, hallucination-guarded OCR, receipts, MCP, purchase due diligence, reliability)
- /.well-known/ai-catalog.json: Discovery index
- /stats: measured latency & success rate (last 30 days). The same operator runs Market402 (market402.com), which probes this store under the public rules it applies to every x402 operator (market402.com/methodology); every paid claim there carries an on-chain tx hash you can check yourself

## Common workflow: purchase due diligence
Before your agent pays an unfamiliar x402 seller: check its measured record at https://market402.com/op/{operator}. After ordering: extract the order-confirmation page (/v1/extract), parse the receipt PDF (/v1/parse), verify the amounts (/v1/verify).

## Products (all pay-per-call via x402, prices in /catalog)
- POST /v1/extract: URL -> Markdown + metadata. JS rendering auto. ($0.005-$0.01)
- POST /v1/parse/quote -> /v1/parse: PDF -> structured Markdown. Free quote, then flat $0.01/document for text-embedded PDFs, $0.015/page for scanned OCR. Japanese-strong OCR routing. Hallucination-guarded: dual-engine consensus (VLM + traditional OCR) + calibrated confidence in every OCR result - see /ocr.
- POST /v1/ocr: single image -> text with dual-engine consensus, calibrated confidence, and per-segment corroboration. Flat $0.05/image. Japanese-strong.
- POST /v1/enrich: company name/domain/URL -> verified company profile from primary sources (official site + GLEIF LEI + Japan NTA corporate-number registries). Per-field evidence + confidence, honest nulls. Resolution failures are never charged. Flat $0.03/company.
- POST /v1/verify: invoice field verification (tax math, JP registration check-digit + NTA corporate-number existence observation, accounting JSON). ($0.015)
- POST /v1/structured: fill YOUR JSON schema from any URL. Hybrid LLM + deterministic canonicalization. ($0.03)
- POST /v1/jp-company: Japanese company site -> standard profile JSON. ($0.03)
- POST /v1/document-pipeline: invoice pipeline in one call - parse + field extraction + arithmetic verification (+optional issuer enrich). Flat $0.05/document (text PDFs to 20 pages, scans to 3). Inputs validated before payment; stage outcomes recorded honestly.
- POST /v1/pdf-merge | /v1/pdf-pages | /v1/pdf-info: deterministic PDF utilities - merge 2-10 PDFs ($0.003), extract page ranges ($0.002), page/metadata/scanned-or-not facts ($0.001).
- POST /v1/jp-payroll-net: Japan annual gross -> net take-home. Exact NTA Beppyo-5 table, official Kyokai-Kenpo FY2026 rates (47 prefectures), reconstruction surtax, resident tax with adjustment credit. Deterministic, cites primary sources. ($0.02)
- POST /v1/jp-social-insurance | /v1/jp-bonus-net: official grade-table premiums ($0.01) and bonus net pay with the official withholding rate table ($0.01).
- POST /v1/jp-dependent-threshold: Japan income-wall analysis - tax wall derived from the engine, time-versioned social-insurance walls (2026-10 rule change), spousal + student walls. ($0.02)
- POST /v1/jp-consumption-tax | /v1/jp-overtime-wage | /v1/jp-retirement-tax | /v1/jp-business-days | /v1/jp-mortgage: consumption tax incl. qualified-invoice validation ($0.01), overtime premiums with official rounding ($0.015), retirement income tax ($0.02), holidays + statutory deadlines + wareki ($0.003), mortgage math ($0.005).
- POST /v1/jp-payroll-suite: net salary + social insurance + income walls (+bonus) in one call. Flat $0.05.
- POST /v1/jp-payslip-audit: audit a Japanese payslip - recompute premiums and withholding from official tables, per-item verdicts that explain grade revisions and combined care notation instead of flagging them as errors. ($0.02)
- POST /v1/jp-crypto-tax: Japan crypto-asset realized income under NTA total-average/moving-average rules (sell/spend/exchange, fees, opening balances), verified to the yen against the official NTA FAQ examples. Max 300 tx/call. ($0.05)
- jp-statutory line: every response carries rules_version, cited primary-source URLs, assumptions, not_covered and unknown-field warnings with fix suggestions. Calculations using rules not yet verified against primary sources are NEVER billed (rule_unverified, no payment taken). Errors are never billed. Full-fidelity free sandbox (the engine is LLM-free).

First real call on the JP statutory line: POST /v1/jp-business-days costs $0.003 - deterministic (LLM-free), a genuine end-to-end x402 payment (402 challenge -> pay -> result with rules_version and cited sources -> receipt) for the price of a rounding error. Free recorded response shape at /samples/jp-business-days; the whole line runs at full fidelity on the sandbox with test USDC.
- POST /v1/meal-vision: meal photo -> itemized nutrition JSON (dishes, portions, kcal, protein/fat/carb, per-item confidence). v1.3: reference-object scale calibration (chopsticks/cutlery/phone with strength grading), scene-complexity detection with honest confidence downgrade, a disclosed calibrated kcal range, PFC energy-balance ratios, and alcohol-aware deterministic 4/4/9 cross-checks. v1.5: every call is a 3-run consensus - median run reported, per-call kcal spread + item agreement disclosed. Pass a cuisine hint (hints param) for regional home-style meals - measured accuracy gain. ($0.05/image)
- POST /v1/portrait-analysis: 1-3 portraits -> personal color analysis. Measured pixel colorimetry (CIELAB/ITA angle) cross-checked against vision-model attributes, cross-photo lighting consistency checks, published rule table for the 4-season verdict + all-4 season_scores + structured palette (base/accent/metal/avoid+reason, every hex with a human-readable color name) + task advice + rules_version. No identification; images not stored. (flat $0.05)
Vision calibration evidence (why agents can trust these numbers):
- meal-vision is calibrated against 30 dietitian-portioned WEIGHED meals (Japanese teishoku, donburi, noodle bowls, Chinese, Western). Current rules: median error ~12-15 percent and the disclosed two-sided kcal range contained the true value in 26 of 30 meals. Every call is a 3-run consensus with per-call spread and item agreement - reproducibility an agent can probe directly.
- portrait-analysis and style-profile colorimetry is calibrated on a 16-subject diverse-skin E2E set (ITA -0.2 to +62 deg, light to deep skin): specular-highlight demotion, cast demotion and sclera-referenced white balance were each added in response to a measured failure, not a guess.
- Every response carries the exact rules_version that produced it and every rule change is dated in pricing_changelog - agents can pin, compare and re-verify any verdict. No competitor in this category publishes weighed-meal or diverse-skin calibration evidence.
- We do not keep your money for a photo of your desk: if meal-vision finds no food, or portrait-analysis finds no face, the response includes a single-use retry credit for the same product (x402 settlements are final, so we return the value instead). Typical latency: meal-vision 8-15s (3-run consensus), portrait 4-15s, style-profile 5-20s, style-report 6-25s - set client timeouts to 60s+.
- Full method, findings and the systematic errors VLMs make about food (citable, CC BY 4.0): https://mart402.com/vision-calibration . Worked flows: /use-cases/meal-logging and /use-cases/personal-color

- POST /v1/portrait-precheck: FREE analyzability check before paying - face detectable? photo quality OK (clipping/color cast)? Now also returns a deterministic confidence preview: a photo grade (clean/flagged/unusable) plus a published band table (2+ clean photos -> high 0.7-0.9, calibrated on a 16-subject diverse-skin set), so you know the expected verdict confidence BEFORE spending a cent. No LLM. 10/hour/IP.
- POST /v1/style-profile: integrated styling verdict in one call - seasonal color (measured colorimetry consensus) + face-impression zone (published 2-axis geometry rules, on-device landmarks) + body frame type (photo/questionnaire) + integration rules (palette subset, taste, silhouette, hair/brow/beard modifiers). Every layer carries a rule trace. (flat $0.05)
- POST /v1/style-report: the same style-profile analysis rendered as a finished, client-ready English PDF report (cover, verdict table, palette swatches with color names, style-aware outfit formulas, virtual draping boards with disclosed candidate conflicts, honest confidence) returned as base64 + the full profile JSON. Japanese version via language:"ja". For agents serving human end-clients. ($2.99/call; volume: POST /v1/report-pack = 10 single-use credits for $19.90, i.e. $1.99/unit)

Billing promise (all products, since 2026-09-27): payment is verified before the call and settled only when the call succeeds - a call that does not succeed is never charged (billed_usd 0). Structured errors say whether retrying makes sense. Same payment resent = same stored result, never a second charge.

Verifiable terms (x402 offer-receipt extension, since 2026-09-27): every 402 carries a signed offer (JWS/EdDSA, kid did:web:mart402.com#key-1, key at /.well-known/did.json) over resourceUrl/scheme/network/asset/payTo/amount/validUntil (validUntil = issue time + 300 s: how long the quoted terms are held; a valid payment presented later is still accepted while the price is unchanged - it is not a payment deadline), and every settled response carries a signed receipt (payer, network, resourceUrl, issuedAt, transaction) inside PAYMENT-RESPONSE - re-served by GET /v1/receipts/{id}. Verify with @x402/extensions/offer-receipt or POST https://scvd.store/api/preflight/v1.

First real call on a budget: POST /v1/pdf-info costs $0.001 - a genuine end-to-end x402 payment (402 challenge -> pay -> result -> receipt) for the price of a rounding error. Response shapes for 28 products are free at /samples/{product} before you pay anything.

Works with the Cloudflare Agents SDK client stack: verified end-to-end with @x402/fetch v2.21.0 (2026-08-11, payment settled and delivered on the Base Sepolia sandbox; production speaks the identical x402 v2 protocol). If your agent runs on Cloudflare Workers or anything using @x402/fetch, it can pay Mart402 today.

## Use cases (worked examples)
- /use-cases/invoice-processing: PDF invoice to verified accounting JSON in one call
- /use-cases/purchase-due-diligence: check an x402 seller before paying, verify receipts after
- /use-cases/document-workflows: prepare (info/pages/merge), read (parse/ocr), check (verify)

---

# 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.