x402 ↗ 是一种 HTTP 付款协议。Monetization Gateway 使用 x402 版本 2,在一次 HTTP 交换中请求并结算付款。
该协议使用两个面向客户端的标头。每个标头都包含 Base64 编码的 JSON。
| 标头 | 方向 | 用途 |
|---|---|---|
PAYMENT-REQUIRED |
网关到客户端 | 描述资源和可接受的付款选项。 |
PAYMENT-SIGNATURE |
客户端到网关 | 提供已签署的付款授权。 |
客户端首先在不带付款的情况下请求资源:
GET /premium-data HTTP/1.1
Host: api.example.comMonetization Gateway 以 402 Payment Required 响应。PAYMENT-REQUIRED 标头包含编码后的付款要求:
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <BASE64_ENCODED_PAYMENT_REQUIRED>Base64 解码后,固定价格响应的大致结构如下:
{
"x402Version": 2,
"resource": {
"url": "https://api.example.com/premium-data",
"description": "Premium data",
"mimeType": "application/json"
},
"accepts": [
{
"scheme": "exact",
"network": "<CAIP_2_NETWORK>",
"asset": "<ASSET_IDENTIFIER>",
"amount": "25000",
"payTo": "<RECEIVING_WALLET>",
"maxTimeoutSeconds": 3600,
"extra": {}
}
]
}accepts 数组告诉客户端如何付款。重要字段包括:
| 字段 | 描述 |
|---|---|
scheme |
付款 scheme。Monetization Gateway 对固定定价使用 exact,对可变定价使用 upto。 |
network |
CAIP-2 格式的区块链网络标识符。 |
asset |
用于付款的资产标识符。 |
amount |
以原子单位表示的固定收费或最高授权收费。 |
payTo |
卖方配置的收款钱包。 |
maxTimeoutSeconds |
付款授权允许的最长时间。 |
客户端选择一个可接受选项并签署付款授权。然后使用 PAYMENT-SIGNATURE 标头重复该请求:
GET /premium-data HTTP/1.1
Host: api.example.com
PAYMENT-SIGNATURE: <BASE64_ENCODED_PAYMENT_PAYLOAD>已签署的 payload 将授权绑定到所选付款要求。请使用 x402 客户端库创建此 payload,而不是手动构造。
要实现付款客户端,请参阅 x402 付款。要从 Cloudflare Agent 付款,请参阅 从 Agents SDK 付款。
在验证客户端授权后,Monetization Gateway 会将请求转发到你的源站。它会添加包含已签署 JSON Web Token (JWT) 的 PAYMENT-CONTEXT 标头。
在提供付费资源之前,源站必须验证此令牌。可变价格源站还会在 PAYMENT-SETTLEMENT 中返回实际收费。这些标头用于 Monetization Gateway 与源站之间,不是 x402 客户端标头。
验证和结算要求请参阅 付款验证。
结算成功后,Monetization Gateway 返回源站响应。
如果验证或结算失败,网关不会提供受保护资源。客户端应在重试前检查 HTTP 状态和 x402 响应。