x402 V2

Payments

Every paid tool uses the same handshake. Browsers that prefer text/html get the paywall UI. Agents that prefer application/json get a JSON 402 body. Both include the base64 PAYMENT-REQUIRED header.

Cursor, Claude Desktop, and VS Code spawn one local stdio process. Config and spending-key payment: /docs/mcp. HTTP agents keep using @x402/fetch.

Parameters before payment

Unpaid requests return HTTP 402 even if query parameters or POST items are missing or invalid, so CDP and agents can index the path. After a PAYMENT-SIGNATURE, invalid params return HTTP 400 JSON before settlement. magent does not charge. Fix the params, then request a new 402 quote for that complete URL. Catalog misses (empty matches, found=false) are valid paid 200s.

Handshake

1. GET the tool with Accept: application/json (do not send Accept: text/html unless you want the human paywall).
2. HTTP 402 means you have not paid. Decode the base64 PAYMENT-REQUIRED header. HTTP 503 is not a new quote.
3. Sign accepts[0] (exact, EIP-3009) with validBefore = now + maxTimeoutSeconds (600 seconds), or accepts[1] (batch-settlement deposit/voucher) on product GET. Ping and POST {items} stay exact. Magent retries transient facilitator 429/5xx before answering.
4. Retry the same URL with PAYMENT-SIGNATURE (base64 JSON of accepted and payload). Magent attaches canonical extensions.bazaar on CDP verify/settle; echoing 402 bazaar is optional.
5. Success is HTTP 200 JSON plus PAYMENT-RESPONSE. exact settles before the tool. batch-settlement verifies (and deposit-settles) before the tool and commits the charge after HTTP 2xx. HTTP 503: retry the same PAYMENT-SIGNATURE. Mint a new exact nonce only after a new HTTP 402.

Guarantees

• HTTP 402 is unpaid, including a missing query. After PAYMENT-SIGNATURE, invalid parameters return HTTP 400 before settlement. You are not charged. HTTP 402 never includes the tool JSON.
• exact: settlement finishes before the tool (paymentFlow upfront). batch-settlement: verify/deposit before the tool; chargedCumulativeAmount commits after HTTP 2xx. Uncertain or failed settlement fails closed (HTTP 503). Retry the same PAYMENT-SIGNATURE.
• HTTP 402 is unpaid only. Do not sign a second authorization because of a 503.
• Execution is timeout-bounded and concurrency-capped.
• Calculator inputs are stored encrypted for allowlisted operators (Magent Console). They are not in public logs, SSH lookups, catalog, or rollups. Request logs store path without query.

Schemes

magent accepts only the offered schemes. CDP may list others; sending them is HTTP 402. Same-path POST {items} is still scheme exact: one EIP-3009 authorization for GET unit plus $0.002 per extra item. That is not x402 batch-settlement (payment channels / vouchers).

Payment channels (batch-settlement)

Deposit USDC into the x402 channel contract, then sign cumulative vouchers. Exact remains accepts[0] for one-off EIP-3009.

accepts[0] is always exact. accepts[1] is batch-settlement on product GET only, and only while offered. Ping and POST {items} stay exact.

• Not the same as POST {items} bulk (that is still exact).
• Product GET only. Ping, POST {items}, paywall.js, and canary stay exact.
• Verify (and deposit settle) before the tool. Charge commit after HTTP 2xx.
• Refund skips the tool. Full drain closes locally; a later deposit reopens the same channelId.

Headers

Shared payment errors

Tool-specific 400 codes live on each tool page. Those codes return before settlement; you are not charged. payment_required is listed once there after merge.