Build with API#

This guide will walk you through integrating with x402 on the X Layer mainnet to enable payment functionality for your API or service. After completing this guide, your API will be able to charge buyers and AI agents for access.

Prerequisites#

Before you begin, make sure you have:

• A receiving wallet: any EVM-compatible wallet (e.g. OKX Wallet, OKX Agentic Wallet)
• An API key: apply via the OKX Developer Portal
• A business backend: your own API service or backend server

1. Get Supported Networks and Currencies#

Call the Get Basic Information endpoint to query the chains and settlement schemes currently available for payment. No business parameters are needed — only API authentication headers.

Execute:

GET https://web3.okx.com/api/v6/x402/supported

Response:

{
    "code": "0",
    "data": [
        {
               "x402Version": 1,
               "scheme": "exact",
               "chainIndex": "196",
               "chainName": "X Layer"
        }
    ],
    "msg": ""
}

View full parameters

2. Configure Payment Information#

When a buyer requests a resource, the seller should check whether the X-PAYMENT header is present. If not, return a 402 response along with the seller's receiving address.

Note the following:

• Include the following JSON in the PAYMENT-REQUIRED header
• The header value is Base64-encoded JSON
• amount uses the token's smallest unit (USDG has 6 decimals, so 1 USDG = 1000000)
• network uses CAIP-2 format (eip155:196 = X Layer)

{
  "x402Version": 1,
  "accepts": [{
    "network": "eip155:196",
    "amount": "123",
    "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "payTo": "0xYourRecepient",
    "maxTimeoutSeconds": 300,
    "extra": { 
        "name": "USDG", 
        "version": "2" 
      }
  }]
}

3. Transaction Verification#

When a buyer requests a resource and the X-PAYMENT header is present, the seller calls the Verify Transaction endpoint. The Facilitator will check signature validity, balance sufficiency, and consistency of amount and recipient address.

Execute:

POST https://web3.okx.com/api/v6/x402/verify

Response:

{
    "code": "0",
    "msg": "success",
    "data": [
        {
            "isValid": true,
            "invalidReason": null,
            "payer": "<payer-wallet-address>"
        }
    ]
}

View full parameters

4. Transaction Settlement#

After verification, the seller calls the Submit Transaction endpoint to initiate on-chain settlement. The Facilitator will submit the buyer's payment transaction to the blockchain, and upon confirmation, the seller will receive the funds. The Payment API supports two settlement modes:

• Synchronous settlementsyncSettle = true: The Facilitator submits the transaction, waits for on-chain confirmation, then returns the transaction hash.

• Asynchronous settlementsyncSettle = false: The Facilitator submits the transaction and returns the transaction hash immediately without waiting for on-chain confirmation — suitable for scenarios that prioritize response speed.

Execute:

POST https://web3.okx.com/api/v6/x402/settle

Response:

{
    "code": "0",
    "msg": "success",
    "data": [
        {
            "success": true,
            "errorReason": null,
            "payer": "<payer-wallet-address>",
            "txHash": "<transaction-hash>",
            "chainIndex": "196",
            "chainName": "X Layer"
        }
    ]
}

View full parameters