# Mart402 - Agent Guide

Extraction API for AI agents. No signup. Pay per request via x402, or free in dev mode.

## Try it free first
Identical 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) are production-only; on the sandbox they return 503 before any payment.

## 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.002 (HTTP fetch + readability), `heavy` $0.006 (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. Rate limits are per-payer and stated in /catalog.

## 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 OCR result 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: "agree" / "disagree_review_recommended" - 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` or
"review_recommended" for human review or a re-scan. Measured basis published in /stats.

## 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://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"}'

# 1b) OCR a single image (flat $0.005, 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://example.com/receipt.png","lang":"japanese"}'

# 1c) Enrich a company (flat $0.015, 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":"example.com"}'

# 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://example.com","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
```
Errors are machine-readable: {ok:false, code, retryable(bool), action}. See /catalog.errors.

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