跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

x402 协议

最后更新 查看 MarkdownAgent 设置

x402 ↗ 是一种 HTTP 付款协议。Monetization Gateway 使用 x402 版本 2,在一次 HTTP 交换中请求并结算付款。

该协议使用两个面向客户端的标头。每个标头都包含 Base64 编码的 JSON。

标头 方向 用途
PAYMENT-REQUIRED 网关到客户端 描述资源和可接受的付款选项。
PAYMENT-SIGNATURE 客户端到网关 提供已签署的付款授权。

请求受保护资源

客户端首先在不带付款的情况下请求资源:

GET /premium-data HTTP/1.1
Host: api.example.com

Monetization 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 付款。

在源站验证(Cloudflare 特定)

在验证客户端授权后,Monetization Gateway 会将请求转发到你的源站。它会添加包含已签署 JSON Web Token (JWT) 的 PAYMENT-CONTEXT 标头。

在提供付费资源之前,源站必须验证此令牌。可变价格源站还会在 PAYMENT-SETTLEMENT 中返回实际收费。这些标头用于 Monetization Gateway 与源站之间,不是 x402 客户端标头。

验证和结算要求请参阅 付款验证。

返回资源

结算成功后,Monetization Gateway 返回源站响应。

如果验证或结算失败,网关不会提供受保护资源。客户端应在重试前检查 HTTP 状态和 x402 响应。

这篇文档对您有帮助吗?