Aly Sawft · Founder & Engineer, Sawftware LLC · · 10 min read
Every HTTP API in production today requires some form of pre-registration: an API key, an OAuth token, a subscription. That works for human developers who can sign up, enter credit card details, and manage credentials.
It breaks completely for autonomous AI agents. An agent running inside Claude, GPT-4, or a local LLM cannot open a browser, fill out a form, or store a secret credential. It can make HTTP calls — but it cannot get the key it needs to make those calls useful.
This is not a theoretical problem. It is the reason most agent-integrated APIs require the human operator to pre-provision credentials and inject them into the agent's environment. The agent is not truly autonomous — it borrows human identity to function.
x402 solves this at the HTTP protocol layer. Instead of credentials, the server returns a payment requirement. The agent signs a USDC transfer. The server verifies the payment and processes the request. No account. No signup. No human in the loop.
HTTP 402 was defined in RFC 2616 (Fielding et al., 1999) as "reserved for future use." The x402 protocol specification at x402.org (2025) gives it precise semantics for USDC micropayments on EVM chains including Base (chain ID 8453).
The x402 payment flow:
DocImprint x402 pricing starts at $0.010 per lean extract and $0.075 for a full evidence bundle — sub-cent to sub-dime per autonomous agent action. The payment is atomic with the response: you pay for exactly what you receive, at the moment you receive it.
# Step 1: probe — no payment header
curl -X POST https://api.docimprint.com/v1/extract \
-H "Content-Type: application/json" \
-d '{"source":"https://example.com/contract.pdf","include":["markdown","summary"]}'
# Response: 402 Payment Required
# X-Payment-Required: eyJhbW91bnQiOiI3NTAwMCIsInRva2VuIjoiMHg4MzM...
# Body: {"error":"PAYMENT_REQUIRED","accepts":[{"scheme":"exact","network":"base",...}]}The X-Payment-Required header (or the accepts array in the 402 body) contains a JSON object with everything the client needs to construct a valid payment:
A compliant client hashes this payload, signs an EIP-712 USDC Permit or Transfer Authorization, and sends the result in X-Payment on the retry.
{
"scheme": "exact",
"network": "base",
"maxAmountRequired": "75000",
"resource": "https://api.docimprint.com/v1/extract",
"description": "DocImprint document extract — full bundle",
"mimeType": "application/json",
"payTo": "0xDocImprintTreasury...",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"extra": { "name": "DocImprint", "version": "1" }
}A naive x402 implementation would require every API server to submit USDC transfers on-chain directly. That creates operational complexity: gas management, transaction monitoring, failed submission retries, and mempool congestion handling.
DocImprint uses an x402 facilitator pattern. The server validates the client's signed payment payload, then a facilitator service submits the USDC transfer on-chain and confirms settlement before the API processes the request. The client signs once; the facilitator handles chain interaction.
This separation matters for agent developers: you do not need to understand gas estimation or transaction broadcasting. You sign an EIP-712 typed authorization, send it in X-Payment, and receive the API response plus X-Payment-Response with the confirmed txHash.
The facilitator also enforces payment schema validation before submission — invalid signatures, wrong token addresses, or amount mismatches fail fast with structured error codes in the 402 body, not silent on-chain failures.
On staging (Base Sepolia), a mock facilitator accepts correctly formatted signatures without submitting real transactions. This lets you test the full client flow — probe, sign, retry, parse response — without funding a wallet with testnet USDC.
Payment replay is the primary attack vector in any micropayment protocol. An attacker who intercepts a valid X-Payment header could theoretically replay it against the same or different endpoints.
DocImprint prevents this with nonce deduplication:
Each payment requirement includes a unique nonce tied to the specific resource URL, amount, and timestamp window. The server stores consumed nonces in Cloudflare KV with TTL. A second request with the same signed payload returns PAYMENT_NONCE_REUSED before any API processing occurs.
The resource field in the payment requirement binds the signature to a specific endpoint. A payment signed for POST /v1/extract cannot be replayed against POST /v1/summarize — the resource mismatch fails validation.
Amount binding prevents partial replay: maxAmountRequired in the payment requirement must match the signed transfer amount exactly under the "exact" scheme. Underpayment or overpayment both fail.
For agent implementers: always use the nonce and resource from the latest 402 response. Never cache and reuse X-Payment headers across requests. Each API call requires a fresh probe-retry cycle.
# If you replay a consumed payment:
curl -X POST https://api.docimprint.com/v1/extract \
-H "Content-Type: application/json" \
-H "X-Payment: <previously-used-payload>" \
-d '{"source":"https://example.com/doc.pdf"}'
# Response: 402
# { "error": "PAYMENT_NONCE_REUSED", "message": "Payment nonce already consumed" }
# Fix: probe again (no X-Payment), sign fresh payment, retryx402 could theoretically work on any chain, but Base (Coinbase's EVM L2) and USDC are the practical choice for developer API payments today:
Transaction fees on Base are sub-cent — a $0.075 document extraction does not become $2.00 in gas. Ethereum mainnet fees make micropayments economically absurd.
USDC is the dominant dollar-pegged stablecoin with native issuance on Base. Every agent wallet capable of Base transactions can hold USDC. Payments are in dollars, not volatile native tokens.
EIP-712 typed signing is standardized across every Ethereum wallet library (viem, ethers, wagmi). Agent frameworks that support Base can implement x402 with a few dozen lines.
Coinbase's AgentKit SDK already includes an x402 client. LangChain and Vercel AI SDK integrations are community-maintained. The ecosystem is building around this pattern.
After parsing the 402 response, the client:
The DocImprint server (via its x402 facilitator) submits the transfer on-chain, waits for confirmation, and processes the request. The response includes X-Payment-Response confirming the on-chain transaction hash.
If the agent's wallet has insufficient USDC or the signature is invalid, the server returns a specific error code. The agent can surface this to the user or halt. No partial charges occur — the transfer either completes or it does not.
# Step 2: retry with X-Payment header (payload signed by agent wallet)
curl -X POST https://api.docimprint.com/v1/extract \
-H "Content-Type: application/json" \
-H "X-Payment: eyJzY2hlbWUiOiJleGFjdCIsInBheWxvYWQiOnsi..." \
-d '{"source":"https://example.com/contract.pdf","include":["markdown","summary"]}'
# Response: 200 OK
# X-Payment-Response: {"success":true,"txHash":"0xabc123...","network":"base"}
# Body: { "bundle_id": "ev_...", "manifest_sha256": "...", ... }x402 is the right choice when:
API keys are better when:
DocImprint supports both on every paid endpoint. The authentication model does not affect the API surface — the same POST /v1/extract request works with either auth method.
DocImprint staging runs on Base Sepolia (eip155:84532) with a mock x402 facilitator that accepts test signatures without submitting on-chain. This means:
The staging environment uses a separate D1 database and R2 bucket. Bundles created in staging do not appear in production and vice versa. On-chain notarization on staging writes to Base Sepolia, not Base mainnet.
# OpenAPI 3.1 spec (includes x402 payment schemas)
curl https://api.docimprint.com/openapi.json
# Agent card (A2A discovery with x402 payment info)
curl https://api.docimprint.com/.well-known/agent.jsonx402 enables a new class of agent behaviors that are impossible with credential-based APIs:
An agent can call DocImprint on behalf of a user without the user ever creating an account. The agent's wallet funds the call. The user sees a USDC debit on their Base wallet — transparent, auditable, reversible if the agent misbehaves.
Agent marketplaces (Claude, GPT store, A2A) can list DocImprint as a tool without requiring operators to provision API keys for every user. Each agent session funds itself from the user's wallet.
Multi-agent pipelines where Agent A extracts a document, Agent B verifies the bundle, and Agent C answers questions across a corpus — each step can pay independently with its own wallet identity. The chain-of-custody log records every agent's wallet alongside its actions.
The broader implication: API monetization shifts from account management to protocol. Any server that implements x402 can monetize any HTTP call. Any agent that can sign a USDC transfer can pay for any x402-compatible service. This is the payment layer the agent economy has been missing.