Answers · agent payments
How do I accept x402 payments on my API?
Last updated
TL;DR: Put x402 middleware in front of the routes you want to charge for, give each route a price, a network and a payTo address you control, and point the middleware at a facilitator that verifies and settles payments. Unpaid requests get HTTP 402 with a base64 PAYMENT-REQUIRED header, the client retries with a PAYMENT-SIGNATURE header, and you answer with the result plus a PAYMENT-RESPONSE header. Coinbase's CDP facilitator is free for the first 1,000 onchain transactions a month and $0.001 per onchain transaction after that, and verification is always free. You never hold the buyer's funds, but you do need a receiving address you control.
What should I check, step by step?
1. Pick a payTo address you control on every network you advertise. Coinbase's docs say one EVM address covers all the EVM networks you list, Solana needs its own address, and production needs a mainnet address, not a testnet wallet. The CDP API key only authenticates you to the facilitator; it doesn't decide where funds land.
- Install the middleware. TypeScript: npm install express @coinbase/cdp-sdk @x402/core @x402/evm @x402/svm @x402/extensions @x402/express, then app.use(paymentMiddlewareFromHTTPServer(server)) with a server from createX402Server. Python: pip install "cdp-sdk" "x402[evm,svm,fastapi]" and add PaymentMiddlewareASGI. Only the routes you list are charged; everything else stays free.
- Price in dollars, for example price: "$0.01", and test on Base Sepolia (eip155:84532) first. Dollar prices use the network's default USDC. For production switch to Base (eip155:8453); if you set a token address and amount yourself, swap in the mainnet token address and check its decimals.
- Test it unpaid: curl -i your route should return 402 with a PAYMENT-REQUIRED header. That header is base64 JSON; decode it and confirm the amount, token, network and payTo are what you meant before any real buyer sees it.
- Choose when settlement happens. For the exact scheme the default authorization flow verifies the payment before your handler runs and settles after the work succeeds. paymentFlow: "upfront" settles before your handler runs, so if the work then fails the buyer has already paid and any refund happens outside x402.
- If browsers will call it, fix CORS: send Access-Control-Allow-Origin on the 402 itself, list PAYMENT-REQUIRED and PAYMENT-RESPONSE in Access-Control-Expose-Headers, and list PAYMENT-SIGNATURE (plus Content-Type for JSON bodies) in Access-Control-Allow-Headers. A * doesn't cover them on credentialed requests.
- Advertise the payment-identifier extension so a client that retries can send the same id (16 to 128 characters) and you can return the cached response instead of serving and charging twice.
- Log every settlement. The TypeScript resource server has hooks such as onAfterVerify, onAfterSettle and onSettleFailure; keep the network and transaction from each result next to your own request id.
What the facilitator does, and what it costs
Coinbase describes the CDP facilitator as validating signed payments, screening transactions (OFAC and Know Your Transaction checks that decline sanctioned or high-risk addresses), submitting settlement onchain and reporting the result to your server.
- Pricing on its facilitator page: up to 1,000 onchain transactions a month free, then $0.001 per onchain transaction. Fees follow onchain activity, not requests, and verification is always free. With exact and EVM upto each accepted payment is one onchain transaction; with batch-settlement, vouchers are checked offchain and claimed together, so one onchain transaction can cover thousands of payments.
- Networks listed for x402 v2 as of Oct 30, 2026: Base, Base Sepolia, Polygon, Arbitrum, Monad, World, World Sepolia, Solana and Solana Devnet. Coinbase says the list changes and points to its supported-networks endpoint as the source of truth.
Which scheme to use
exact: a fixed price per request. The simplest choice for a priced API route.
- upto: the buyer authorizes a maximum and you settle the amount actually used, for metered work on a synchronous endpoint. On Solana it uses an escrow deposit and a second transaction that refunds the remainder.
- batch-settlement: a payment channel for high-volume repeat buyers. The first request funds the channel, later requests send vouchers you verify locally, and a scheduled job claims them. Refunds are cooperative and need your server's signature.
What x402 doesn't do for you
It proves a payment, not who the payer is. A wallet address isn't an identity, so if you need to know who is buying (an agent's owner, a verified business), check that separately before serving.
- Replays of the same signed authorization fail onchain (the x402 spec relies on EIP-3009's 32-byte nonce), but a client that retries with a fresh signature is making a new payment. Deduplicate with payment-identifier or your own request ids.
- Refunds, receipts for accounting, and tax or sanctions obligations beyond the facilitator's screening are yours to handle.
How do I ask Rightshold about this (free, no key)?
Add the MCP server https://www.rightshold.com/mcp to Claude, Cursor, ChatGPT, Grok or VS Code, then ask: “Before I serve this paid request, check the payer against my policy: at least RS-KYA L1, standing clear, and no more than $0.05.”
{
"tool": "x402_gate_check",
"arguments": {
"payer": {
"rs": "<payer handle or RS number>"
},
"resource_url": "https://api.example.com/report",
"amount_micro": 10000,
"policy": {
"min_kya_level": "L1",
"require_standing_clear": true,
"max_amount_micro": 50000
}
}
}- Free, no key. The gate answer is only your own policy lines evaluated against the payer's public records (KYA level, standing, scan receipts, ERC-8004 identity). A payer with no record fails the lines that need one, and an identity claim counts as proven only with a signature by the key bound to the payer's RS record.
- REST, free: POST /v1/x402/price-tag with your own 402 body or PAYMENT-REQUIRED header decodes it into plain prices per option, warns when a token named USDC isn't on Circle's list, and reports whether you advertise payment-identifier. Run it on your endpoint before launch.
- verify_spend_authorization (free) checks a buyer agent's signed spend-authorization receipt, if the buyer sends one, so you can see its owner allowed the purchase.
Rightshold doesn't run x402 middleware, act as a facilitator, hold funds or settle payments, and its own checks don't charge through 402. It decodes 402 responses and checks payers against policies you set. Not financial or legal advice.
What are the sources?
- Coinbase CDP: Quickstart, charge for an endpoint
- Coinbase CDP: CDP Facilitator (pricing, networks, schemes)
- Coinbase CDP: Production configuration (payment flows, hooks)
- x402 specification v2
- x402 HTTP transport v2 (headers, browser CORS)
- x402 extension: payment-identifier
Related
- How to read an x402 402 Payment Required response as a price
- How to stop an AI agent from paying twice when it retries
- How to set a spending cap for an AI agent paying with x402
- x402 trust gate
Not legal advice. JSON · Markdown · All answers
Get a free API key in one call
No card and no email needed. 100 free credits; the license and policy checks stay free without a key.
curl -s -X POST https://www.rightshold.com/v1/accounts/signup -H "Content-Type: application/json" -d '{"accept_terms":true}'
export RIGHTSHOLD_API_KEY=rs_... # the api_key from the reply (shown once)
curl -s https://www.rightshold.com/v1/licenses/check -H "Authorization: Bearer $RIGHTSHOLD_API_KEY" \
-H "Content-Type: application/json" -d '{"license":"MIT","intended_use":{"commercial_use":true}}'