一种基于 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 构建的项目，其中包括：

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

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

路线图： 请参阅 ROADMAP.md

条款：

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

技术目标：

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

V1 协议

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

它具体说明如下：

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

V1 协议序列

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

1. Client 向 resource server 发出 HTTP 请求。
2. Resource server 返回 402 Payment Required 状态，并在响应正文中 Payment Required Response JSON 对象。
3. Client 从服务器响应返回的 paymentRequirements 中选择一种，并根据所选 paymentRequirements 的 scheme 创建 Payment Payload 。
4. Client 向资源服务器发送带有 X-PAYMENT 标头的 HTTP 请求，其中包含 Payment Payload 。
5. Resource server 通过本地验证或将 Payment Payload 和 Payment Requirements POST 到 facilitator server 的 /verify 端点来验证 Payment Payload 是否有效。
6. Facilitator server 根据 Payment Payload 的 scheme 和 network 对对象进行验证，并返回 Verification Response 。
7. 如果 Verification Response 有效，资源服务器将执行操作以完成请求。如果 Verification Response 无效，资源服务器将返回 402 Payment Required 状态码，并在响应正文中返回一个 Payment Required Response JSON 对象。
8. Resource server 要么直接与区块链交互来结算付款，要么将 Payment Payload 和 Payment PaymentRequirements POST 到 facilitator server 的 /settle 端点来结算付款。
9. Facilitator server 根据 Payment Payload 的 scheme 和 network 将支付提交到区块链。
10. Facilitator server 等待区块链上确认付款。
11. Facilitator server 向资源服务器返回 Payment Execution Response 。
12. 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 或更高版本

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

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

运行测试

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

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