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

  1. Unpaid challenge: inspect the requested amount, asset, network and recipient. Do not sign until they match the authorized request.
  2. Paid success: retain settlement evidence and validate the returned application result.
  3. Paid application error: preserve both the settled payment and the error. Investigate delivery using the original evidence.
  4. 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 check

Ask 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.