B402 Payments

Integration Guide

Copy page

This guide describes the recommended x402 V2 merchant flow. B402 calls must come from your trusted backend and use the Web3 API Key created for the same Developer Portal project that completed B402 onboarding.

Portal Onboarding and Runtime API

The Developer Portal and the B402 runtime API serve different purposes:

Stage	Where it happens	What to use
Onboarding	Developer Portal	Select a project, complete the B402 Payments application, and configure the write-once payTo address.
Key setup	Developer Portal	Create an API Key in the same project with B402 Payments permission. If enabled, allow your backend's public egress IP.
Runtime	Merchant backend	Sign and call https://web3.binance.com/build/api/v2/b402/* with the API Key and Secret Key.

1. Create and Configure a B402-Enabled API Key

In the same Developer Portal project that completed B402 onboarding:

1. Open API Key Management and select Add New Key.
2. Enter a key name. On the API permissions step, select B402 Payments before creating the key. A key without this option cannot call any B402 endpoint.
3. If you configure an IP whitelist, add the stable public egress IP of the backend that will call B402. Do not add a private, local, or end-user IP.
4. When the success dialog appears, store both displayed values in your backend's secret manager. The Secret Key is shown only once; create or rotate the API Key if it is lost.

Portal value	Suggested backend setting	How B402 uses it
API Key	OC_API_KEY	Send as the X-OC-APIKEY header.
Secret Key	OC_SECRET_KEY	Use as the HMAC-SHA256 signing key. Never include it in a URL, header, or body.
Project	No request setting	The Web3 gateway derives it from the API Key; do not send projectCode.
payTo	Application configuration	Use the write-once onboarding address in HTTP 402 payment requirements.

Keep these credentials in a trusted backend. Never put the Secret Key in browser or mobile code, commit it to source control, or paste it into a client-side request.

Authenticate Web3 Requests

Every B402 request uses the standard Binance Web3 HMAC authentication headers:

• X-OC-APIKEY
• X-OC-TIMESTAMP
• X-OC-SIGN
• Optional: X-OC-RECV-WINDOW and X-OC-NONCE

Follow Authentication exactly. The signed request path includes /build, and the signature must use the exact raw JSON string sent on the wire.

The Web3 gateway resolves the B402 merchant from the authenticated project's tenant identity. Do not send or trust a client-supplied merchantId for Portal traffic.

2. Test the API Key with Supported

The following Node.js 18+ example is ready to use after OC_API_KEY and OC_SECRET_KEY are supplied through your local or deployment secret configuration. Do not change the host or remove /build from requestPath:

Code
import crypto from "node:crypto";

const apiKey = process.env.OC_API_KEY;
const secretKey = process.env.OC_SECRET_KEY;

if (!apiKey || !secretKey) {
  throw new Error(
    "Set OC_API_KEY and OC_SECRET_KEY from the Web3 Developer Portal",
  );
}

