一种基于 HTTP 的互联网支付协议-技术接入说明

· 3 days ago

一种基于 HTTP 的互联网支付协议-技术接入说明

互联网支付存在根本性缺陷。信用卡支付门槛高、难以接受、最低还款额过高，而且与互联网的程序化特性格格不入。是时候推出一种开放的、原生于互联网的支付方式了。这种支付方式没有高额最低还款额和按百分比计费的手续费，对人类和人工智能代理来说都非常便捷。

x402 支付协议

“只需一行代码即可接受数字美元。无手续费，两秒结算，最低支付金额0.001美元。”

app.use(
  // How much you want to charge, and where you want the funds to land
  paymentMiddleware("0xYourAddress", { "/your-endpoint": "$0.01" })
);
// That's it! See examples/typescript/servers/express.ts for a complete example. Instruction below for running on base-sepolia.

哲学

原则

开放标准： x402 协议永远不会强制用户依赖任何单一方。
HTTP Native: x402 旨在无缝补充传统 Web 服务发出的现有 HTTP 请求，它不应强制执行超出典型客户端/服务器流程范围的额外请求。
我们欢迎对新链、签名标准或方案的支持，只要它们符合 CONTRIBUTING.md 中列出的接受标准即可。
降低信任风险： 所有支付方案均不得允许协调人或资源服务器转移资金，除非符合客户意愿。
易用性： x402 必须比现有的互联网支付方式好十倍。这意味着要尽可能地将加密细节从客户端和资源服务器端抽象出来，转移到支付服务端。也就是说，客户端/服务器端无需考虑 gas、rpc 等问题。

生态系统

x402 生态系统正在蓬勃发展！请访问我们的生态系统页面，查看使用 x402 构建的项目，其中包括：

客户端集成
服务和端点
生态系统基础设施和工具
学习和社区资源

想将您的项目添加到生态系统中吗？请参阅我们的 #adding-your-project-to-the-ecosystem">演示网站 README 文件，了解如何提交项目的详细说明。

路线图： 请参阅 ROADMAP.md

条款：

resource ：互联网上的某个东西。这可以是网页、文件服务器、RPC 服务、API，任何接受 HTTP/HTTPS 请求的互联网资源。
client ：想要付费购买资源的实体。
facilitator server ：促进链上支付的验证和执行的服务器。
resource server ：为客户端提供 API 或其他资源的 HTTP 服务器。

技术目标：

无需许可，对客户端和服务器都安全
客户端和资源服务器无需 Gass
资源服务器和客户端的集成非常简洁（服务器端一行代码，客户端一个函数）。
能够以牺牲响应速度为代价来换取付款保障
可扩展至不同的支付流程和支付链

V1 协议

x402 协议是一个与区块链无关的支付标准，它基于 HTTP，利用现有的 402 Payment Required HTTP 状态码来指示访问资源需要支付费用。

它具体说明如下：

服务器如何响应客户端以方便支付资源费用的模式（ PaymentRequirements ）
客户端为资源付款时设置的标准标头 X-PAYMENT
X-PAYMENT 标头中的数据采用标准模式和编码方法。
资源服务器验证和结算付款的推荐流程
REST 规范，用于描述资源服务器如何对远程第三方服务器（ facilitator ）执行验证和结算。
X-PAYMENT-RESPONSE 标头规范，资源服务器可以使用该标头在其 HTTP 响应中向客户端传达区块链交易详情。

V1 协议序列

以下概述了使用 x402 协议的支付流程。请注意，如果客户端已经知道资源的支付方式，则步骤 (1) 和 (2) 是可选的。

Client 向 resource server 发出 HTTP 请求。
Resource server 返回 402 Payment Required 状态，并在响应正文中 Payment Required Response JSON 对象。
Client 从服务器响应返回的 paymentRequirements 中选择一种，并根据所选 paymentRequirements 的 scheme 创建 Payment Payload 。
Client 向资源服务器发送带有 X-PAYMENT 标头的 HTTP 请求，其中包含 Payment Payload 。
Resource server 通过本地验证或将 Payment Payload 和 Payment Requirements POST 到 facilitator server 的 /verify 端点来验证 Payment Payload 是否有效。
Facilitator server 根据 Payment Payload 的 scheme 和 network 对对象进行验证，并返回 Verification Response 。
如果 Verification Response 有效，资源服务器将执行操作以完成请求。如果 Verification Response 无效，资源服务器将返回 402 Payment Required 状态码，并在响应正文中返回一个 Payment Required Response JSON 对象。
Resource server 要么直接与区块链交互来结算付款，要么将 Payment Payload 和 Payment PaymentRequirements POST 到 facilitator server 的 /settle 端点来结算付款。
Facilitator server 根据 Payment Payload 的 scheme 和 network 将支付提交到区块链。
Facilitator server 等待区块链上确认付款。
Facilitator server 向资源服务器返回 Payment Execution Response 。
Resource server 向 Client 返回 200 OK 响应，HTTP 响应正文包含客户端请求的资源，如果支付成功执行，则 X-PAYMENT-RESPONSE 标头包含 Base64 编码的 JSON 格式的 Settlement Response 。

