Answers · agent payments
How do I read an x402 402 Payment Required response as a price before my agent pays?
Last updated
TL;DR: In x402 v2 the price comes in the PAYMENT-REQUIRED response header: base64-encoded JSON whose accepts list holds one or more payment options. In each option, amount is a whole number of the token's smallest units, not dollars; asset is the token's contract address; network is a CAIP-2 chain id (eip155:8453 is Base, eip155:84532 is Base Sepolia, a testnet); payTo is who gets paid. Divide amount by 10 to the power of the token's decimals: USDC has 6, so "10000" is $0.01. Check the asset address against the issuer's published list, check that payTo is who you expect, read extra.paymentFlow (if it isn't authorization, money can move before you get the resource), and remember that in the upto scheme amount is a ceiling. Compare the price with your budget before your agent signs anything. Older v1 servers put the requirements in the JSON body instead, with maxAmountRequired and network names like base-sepolia.
What should I check, step by step?
1. Find the requirements: v2 servers send a PAYMENT-REQUIRED header on the 402 (base64 JSON, x402Version 2). v1 servers put them in the response body (x402Version 1, maxAmountRequired). Decode it; don't guess the price from the page.
- Pick an option from accepts[] that your wallet supports (scheme and network). Each option is a separate price; they can be on different chains and tokens.
- Convert amount: it's a string of atomic units. For USDC (6 decimals) divide by 1,000,000, so "10000" is 0.01 USDC. Read the decimals from the token itself for any other asset.
- Check asset against the issuer's list for that network. Circle lists Base USDC as 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 and Base Sepolia (testnet) USDC as 0x036CbD53842c5426634e7929541eC2318f3dCF7e. A look-alike token can carry the name USDC.
- Check network: eip155:8453 is Base mainnet (real money), eip155:84532 is Base Sepolia (testnet). A testnet price on a production API is a sign something is misconfigured.
- Check payTo is the seller's known address (from their docs or an earlier receipt), not just whatever this response says.
- Read scheme and extra.paymentFlow. In upto, amount is the most you could be charged. A flow other than authorization (upfront, escrow) settles before the resource runs; the spec says clients must not build a payment for a flow they don't recognise.
- Note maxTimeoutSeconds and keep the authorization window short, then check the total against your agent's per-call and daily limits before signing.
Where the price is (v2 and v1)
x402 v2 HTTP transport: the server answers 402 with a PAYMENT-REQUIRED header holding a base64-encoded PaymentRequired object, and the spec calls the header the canonical location. The client retries with a PAYMENT-SIGNATURE header, and the server reports settlement in PAYMENT-RESPONSE.
- PaymentRequired has x402Version, an optional error, a resource object (url is required; description and mimeType are optional) and accepts, the list of PaymentRequirements the server will take.
- x402 v1 servers return the requirements in the JSON body, using maxAmountRequired for the amount and network names such as base-sepolia, and the client pays with an X-PAYMENT header. Support both if you call servers you don't control.
The fields that make up the price
scheme: how the payment works, such as exact or upto. network: a CAIP-2 id like eip155:8453. amount: a string in atomic token units. asset: the token's address (or an ISO 4217 code for fiat). payTo: the recipient. maxTimeoutSeconds: how long the payment may take. extra: scheme-specific data; for EVM USDC it carries the token's EIP-712 name and version.
- The spec's v2 example asks for amount "10000" of asset 0x036CbD53842c5426634e7929541eC2318f3dCF7e on eip155:84532. That's Circle's Base Sepolia USDC, so the price is 0.01 testnet USDC, not real money.
- USDC's decimals() returns 6 on Base. For any other token, read decimals() from the token contract rather than assuming a value; a wrong guess shifts the price by powers of ten.
What can go wrong?
Paying the wrong token: anyone can deploy a token called USDC. Match asset to the issuer's address list for that exact network.
- Paying more than shown: in the upto scheme amount is the maximum authorized at verification time, and the settled amount can be lower. Budget for the maximum.
- Paying before you get anything: under upfront and escrow flows settlement happens before the resource runs. Authorization (the default) verifies first and settles only after the resource completes.
- Being steered by text: resource.description and other free-text fields come from the server. Treat them as untrusted input to your model, not as instructions.
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 my agent pays this x402 endpoint, check the description and resource text in the decoded PAYMENT-REQUIRED header for hidden text or instructions aimed at my agent.”
{
"tool": "scan_text",
"arguments": {
"text": "<the decoded PAYMENT-REQUIRED JSON, or just its resource.description>"
}
}- Free, no key. scan_text reports exact positions of zero-width and bidirectional characters, hidden markup and base64 blobs, and labels instruction-like language as a heuristic, never a certainty.
- REST, free: POST /v1/x402/price-tag with {payment_required_header} or {body} decodes a v1 or v2 402 and lists each option's scheme, network, asset, amount in atomic units and payTo. It shows a dollar figure for Circle USDC on Base, Base Sepolia (marked testnet) and other chains on Circle's list, reads the v2 top-level resource, warns when a token named USDC isn't on Circle's list, and reports whether the server takes a payment-identifier; for other assets, use the token's decimals yourself.
- With an account key, authorize_spend checks a proposed purchase against the spending policy you set and returns a signed allow or deny receipt. It records the decision only and never moves money; the merchant can check it with verify_spend_authorization.
Rightshold decodes and reads x402 payment requirements, scans their text, and records spend decisions against limits you set. It doesn't hold funds, sign or send payments, act as an x402 facilitator, or vouch for a seller. Check token addresses against the issuer's own list.
What are the sources?
- x402 protocol specification v2 (coinbase/x402)
- x402 v2 HTTP transport (PAYMENT-REQUIRED, PAYMENT-SIGNATURE)
- x402 protocol specification v1
- Circle: USDC contract addresses
- CAIP-2: Blockchain ID specification
- RFC 9110: HTTP Semantics, 15.5.3 402 Payment Required
Related
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}}'