x402 payments for document APIs

Send POST without payment → receive 402 with payment-required header (base64 JSON). Sign USDC transfer per accepted requirements. Retry with payment-signature header. On success, x402Payer is recorded as owner_wallet for stored bundles.

On staging (ENVIRONMENT !== production), mock x402 facilitators accept test signatures. Production requires real signed USDC on Base.

Transparent per-operation pricing — charged only on 2xx success:

GET /v1/extract/:id/verify and GET /v1/extract/:id/download are free.

Paid POST routes (/v1/extract, /v1/summarize, etc.) do not require X-Wallet-Address — identity comes from the verified payment payer.

Owner-scoped routes (GET bundle, collections, jobs, monitor) require wallet identity under x402: send X-Wallet-Address matching your payment payer, or use an API key instead.

OAuth and API keys are designed for humans. OAuth requires a browser redirect and a session cookie. API keys require account creation, email verification, billing setup, and a human to copy-paste a secret into an environment variable.

Autonomous agents run without humans in the loop. An agent discovering DocImprint at runtime via an agent card has no way to register an account or retrieve a stored API key. x402 solves this: the payment requirements arrive in the 402 response body, the agent signs a USDC transfer using its own wallet, and retries. The entire auth flow is machine-readable and requires no prior coordination.

x402 also provides wallet identity by design. The payment payer address becomes the owner of every bundle the agent creates — no additional identity header required on paid routes. Audit trails map directly to on-chain wallet addresses.

The full probe → pay → succeed cycle in four curl commands:

bash
Copy
# Step 1: Probe (expect 402)
curl -si -X POST https://api.docimprint.com/v1/extract \
  -H "Content-Type: application/json" \
  -d '{"source":"https://example.com/contract.pdf"}' \
  | head -20

# HTTP/2 402
# x-payment-response: eyJ...base64...
# The x-payment-response header contains base64-encoded JSON:
# {
#   "scheme": "exact",
#   "network": "base",
#   "maxAmountRequired": "75000", // $0.075 in USDC (6 decimals)
#   "resource": "https://api.docimprint.com/v1/extract",
#   "description": "Extract document with evidence bundle",
#   "mimeType": "application/json",
#   "payTo": "0xDocImprintFacilitator...",
#   "nonce": "0x...",
#   "expires": 1718000000
# }

# Step 2: Sign EIP-712 USDC transfer (using your wallet library)
# PAYMENT_SIG=$(sign_eip712 --to 0xFacilitator --amount 75000 --nonce $NONCE)

# Step 3: Retry with payment
curl -X POST https://api.docimprint.com/v1/extract \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT_SIG" \
  -H "X-Wallet-Address: 0xYourWallet" \
  -d '{"source":"https://example.com/contract.pdf","include":["markdown","summary"]}'

# Step 4: Use the returned bundle_id for future operations (free)
curl https://api.docimprint.com/v1/extract/ev_abc123/verify

Common x402 errors and how to handle them:

SIGNATURE_INVALID — EIP-712 signature does not verify. Check that you signed against the correct domain (chainId: 8453 for mainnet, 84532 for Sepolia), used the correct facilitator address from the payment requirements, and that the amount matches maxAmountRequired exactly.

NONCE_REUSED — Each payment nonce is single-use. Never reuse a nonce across retries. Fetch fresh payment requirements for each attempt.

PAYMENT_EXPIRED — The expires timestamp in payment requirements has passed. Re-probe to get a fresh payment object, then sign and retry.

INSUFFICIENT_FUNDS — On-chain USDC balance or allowance is too low. The facilitator checks the allowance before settlement; pre-approve or use a permit signature.

WRONG_NETWORK — Payment signed for Base Sepolia (84532) sent to production (Base mainnet 8453) or vice versa. Match chainId to the environment.

DocImprint staging accepts mock x402 signatures. Set the base URL to the staging environment, or use the X-Test-Payment: true header on staging instances to bypass real signature verification.

For integration tests against the real payment flow, use Base Sepolia (chainId: 84532). USDC on Sepolia is a testnet token — fund your test wallet from the Coinbase testnet faucet.

Production (api.docimprint.com) requires real USDC on Base mainnet (chainId: 8453). A full evidence bundle costs $0.075 — roughly 75,000 USDC units at 6 decimal places.