Define the paid result before choosing a wallet
Start with one endpoint and a precise unit of value: one validated address, one licensed image or one completed report. Write down the request parameters, response schema, price unit and maximum work. A route that performs expensive work before checking payment can still create an abuse problem.
This guide is an implementation and testing plan, not a claim that a sample application has been deployed or audited. Use the maintained seller and buyer quickstarts for executable code matching your language and package version. Start on a supported testnet with a dedicated wallet and test assets.
Map the V2 request cycle
V2 communicates payment terms in PAYMENT-REQUIRED, the client’s authorization in PAYMENT-SIGNATURE, and settlement information in PAYMENT-RESPONSE. These headers carry Base64-encoded JSON. Base64 is an encoding, not encryption. Avoid mixing an older X-PAYMENT tutorial with a V2 client and server.
Draw a sequence for your chosen scheme: request, terms, policy check, signed retry, verification, settlement handling and response. Put a distinct failure branch beside each step. Decide exactly when the expensive operation begins and when its result can be released. Do not use an “authorized” state as a synonym for “settled.”
Choose a compatible stack
The current seller quickstart documents framework integrations such as @x402/express with @x402/core and relevant network packages. Record exact versions in your lockfile and start from one official minimal example. The public x402.org facilitator is intended for development and testnet use; production needs an appropriate provider or your own supported verification and settlement infrastructure.
For each candidate, record the scheme, network, token, wallet requirements, facilitator support and operational cost. Coinbase’s managed services and Cloudflare’s gateway are options to investigate, not requirements of the open protocol. Cloudflare’s September 2026 gateway announcement describes eligibility restrictions; confirm current access before planning around it.
Keep the price and permissions explicit
Use integer asset units at the boundary where the SDK expects them, and use its documented price conversion when available. In an illustrative six-decimal asset, 0.01 token equals 10,000 smallest units: 0.01 × 1,000,000. Never infer decimals from a ticker or pass a floating-point dollar value where an integer token amount is required.
The client should allow only intended origins, routes, recipients, assets and maximum amounts. Reserve spending before dispatch and release the reservation only after a known result. Store signing material in an appropriate secure service, not browser JavaScript or a repository. A website asking an agent to ignore its budget is untrusted input, not a new spending policy.
Keep your route’s ordinary authorization rules. Paying for a response must not let one customer read another customer’s private report. Payment proves a financial condition; access control determines whose record can be returned.
Treat a timeout as an unknown outcome
A network timeout can occur after payment has succeeded. Blindly signing another payment may create a second charge. The optional payment-identifier extension lets compatible clients and servers associate retries with an identifier and deduplicate processing. It requires implementation and state; it is not a promise that every x402 deployment handles retries for you.
Bind the identifier to the operation, payer and relevant request data. A reused identifier with different parameters should be rejected. Store enough state to reconcile after a restart, and use shared storage if multiple server instances accept retries. Separately ensure the underlying job is idempotent: deduplicating payment alone does not prevent two emails, two bookings or two reports.
Run this failure test matrix
Use test assets and inspect both the HTTP result and payment state. Record the versions, network and expected outcome for each test. A green happy-path request is insufficient evidence that a payment endpoint is ready.
- Missing payment: returns the expected terms without running the paid job.
- Wrong network, asset, recipient, expired authorization or excessive amount: rejected.
- Successful payment: returns the promised schema and a traceable payment outcome.
- Timeout after settlement: retry reconciles without another charge for the same operation.
- Concurrent identical retries: one charge and one underlying job.
- Same identifier with a different body: rejected rather than returning the wrong result.
- Facilitator outage and server restart: bounded retries and a recoverable pending state.
- Paid response contains another user’s identifier: denied by access controls.
Release with a stop switch and a reconciliation view
Keep a private versioned copy of the tested configuration and a way to disable paid requests without corrupting pending jobs. Begin with a limited route and controlled traffic. Monitor usable results, payment failures, pending settlements, refunds and cost per successful operation. Avoid storing wallet secrets or unnecessary customer data in logs.
Define a manual support path for “paid but no result” before your first real customer. Reconcile the seller’s operation ID, payment ID and chain or provider evidence. A dashboard counter alone is not financial reconciliation. Repeat the affected tests when the SDK, payment scheme or facilitator changes.
Sources & further reading
- x402 seller quickstart: current SDK and testnet setup
- x402 buyer quickstart: client configuration
- x402 documentation: HTTP 402 and V2 payment headers
- x402 documentation: facilitator responsibilities and deployment choices
- Cloudflare: Monetization Gateway closed beta, September 30, 2026
- x402 payment-identifier extension: retry deduplication
Educational content. Examples are illustrative. Protocols, products and rules can change; consult the linked documentation for current details.