x402 integration guide
Payment settled. Did the service deliver?
A transaction receipt and a useful API response answer different questions. Keep both outcomes in your agent's records so an application error does not become another payment.
Record two separate outcomes
Payment: confirmed, failed, or unknown. Service: a validated result, an application error, or no response. Keep the original request identifier, request parameters, transaction hash and returned result together.
A seller error message is not independent settlement evidence. Likewise, an HTTP success response does not establish that a later trade executed.
Test these four cases before launch
- Unpaid challenge: inspect the requested amount, asset, network and recipient. Do not sign until they match the authorized request.
- Paid success: retain settlement evidence and validate the returned application result.
- Paid application error: preserve both the settled payment and the error. Investigate delivery using the original evidence.
- Unknown payment status: reconcile the original attempt. Do not automatically create a fresh payment because a request timed out.
Where a provider supports idempotency, keep its key bound to the original method, URL and body. Confirm the provider's actual retry contract; a client-generated key alone does not prevent duplicate charges.
Check one supported Base flow
SafeRoute's first-call example starts with an unpaid challenge check. You choose whether to authorize the separate, bounded paid safety check locally. The example does not execute a swap.
Try the unpaid connection checkAsk about your integration — include the request ID and error, never a private key. We agree scope and acceptance before any paid implementation.
Technical background: Coinbase's x402 overview. This guide describes integration checks; it does not claim that a particular third-party implementation has passed them.