类型规格

数据类型

需要付款回复

{
  // Version of the x402 payment protocol
  x402Version: int,

  // List of payment requirements that the resource server accepts. A resource server may accept on multiple chains, or in multiple currencies.
  accepts: [paymentRequirements]

  // Message from the resource server to the client to communicate errors in processing payment
  error: string
}

付款要求

{
  // Scheme of the payment protocol to use
  scheme: string;

  // Network of the blockchain to send payment on
  network: string;

  // Maximum amount required to pay for the resource in atomic units of the asset
  maxAmountRequired: uint256 as string;

  // URL of resource to pay for
  resource: string;

  // Description of the resource
  description: string;

  // MIME type of the resource response
  mimeType: string;

  // Output schema of the resource response
  outputSchema?: object | null;

  // Address to pay value to
  payTo: string;

  // Maximum time in seconds for the resource server to respond
  maxTimeoutSeconds: number;

  // Address of the EIP-3009 compliant ERC20 contract
  asset: string;

  // Extra information about the payment details specific to the scheme
  // For \`exact\` scheme on a EVM network, expects extra to contain the records \`name\` and \`version\` pertaining to asset
  extra: object | null;
}

Payment Payload （包含在 base64 编码的 JSON 中，作为 X-PAYMENT 标头）

{
  // Version of the x402 payment protocol
  x402Version: number;

  // scheme is the scheme value of the accepted \`paymentRequirements\` the client is using to pay
  scheme: string;

  // network is the network id of the accepted \`paymentRequirements\` the client is using to pay
  network: string;

  // payload is scheme dependent
  payload: <scheme dependent>;
}

引导者类型及界面

facilitator server 是一种第三方服务， resource server 可以使用它来验证和结算付款，而无需 resource server 访问区块链节点或钱包。

POST /verify 。使用支持的方案和网络验证付款：

请求正文 JSON：

回复：

{
  isValid: boolean;
  invalidReason: string | null;
}

POST /settle 。使用支持的支付方案和网络进行支付结算：

请求正文 JSON：

回复：

{
  // Whether the payment was successful
  success: boolean;
  // Error message from the facilitator server
  error: string | null;
  // Transaction hash of the settled payment
  txHash: string | null;
  // Network id of the blockchain the payment was settled on
  networkId: string | null;
}

获取 /supported 。获取支持的支付方案和网络：

回复：

{
  kinds: [
    {
      "scheme": string,
      "network": string,
    }
  ]
}

方案

计划是一种合乎逻辑的资金转移方式。

区块链提供了多种灵活的资金转移方式。为了更好地满足不断增长的支付应用场景， x402 协议通过其 scheme 字段可扩展至不同的支付结算方式。

根据完成支付所需的具体操作，每种支付方案可能具有不同的运行功能。例如，协议中首个推出的方案 exact 与 upto exact 行为就截然不同。exact 会转账特定金额（例如：支付 1 美元阅读一篇文章），而理论上的 upto 则会根据请求期间消耗的资源（例如：从 LLM 生成代币）转账至多一个金额。

有关方案的更多详细信息，请参阅 specs/schemes ，并参阅 specs/schemes/exact/scheme_exact_evm.md 以查看 EVM 链上第一个提出的精确支付方案。

方案与网络

因为方案是一种合理的资金转移方式，所以方案的实现方式在不同的区块链上可能有所不同。（例如：在以太坊上实现 exact 的方式与在 Solana 上实现 exact 的方式截然不同）。

客户和促进者必须明确支持不同的 (scheme, network) 组合，才能创建正确的有效载荷并验证/结算付款。

运行示例

要求： Node.js v24 或更高版本

从 examples/typescript 运行 pnpm install 和 pnpm build 以确保所有依赖包和示例都已设置。
选择一个服务器，例如 express，然后进入该示例的 cd 。将服务器的以太坊地址（用于接收付款）添加到 .env 文件中，然后在该目录中运行 pnpm dev 。
选择一个客户端，例如 axios，然后进入该示例 cd 。将用于支付的账户的私钥添加到 .env 文件中，然后在该目录下运行 pnpm dev 。

您应该会在客户端终端上看到活动，其中会显示天气预报。

运行测试

导航到 typescript 目录： cd typescript
安装依赖项： pnpm install
运行单元测试： pnpm test

这将运行 x402 软件包的单元测试。

作者 coinbase

来源 https://github.com/coinbase/x402