主題

HTTP 端 API - 批量支付#

Buyer 在 AA 钱包内派发 Session Key 证书（sessionCert），所有调用都用 Session Key 签名，Facilitator 将多笔授权聚合后一次性上链结算。适用于高频小额、Agent 持续消费等场景。

Base URL：https://web3.okx.com
路径前缀：/api/v6/pay/x402
Scheme：aggr_deferred
Network：X Layer（CAIP-2 标识 eip155:196）

认证#

所有接口均需通过 API Key 认证，请求头中携带以下字段：

Header	必传	描述
`OK-ACCESS-KEY`	是	API Key
`OK-ACCESS-SIGN`	是	请求签名
`OK-ACCESS-PASSPHRASE`	是	API 密码短语
`OK-ACCESS-TIMESTAMP`	是	ISO 8601 时间戳
`Content-Type`	是	POST 请求需设为 `application/json`

所有响应统一使用业务包络：

json

{
  "code": "0",
  "msg": "success",
  "data": { /* 业务字段 */ }
}

业务错误时 code 为非 "0"，data 为 null，错误码集中见文末错误码章节。

与 `exact` 模式的差异#

接口路径与 exact 完全一致，关键字段差异如下：

字段	`exact`	`aggr_deferred`
`accepted.scheme`	`"exact"`	`"aggr_deferred"`
`accepted.extra.sessionCert`	无	必填：Session Key 证书（base64）
`payload.signature`	EOA 签名	Session Key 签名
`authorization.from`	EOA 地址	Buyer 的 AA 钱包地址
`settle.syncSettle`	可选，默认 `false`	不适用，忽略
`settle` 响应 `transaction`	链上 txHash	入库时为空串，批量上链后通过 `/settle/status` 获取
`settle` 响应 `status`	`pending` / `success` / `timeout` / `""`	入库即返回 `"success"`

sessionCert 流转：Buyer 在 paymentPayload.accepted.extra.sessionCert 中携带 → Seller 原样透传 → Facilitator 内部在 TEE 中提取并验证。Seller 无需解析此字段。paymentRequirements.extra 中不应出现 sessionCert。

1. /api/v6/pay/x402/supported#

GET

/api/v6/pay/x402/supported

查询 Facilitator 支持的 scheme、network 及签名者列表。批量模式下 kinds 包含 aggr_deferred 项。

请求参数#

无。

响应参数#

参数	类型	描述
`kinds`	`Array<SupportedKind>`	支持的支付类型列表
`kinds[].x402Version`	`Integer`	x402 协议版本，如 `2`
`kinds[].scheme`	`String`	结算方案：`exact` / `aggr_deferred`
`kinds[].network`	`String`	CAIP-2 链标识，如 `eip155:196`
`kinds[].extra`	`Object`	scheme 特有扩展配置
`extensions`	`Array<String>`	支持的扩展标识列表
`signers`	`Object`	CAIP-2 通配符 → 签名者地址数组映射

响应示例#

json

{
  "code": "0",
  "msg": "",
  "data": {
    "kinds": [
      { "x402Version": 2, "scheme": "exact",         "network": "eip155:196", "extra": null },
      { "x402Version": 2, "scheme": "aggr_deferred", "network": "eip155:196", "extra": null }
    ],
    "extensions": [],
    "signers": {
      "eip155:*": ["0x...facilitatorSignerAddress"]
    }
  }
}

2. /api/v6/pay/x402/verify#

POST

/api/v6/pay/x402/verify

校验 Buyer 的 PaymentPayload：

解析并校验 accepted.extra.sessionCert（TEE 内验证 AA 钱包签发链）。
校验 payload.signature 由 sessionCert 中授权的 Session Key 签出。
校验授权金额、有效期、payTo、asset 均落在 sessionCert 允许范围内。
校验 nonce 未被使用。

请求参数#

参数	类型	必传	描述
`x402Version`	`Integer`	是	x402 协议版本，如 `2`
`paymentPayload`	`Object`	是	客户端随受保护请求携带的 x402 支付载荷，详见 PaymentPayload
`paymentRequirements`	`Object`	是	Seller 定义的支付要求，详见 PaymentRequirements

约束：

paymentPayload.accepted.scheme 与 paymentRequirements.scheme 必须均为 "aggr_deferred"。
paymentPayload.accepted.extra.sessionCert 必填（base64 编码字符串）。

响应参数#

参数	类型	描述
`isValid`	`Boolean`	`true` 验证通过，`false` 验证失败
`invalidReason`	`String`	机器可读的无效原因（验证失败时返回）
`invalidMessage`	`String`	人类可读的无效说明（验证失败时返回）
`payer`	`String`	付款方 AA 地址

