使用 API 搭建#
本指南将引导您在 X Layer 主网上完成与 x402 的集成，从而为您的 API 或服务启用支付功能。完成本指南后，您的 API 将能够向买家和 AI 代理收取访问费用。
准备工作#
开始之前，请确保您已准备好：
- 收款钱包：任何 EVM 兼容钱包（如 OKX 钱包、OKX Agentic Wallet）
- API 密钥：通过OKX开发者管理平台申请
- 业务后端：您自己的 API 服务或后台服务器
1. 获取支持的网络和币种#
调用 获取基本信息 接口，查询当前可用于支付的链和结算方案，无需传入业务参数，仅需携带 API 鉴权头。
执行：
Shell
GET https://web3.okx.com/api/v6/x402/supported
返回内容：
Shell
{
"code": "0",
"data": [
{
"x402Version": 1,
"scheme": "exact",
"chainIndex": "196",
"chainName": "X Layer"
}
],
"msg": ""
}
2. 设置收款信息#
买家请求资源时，卖家需判断请求头中是否有 X-PAYMENT，如果没有，此时需返回 402 响应以及卖家的收款地址。
需注意以下几点：
- 在
PAYMENT-REQUIRED标头中包含以下 JSON 信息 - 标头值为 Base64 编码的 JSON
amount使用代币最小单位（USDG 精度 6 位，1 USDG = 1000000）network使用 CAIP-2 格式（eip155:196= X Layer）
Shell
{
"x402Version": 1,
"accepts": [{
"network": "eip155:196",
"amount": "123",
"asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
"payTo": "0xYourRecepient",
"maxTimeoutSeconds": 300,
"extra": {
"name": "USDG",
"version": "2"
}
}]
}
3. 交易验证#
买家请求资源时，如果请求头中有 X-PAYMENT，卖家调用交易验证 接口， Facilitator 会检查签名有效性、余额充足性、金额与收款地址一致性。
执行：
Shell
POST https://web3.okx.com/api/v6/x402/verify
返回内容：
Shell
{
"code": "0",
"msg": "success",
"data": [
{
"isValid": true,
"invalidReason": null,
"payer": "<payer-wallet-address>"
}
]
}
4. 交易结算#
验证通过后，卖家调用交易结算 接口发起链上结算，Facilitator 会把买家的付款交易提交到链上，上链后，卖家将收到资金。 支付 API 支持两种结算模式：
- 同步结算
syncSettle = true：Facilitator 提交交易，等待链上确认后再返回交易哈希。
- 异步结算
syncSettle = false：Facilitator 提交交易，不等待上链即返回交易哈希，适合追求响应速度的场景
提示
异步结算时，交易验证与链上结算之间存在短暂时间差，可能出现商品已下发但最终收款未完成的情况。对于金额较高的交易，建议使用同步结算模式以降低该风险。
执行：
Shell
POST https://web3.okx.com/api/v6/x402/settle
返回内容：
Shell
{
"code": "0",
"msg": "success",
"data": [
{
"success": true,
"errorReason": null,
"payer": "<payer-wallet-address>",
"txHash": "<transaction-hash>",
"chainIndex": "196",
"chainName": "X Layer"
}
]
}