x402 seller operations
x402 seller checklist: 12 things that break agent payments
Published October 26, 2026 · SpendPreflight · AI-assisted, checked against the official sources linked below.
Use this checklist when an agent can discover your service but cannot complete its intended purchase. Start with a saved, redacted challenge and the exact deployed versions. A 402 response is an offer to negotiate payment; it is not evidence of buying intent.
Work from unpaid observations and local fixtures first. A paid reproduction needs an explicit budget and a compatible client. Do not paste wallet keys, signed authorizations or private customer inputs into a public issue.
1. The client expects a different protocol version
Compare the challenge and client SDK versions. For v2 HTTP, the transport uses PAYMENT-REQUIRED for the challenge and PAYMENT-SIGNATURE on the paid retry. Do not silently mix a legacy integration with v2 fields. Follow the HTTP transport specification.
2. A browser page replaces the machine-readable challenge
Inspect the public response outside your logged-in browser. Login redirects, proxy error pages and WAF challenges can prevent a client from seeing the payment requirements. Confirm status, response type and required fields before investigating the wallet.
3. The advertised payment choice is unsupported
Check scheme, network and asset together against the deployed SDK and your actual facilitator’s official supported values. Do not infer settlement support from an ecosystem listing. The v2 specification defines the negotiation fields; your operator decides its supported combinations.
4. The amount or asset representation is wrong
Compare the serialized challenge with the SDK output. Check atomic units and asset precision; do not substitute a human-readable currency amount where the protocol requires an integer amount. Review the configured recipient too. Never copy a token address or chain constant from memory.
5. The server does not register the selected mechanism
Compare middleware registration with the advertised route. A supported library on disk does not mean the running server enabled it. Use the matching official framework example and confirm production configuration after deployment.
6. The buyer signs a different resource or request
Compare the canonical resource, method and validated inputs on the initial request and retry. Do not let an incidental redirect, changed query or one-use input turn a retry into a different operation. Keep sensitive values out of public debug reports.
7. Browser access hides the protocol headers
For browser clients, verify CORS handling and exposure of the payment response headers through the deployed proxy. A header visible in curl may be inaccessible to browser JavaScript. Check the transport’s browser/CORS guidance and your client SDK.
8. Payment verification and fulfillment drift apart
Separate input validation, payment handling and fulfillment in your diagnosis. Use redacted local fixtures for malformed inputs and failure paths. For an explicitly authorized end-to-end payment test, verify the actual output as well as the settlement receipt; a transaction alone does not establish correct delivery.
9. MCP discovery is mistaken for a paid invocation
A client that initializes MCP or lists tools has not selected a paid operation. Confirm that its payment integration supports the MCP x402 transport; ordinary tool discovery does not supply a wallet, budget or signing policy. Do not send HTTP payment headers blindly into a different transport.
10. The settled payload omits Bazaar metadata
Check that the client echoes the advertised extension and supplies the resource. The Bazaar troubleshooting guide distinguishes successful settlement from catalog visibility. A server-only declaration is insufficient.
11. The discovery schema does not match the example
Validate your input example against the advertised schema. Review required input/output type fields and absolute resource URLs. The Bazaar specification is the source of truth; current helpers reduce hand-built schema mistakes. Keep schema references within the documented constraints.
12. Metadata tells agents what to obey instead of what the API does
Write a factual description and useful parameter help. Avoid unrelated commands, secret requests and instruction overrides. Coinbase’s metadata policy is separate from technical validation. A heuristic warning should prompt review, not an allegation against a seller.
Make the first check repeatable
Run free x402 Lint against the public endpoint, then read its dated report and limitations. It performs an unpaid GET; POST-only behavior and paid output can remain unassessed. A low risk score is not an audit or a safe-to-buy decision.
Use the x402 Lint GitHub Action for a repeatable public challenge check in CI. Shared quotas, robots and host pacing apply. Treat inconclusive results as a reason to inspect the observation, not to bypass a guard or retry indefinitely.
Watch the endpoint after deployment
14 days free for founding sellers
The first 10 eligible Basic registrations get 14 days of monitoring, subject to availability at registration. Start without a wallet or payment; confirm your email to enable alerts. Basic checks one endpoint hourly and listing risk best-effort daily. Scheduling and email delivery can be delayed. Manual renewal afterward is 9 USDC per 31 days; no automatic renewal.
Official references and limits
- v2 HTTP transport
- x402 v2 specification
- Seller quickstart
- MCP server guide
- Bazaar integration and extension specification
- Coinbase catalog policy
Protocol sources pinned to be54b7d. This checklist does not establish paid delivery, security, legal compliance or acceptance by a facilitator or catalog.