请求示例#

bash

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/verify' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z' \
--data '{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/llm/chat",
      "description": "LLM streaming chat per request",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "aggr_deferred",
      "network": "eip155:196",
      "amount": "10000",
      "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
      "payTo": "0xRecipientAddress",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDG",
        "version": "2",
        "sessionCert": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIweEFBQ..."
      }
    },
    "payload": {
      "signature": "0x...(Session Key 对 EIP-3009 message 的签名)",
      "authorization": {
        "from": "0xPayerAAAddress",
        "to": "0xRecipientAddress",
        "value": "10000",
        "validAfter": "0",
        "validBefore": "1740672154",
        "nonce": "0xf374661..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "aggr_deferred",
    "network": "eip155:196",
    "amount": "10000",
    "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
    "payTo": "0xRecipientAddress",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USDG", "version": "2" }
  }
}'

响应示例 — 验证通过#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "isValid": true,
    "invalidReason": null,
    "invalidMessage": null,
    "payer": "0xPayerAAAddress"
  }
}

响应示例 — sessionCert 失效#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "isValid": false,
    "invalidReason": "session_cert_expired",
    "invalidMessage": "sessionCert expired at 2026-04-21T12:00:00Z",
    "payer": "0xPayerAAAddress"
  }
}

3. /api/v6/pay/x402/settle#

POST

/api/v6/pay/x402/settle

将通过验证的授权入库，等待 Facilitator 后台聚合上链。返回时只代表"已接受"，不代表已上链。

请求参数#

参数	类型	必传	描述
`x402Version`	`Integer`	是	x402 协议版本，如 `2`
`paymentPayload`	`Object`	是	同 verify
`paymentRequirements`	`Object`	是	同 verify

aggr_deferred 模式忽略 syncSettle 字段。

响应参数#

参数	类型	描述
`success`	`Boolean`	是否成功入库
`errorReason`	`String`	入库失败的原因（机器可读）
`errorMessage`	`String`	失败说明（人类可读）
`payer`	`String`	付款方 AA 地址
`transaction`	`String`	入库时返回空串；批量上链后通过 `/settle/status` 获取
`network`	`String`	CAIP-2 链标识
`status`	`String`	入库成功固定 `"success"`

请求示例#

bash

curl --location --request POST 'https://web3.okx.com/api/v6/pay/x402/settle' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z' \
--data '{
  "x402Version": 2,
  "paymentPayload": { "...同 verify..." },
  "paymentRequirements": { "...同 verify..." }
}'

响应示例 — 入库成功#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": true,
    "errorReason": null,
    "errorMessage": null,
    "payer": "0xPayerAAAddress",
    "transaction": "",
    "network": "eip155:196",
    "status": "success"
  }
}

响应示例 — 入库失败#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": false,
    "errorReason": "session_cert_expired",
    "errorMessage": "sessionCert expired before settle",
    "payer": "0xPayerAAAddress",
    "transaction": "",
    "network": "eip155:196",
    "status": ""
  }
}

Seller 收到 success: true 后即可向 Buyer 放行资源；最终上链结果通过 /settle/status 异步追踪。

4. /api/v6/pay/x402/settle/status#

GET

/api/v6/pay/x402/settle/status

聚合上链完成后，Facilitator 会将批次的链上 txHash 关联到批次内每一笔原始支付。Seller 通过本接口查询。

请求参数#

参数	位置	类型	必传	描述
`txHash`	query	`String`	是	批量上链的链上交易哈希（由后端事件或异步通知告知 Seller）

响应参数#

参数	类型	描述
`success`	`Boolean`	查询是否成功
`errorReason`	`String`	失败原因
`errorMessage`	`String`	失败说明
`payer`	`String`	付款方 AA 地址
`transaction`	`String`	批量上链的 `txHash`
`network`	`String`	CAIP-2 链标识
`status`	`String`	`pending` / `success` / `failed`

请求示例#

bash

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/settle/status?txHash=0xbatchhash...' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z'

响应示例 — 批量上链成功#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": true,
    "payer": "0xPayerAAAddress",
    "transaction": "0xBatchTxHash...",
    "network": "eip155:196",
    "status": "success"
  }
}

响应示例 — 仍在聚合等待中#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": true,
    "payer": "0xPayerAAAddress",
    "transaction": "",
    "network": "eip155:196",
    "status": "pending"
  }
}

响应示例 — 链上失败#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": true,
    "payer": "0xPayerAAAddress",
    "transaction": "0xBatchTxHash...",
    "network": "eip155:196",
    "status": "failed"
  }
}

公共数据结构#

PaymentPayload#

