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

Client             Merchant            B402           BNB Smart Chain
  |                   |                Facilitator                 |
  |  1. Request       |                     |                      |
  |  paid resource    |                     |                      |
  |------------------>|                     |                      |
  |                   |  2. POST /supported |                      |
  |                   |  (cached)           |                      |
  |                   |-------------------->|                      |
  |                   |<--------------------|                      |
  |  3. HTTP 402      |                     |                      |
  |  + payment req    |                     |                      |
  |<------------------|                     |                      |
  |                   |                     |                      |
  |  4. Sign EIP-712  |                     |                      |
  |  authorization    |                     |                      |
  |  (off-chain,      |                     |                      |
  |   no gas needed)  |                     |                      |
  |                   |                     |                      |
  |  5. Retry with    |                     |                      |
  |  signed payload   |                     |                      |
  |------------------>|                     |                      |
  |                   |  6. POST /verify    |                      |
  |                   |-------------------->|                      |
  |                   |<--------------------|                      |
  |                   |                     |                      |
  |                   |  7. POST /settle    |                      |
  |                   |-------------------->|                      |
  |                   |                     |  8. Submit TX        |
  |                   |                     |  (gas sponsored)     |
  |                   |                     |--------------------->|
  |                   |                     |<---------------------|
  |                   |<--------------------|                      |
  |  9. Deliver       |                     |                      |
  |  resource         |                     |                      |
  |<------------------|                     |                      |

Steps

1. Client requests paid resource — The Client sends an HTTP request to the Merchant API for a resource that requires payment.

2. Merchant queries /supported — The Merchant calls the B402 Facilitator's POST /supported endpoint to retrieve accepted payment methods, tokens, and networks. This response can be cached.

3. 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.extra must carry signerAddress / spenderAddress (V2) or facilitatorAddress (V1), copied from the matching kinds[] entry in the cached /supported response. Buyers do not — and cannot — call /supported themselves; 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).

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

5. Client retries with signed payload — The Client resends the original request to the Merchant, attaching the signed payment payload in the request header.

6. Merchant calls /verify — The Merchant forwards the payment payload to the B402 Facilitator's POST /verify endpoint to validate the EIP-712 signature, token balance, and authorization parameters off-chain.

7. Merchant calls /settle — If verification succeeds, the Merchant calls POST /settle to execute the on-chain settlement.

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

9. Merchant delivers resource — Once settlement is confirmed, the Merchant delivers the requested resource to the Client.