402tools402 docs
docs · live

Buyer guide

You're building an agent that calls HTTP APIs and pays per call. The buyer side of tools402 is just 5 lines of curl + an ERC-20 USDC transfer. No SDK install, no API key, no account. Optional language SDKs exist but are not required.

#What you need

  • An EVM wallet (Base, Polygon) or a Solana wallet, with USDC on the chosen chain. Any wallet that signs EIP-712 (EVM) or partial-signs SPL transfers (Solana) works — viem, wagmi, ethers, web3.py, MetaMask programmatically, etc.
  • ~50 lines of code if you write the 402 dance yourself
  • A target endpoint (browse the catalog at api.tools402.dev/v1/_meta)

#The 5 sub-pages

→ The 402 Dance — wire protocol explained. The exact sequence of HTTP requests and on-chain transactions.

→ Curl — copy-paste bash, no language SDK. Best for CI pipelines, one-off scripts, sanity checks.

→ TypeScript — bun add viem. Full type safety, auto-retry on 402, idempotency. Best for production agents on Bun / Node / Deno.

→ Python — pip install eth-account requests. Same flow, manual but explicit. Best for Python agents.

→ See also /quickstart for a side-by-side comparison of all three languages on one page.

#The flow in 30 seconds

text
1. agent.post('/v1/<path>')                     → 402 quote
2. wallet.signAndSend(USDC.transfer(payTo, …))  → tx hash
3. agent.post('/v1/<path>', X-Payment: <hash>)  → 200 + response body

That's it. No webhook to wire, no signature to verify, no JWT to manage. The marketplace verifies the tx hash on-chain before resolving step 3.

#Picking a chain

The 402 quote returns a accepts[] array with one entry per chain the endpoint accepts. Pick whichever you already have USDC on :

  • Base (eip155:8453) — most agents start here, ecosystem default
  • Polygon (eip155:137) — cheapest gas
  • Solana (solana:5eykt4Us…) — fastest finality + lowest fee

If the endpoint declares accepted_chains: ["base", "polygon", "solana"] in /v1/_meta, you can pay on any of the three. The marketplace handles cross-chain settlement to the seller's preferred chain.

Full chain details : /chains/overview.

#Handling 402 in a real agent

The hard part of the buyer side is error handling, not the happy path. The 402 response includes a maxTimeoutSeconds field — typically 60 s on EVM, 30 s on Solana. If you don't ship the X-Payment retry within that window, the quote expires and you have to start over (and re-pay).

Common pitfalls :

  • Buyer pays then drops : the 60 s window expires before the retry. The buyer's USDC is on the marketplace recipient wallet but the endpoint never resolves. Per the spec, this is the buyer's bug ; we don't offer off-chain refunds.
  • Buyer retries before tx confirms : the marketplace can't yet see the tx on-chain. Returns 402 again. Wait for at least one block confirmation before retry (~1.2 s on Base, ~2 s on Polygon, sub-second on Solana).
  • Buyer retries with wrong X-Payment : tx hash doesn't match the quote's payTo + maxAmountRequired. Returns 402 again with the same quote. Re-pay, don't re-quote.

The reference TypeScript implementation handles all three correctly : /buy-side/typescript.