Typical integration flow
This document describes the end-to-end x402 payment flow between all participants.
Participants
| Role | Description |
|---|---|
| Client | AI Agent, DApp, or any HTTP client that requests a paid resource. |
| Merchant API Server | The partner (client) server that sells resources and integrates B402. |
| B402 Facilitator | The service that verifies and settles on-chain payments. |
| BNB Smart Chain | The blockchain network where token transfers are executed. |
Flow
Code
Steps
-
Client requests paid resource — The Client sends an HTTP request to the Merchant API for a resource that requires payment.
-
Merchant queries /supported — The Merchant calls the B402 Facilitator's
POST /supportedendpoint to retrieve accepted payment methods, tokens, and networks. This response can be cached. -
Merchant returns HTTP 402 — The Merchant responds to the Client with HTTP status
402 Payment Required, including the payment requirements (amount, token, network, payment methods, facilitator URL).⚠️ Merchant must forward facilitator addresses to the buyer. The 402 response's
paymentRequirements.extramust carrysignerAddress/spenderAddress(V2) orfacilitatorAddress(V1), copied from the matchingkinds[]entry in the cached/supportedresponse. Buyers do not — and cannot — call/supportedthemselves; the 402 response is the only channel through which they learn the Permit2 spender contract they need to sign against. See V2 — Forwarding Addresses to Buyers (or the V1 equivalent). -
Client signs EIP-712 authorization — The Client constructs and signs an EIP-712 typed data message authorizing the token transfer. This is done entirely off-chain and requires no gas.
-
Client retries with signed payload — The Client resends the original request to the Merchant, attaching the signed payment payload in the request header.
-
Merchant calls /verify — The Merchant forwards the payment payload to the B402 Facilitator's
POST /verifyendpoint to validate the EIP-712 signature, token balance, and authorization parameters off-chain. -
Merchant calls /settle — If verification succeeds, the Merchant calls
POST /settleto execute the on-chain settlement. -
B402 submits TX to BNB Smart Chain — The Facilitator submits the token transfer transaction to BNB Smart Chain. Gas fees are sponsored by the Facilitator, so the payer does not need BNB for gas.
-
Merchant delivers resource — Once settlement is confirmed, the Merchant delivers the requested resource to the Client.