# 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 (structured/jp-company) are production-only.

## 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").
- Cached results (24h default TTL) are half price; `cache_hit: true` marks them.
- `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.

## 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"}'

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