async function postB402(operation, requestBody) {
  const requestPath = `/build/api/v2/b402/${operation}`;
  const rawBody = JSON.stringify({ body: requestBody });
  const timestamp = new Date().toISOString();
  const preHash = timestamp + "POST" + requestPath + rawBody;
  const signature = crypto
    .createHmac("sha256", secretKey)
    .update(preHash, "utf8")
    .digest("base64");

  const response = await fetch(`https://web3.binance.com${requestPath}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-OC-APIKEY": apiKey,
      "X-OC-TIMESTAMP": timestamp,
      "X-OC-SIGN": signature,
    },
    body: rawBody,
  });
  const result = await response.json();

  if (!response.ok) {
    throw new Error(
      `B402 HTTP ${response.status}, code=${result.code ?? "unknown"}`,
    );
  }

  return result;
}

const supported = await postB402("supported", {});

if (supported.code !== "000000000") {
  throw new Error(`B402 readiness failed, code=${supported.code}`);
}

console.log(supported.data);

The helper accepts the object that belongs inside body and creates the outer {"body": ...} envelope once. It also signs and sends the same rawBody string. Reuse it for the other operations:

Code
await postB402("verify", {
  x402Version: 2,
  paymentPayload,
  paymentRequirements,
});

await postB402("settle", {
  x402Version: 2,
  paymentPayload,
  paymentRequirements,
});

For permit2-upto, add settleAmount to the inner Settle object shown above.

Read and Cache Supported Configurations

Call POST /api/v2/b402/supported when your service starts, then refresh periodically. An empty Supported request is:

Code
{
  "body": {}
}

The response contains kinds[], extensions, and signers. Select a kind matching the asset and transfer method you want to accept. Copy the entire matching kinds[].extra object into the paymentRequirements.extra object returned to the buyer.

Use this first Supported call as a readiness check:

• A successful response has envelope code 000000000.
• 1160401 means the same Developer Portal project has not completed B402 onboarding.
• Gateway code 40104 means an access policy rejected the call. Check the B402 Payments permission and API Key IP whitelist first; if both are correct, contact support to check the endpoint allowlist.

3. Return HTTP 402 to the Buyer

When payment is required, return an x402 V2 response such as:

Code
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "upto",
      "network": "eip155:56",
      "amount": "1000000",
      "asset": "0x1111111111111111111111111111111111111111",
      "payTo": "0x2222222222222222222222222222222222222222",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "Token Name",
        "version": "1",
        "assetTransferMethod": "permit2-upto",
        "signerAddress": "0x3333333333333333333333333333333333333333",
        "spenderAddress": "0x4444444444444444444444444444444444444444"
      }
    }
  ]
}

Amounts are decimal strings in the token's smallest unit. payTo must be the receiving address configured during B402 onboarding.

4. Receive the Signed Payment Payload

The buyer selects one requirement, signs its authorization, and retries the resource request with an x402 payment payload. Keep the original payment requirements server-side; do not let the buyer replace the amount, asset, network, payTo, timeout, or extra values.

Your backend must reject the buyer payload unless paymentPayload.accepted exactly matches the server-held paymentRequirements. Then send both objects unchanged to B402. The transfer-specific signed data is under paymentPayload.payload:

• authorization for eip3009.
• permit2Authorization for permit2-exact and permit2-upto.

5. Verify Before Settlement

Send the buyer payload and your original requirements to POST /api/v2/b402/verify:

Code
{
  "body": {
    "x402Version": 2,
    "paymentPayload": {
      "x402Version": 2,
      "resource": {
        "url": "https://merchant.example.com/weather",
        "description": "Premium weather report",
        "mimeType": "application/json"
      },
      "accepted": {
        "scheme": "exact",
        "network": "eip155:56",
        "amount": "1000000",
        "asset": "0x1111111111111111111111111111111111111111",
        "payTo": "0x2222222222222222222222222222222222222222",
        "maxTimeoutSeconds": 300,
        "extra": {
          "name": "Token Name",
          "version": "1",
          "assetTransferMethod": "eip3009",
          "signerAddress": "0x3333333333333333333333333333333333333333"
        }
      },
      "payload": {
        "signature": "0x...",
        "authorization": {
          "from": "0x5555555555555555555555555555555555555555",
          "to": "0x2222222222222222222222222222222222222222",
          "value": "1000000",
          "validAfter": "0",
          "validBefore": "1780000000",
          "nonce": "0x..."
        }
      }
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "eip155:56",
      "amount": "1000000",
      "asset": "0x1111111111111111111111111111111111111111",
      "payTo": "0x2222222222222222222222222222222222222222",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "Token Name",
        "version": "1",
        "assetTransferMethod": "eip3009",
        "signerAddress": "0x3333333333333333333333333333333333333333"
      }
    }
  }
}

Verify is off-chain and does not spend funds. Proceed only when data.isValid is true. A business validation failure still uses HTTP 200; inspect data.isValid, data.invalidReason, and the optional data.invalidMessage rather than relying only on the HTTP status.

6. Settle the Payment

Call POST /api/v2/b402/settle with the same body. For permit2-upto, also include body.settleAmount, which must not exceed the authorized paymentRequirements.amount.

Settlement submits an on-chain transaction and is irreversible. Treat it as successful only when data.success is true.

• success: true: record transaction, payer, network, and amount, then deliver the resource.
• success: false with a non-empty transaction: the transaction was broadcast; poll or reconcile before deciding whether to retry.
• success: false with an empty transaction: terminal pre-broadcast failure; use errorReason.

Settle is idempotent for the same signed authorization. Use bounded retries with backoff for transient failures, but never create a fresh buyer authorization automatically.

Operational Guidance

• Keep host clocks synchronized; stale timestamps are rejected.
• Persist settlement results using the signed authorization or transaction hash as an idempotency key.
• Log request IDs and transaction hashes, but never signatures, API secrets, or full authorization payloads.
• Build alerting around invalidReason, errorReason, HTTP 429, and infrastructure errors.
• Use Verify for every payment; do not deliver value based only on a buyer-provided signature.