主题

HTTP 端 API - 单次支付#

Buyer 每次访问受保护资源时即时签一次 EIP-3009 授权，Facilitator 单笔上链结算。对齐 Coinbase x402 V2 协议，附 OKX 扩展。

Base URL：https://web3.okx.com
路径前缀：/api/v6/pay/x402
Scheme：exact
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，错误码集中见文末错误码章节。

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

GET

/api/v6/pay/x402/supported

查询 Facilitator 支持的 scheme、network 及签名者列表。Seller SDK 调用此接口构建 402 响应的 accepts 数组。

请求参数#

无。

响应参数#

参数	类型	描述
`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 通配符 → 签名者地址数组映射

请求示例#

bash

curl --location --request GET 'https://web3.okx.com/api/v6/pay/x402/supported' \
--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": "",
  "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 签名的支付授权有效性，不执行链上交易。

请求参数#

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

约束：paymentPayload.accepted.scheme 与 paymentRequirements.scheme 必须均为 "exact"。

响应参数#

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

请求示例#

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/premium-data",
      "description": "Access to premium data",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:196",
      "amount": "10000",
      "asset": "0x4ae46a509f6b1d9056937ba4500cb143933d2dc8",
      "payTo": "0xRecipientAddress",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDG", "version": "2" }
    },
    "payload": {
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480...",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "to": "0xRecipientAddress",
        "value": "10000",
        "validAfter": "0",
        "validBefore": "1740672154",
        "nonce": "0xf374661..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "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": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d"
  }
}

响应示例 — 验证失败#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "isValid": false,
    "invalidReason": "insufficient_funds",
    "invalidMessage": "Payer balance is below required amount",
    "payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d"
  }
}

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

POST

/api/v6/pay/x402/settle

验证通过后，提交链上结算。exact 模式每次调用都会发起一笔独立的 transferWithAuthorization 链上交易。

请求参数#

参数	类型	必传	描述
`x402Version`	`Integer`	是	x402 协议版本，如 `2`
`paymentPayload`	`Object`	是	同 verify
`paymentRequirements`	`Object`	是	同 verify
`syncSettle`	`Boolean`	否	OKX 扩展。`true`=同步等待链上确认；`false`（默认）=异步广播

响应参数#

参数	类型	描述
`success`	`Boolean`	结算是否成功
`errorReason`	`String`	机器可读的失败原因（失败时返回）
`errorMessage`	`String`	人类可读的失败说明（失败时返回）
`payer`	`String`	付款方钱包地址
`transaction`	`String`	链上交易哈希
`network`	`String`	CAIP-2 链标识
`status`	`String`	OKX 扩展。结算状态，见下表

status 取值：

`syncSettle`	结果	`status`	`transaction`
`false`（默认）	已广播	`pending`	txHash
`true`	链上确认成功	`success`	txHash
`true`	等待超时	`timeout`	txHash
—	验签 / 模拟 / 链上失败	`""`	`""`

请求示例#

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..." },
  "syncSettle": true
}'

响应示例 — 同步结算成功（syncSettle=true）#

json

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

响应示例 — 异步结算（syncSettle=false）#

json

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

响应示例 — 结算失败#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": false,
    "errorReason": "insufficient_funds",
    "errorMessage": "Transaction reverted",
    "payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d",
    "transaction": "",
    "network": "eip155:196",
    "status": ""
  }
}

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

GET

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

根据链上交易哈希查询结算状态，适用于 syncSettle=false 异步结算的轮询场景。

请求参数#

参数	位置	类型	必传	描述
`txHash`	query	`String`	是	链上交易哈希

响应参数#

参数	类型	描述
`success`	`Boolean`	查询是否成功（`txHash` 不存在时为 `false`）
`errorReason`	`String`	机器可读的失败原因
`errorMessage`	`String`	人类可读的失败说明
`payer`	`String`	付款方钱包地址
`transaction`	`String`	链上交易哈希
`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=0x4f46ed8eac92ddbccfb56a88ff827db3616c7beb191adabbeeded901340bd7d5' \
--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,
    "errorReason": null,
    "errorMessage": null,
    "payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d",
    "transaction": "0x4f46ed8eac92ddbccfb56a88ff827db3616c7beb191adabbeeded901340bd7d5",
    "network": "eip155:196",
    "status": "success"
  }
}

响应示例 — 交易未找到#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "success": false,
    "errorReason": "not_found",
    "errorMessage": "Transaction not found for txHash: 0xabc123...",
    "payer": null,
    "transaction": null,
    "network": null,
    "status": null
  }
}

公共数据结构#

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 选中的支付方式（从 `accepts` 数组中选取），结构同 PaymentRequirements
`payload`	`Object`	是	签名数据
`payload.signature`	`String`	是	EIP-712 签名（EOA 签名）
`payload.authorization`	`Object`	是	EIP-3009 授权参数，详见 Authorization

PaymentRequirements#

同时用作 402 响应 accepts 数组元素和 paymentPayload.accepted。

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

Authorization#

参数	类型	必传	描述
`from`	`String`	是	付款方钱包地址（EOA）
`to`	`String`	是	收款方钱包地址（应等于 `payTo`）
`value`	`String`	是	支付金额（原子单位，应等于 `amount`）
`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）返回，常见取值：

字段值	适用接口	描述
`insufficient_funds`	verify, settle	付款方余额不足
`nonce_already_used`	verify, settle	nonce 已被使用
`expired_authorization`	verify, settle	授权已过期
`signature_invalid`	verify, settle	签名校验失败
`requirements_mismatch`	verify, settle	`accepted` 与 `paymentRequirements` 不一致
`transaction_reverted`	settle	链上交易回滚
`chain_unavailable`	settle	链上 RPC 不可用
`not_found`	settle/status	`txHash` 不在 Facilitator 记录中

认证

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

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

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

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

公共数据结构

错误码