Buyer 签名后通过 X-PAYMENT Header（base64 编码）传递给 Seller，Seller 原样透传给 Facilitator。

参数	类型	必传	描述
`x402Version`	`Integer`	是	协议版本，如 `2`
`resource`	`Object`	否	受保护资源描述
`resource.url`	`String`	是	受保护资源的 URL
`resource.description`	`String`	否	资源描述
`resource.mimeType`	`String`	否	预期响应的 MIME 类型
`accepted`	`Object`	是	Buyer 选中的支付方式（结构同 PaymentRequirements，但 `extra.sessionCert` 必填）
`payload`	`Object`	是	签名数据
`payload.signature`	`String`	是	Session Key 对 EIP-3009 message 的 EIP-712 签名
`payload.authorization`	`Object`	是	EIP-3009 授权参数，详见 Authorization

PaymentRequirements#

参数	类型	必传	描述
`scheme`	`String`	是	固定 `"aggr_deferred"`
`network`	`String`	是	CAIP-2 链标识，如 `eip155:196`
`amount`	`String`	是	支付金额（原子单位字符串）
`asset`	`String`	是	代币合约地址
`payTo`	`String`	是	收款钱包地址
`maxTimeoutSeconds`	`Integer`	否	支付完成的最大超时时间（秒）
`extra`	`Object`	否	扩展字段，详见下表

extra 字段（paymentPayload.accepted.extra 与 paymentRequirements.extra 略有差异）：

字段	类型	必传	描述
`name`	`String`	否	代币名称（如 `"USDG"`）
`version`	`String`	否	代币 EIP-712 domain 版本
`sessionCert`	`String`	是（仅在 `paymentPayload.accepted.extra` 中）	base64 编码的 Session Key 证书；`paymentRequirements.extra` 中不应包含此字段

Authorization#

参数	类型	必传	描述
`from`	`String`	是	付款方 AA 钱包地址
`to`	`String`	是	收款方钱包地址（应等于 `payTo`）
`value`	`String`	是	支付金额（原子单位）
`validAfter`	`String`	是	授权生效的 Unix 时间戳
`validBefore`	`String`	是	授权过期的 Unix 时间戳
`nonce`	`String`	是	32 字节随机 nonce（0x hex，防重放）

支持的网络和币种#

网络	Chain Index	状态
X Layer	196	已支持

X Layer 支持的稳定币：

币种	合约地址
USDG	`0x4ae46a509f6b1d9056937ba4500cb143933d2dc8`
USD₮0	`0x779ded0c9e1022225f8e0630b35a9b54be713736`
USDC	`0x74b7f16337b8972027f6196a17a631ac6de26d22`

错误码#

错误响应统一使用包络 {"code": "<code>", "msg": "<message>", "data": null}。

1. 认证错误（HTTP 401）#

错误码	描述
50103	请求头 `OK-ACCESS-KEY` 不能为空
50104	请求头 `OK-ACCESS-PASSPHRASE` 不能为空
50105	请求头 `OK-ACCESS-PASSPHRASE` 错误
50106	请求头 `OK-ACCESS-SIGN` 不能为空
50107	请求头 `OK-ACCESS-TIMESTAMP` 不能为空
50111	无效的 `OK-ACCESS-KEY`
50112	无效的 `OK-ACCESS-TIMESTAMP`
50113	无效的签名

2. 请求错误#

错误码	HTTP 状态	描述
50011	429	用户请求频率过快，超过该接口允许的限额
50014	400	必填参数 `{param}` 不能为空

3. 业务错误#

错误码	HTTP 状态	描述
50026	500	系统错误，请稍后重试
81001	200	`{param}` 参数错误
81004	200	不支持的链
80007	200	风险地址

4. verify / settle 业务字段#

x402 接口的失败原因通过响应 data 中的 invalidReason（verify）或 errorReason（settle / settle/status）返回，常见取值：

字段值	适用接口	描述
`session_cert_invalid`	verify, settle	sessionCert 解析或链验证失败
`session_cert_expired`	verify, settle	sessionCert 已过期
`session_key_signature_invalid`	verify	Session Key 签名无效
`out_of_session_scope`	verify	授权金额 / 收款方 / 资产超出 sessionCert 范围
`nonce_already_used`	verify, settle	nonce 已被使用
`insufficient_funds`	verify, settle	AA 钱包余额不足
`expired_authorization`	verify, settle	EIP-3009 授权已过期
`requirements_mismatch`	verify, settle	`accepted` 与 `paymentRequirements` 不一致
`aggregator_unavailable`	settle	聚合器服务不可用
`not_found`	settle/status	`txHash` 不在 Facilitator 记录中