x402-api

x402

x402 是一项面向互联网原生支付的开放标准，旨在支持所有网络（包括加密货币和法币）以及各种价值形式（稳定币、代币、法币）。

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [...],                 // As many networks / schemes as you want to support
        description: "Weather data",    // what your endpoint does
      },
    },
  ),
);
// That's it! See examples/ for full details

# All available reference sdks
npm install @x402/core @x402/evm @x402/svm @x402/axios @x402/fetch @x402/express @x402/hono @x402/next @x402/paywall @x402/extensions

# Minimal Fetch client
npm install @x402/core @x402/evm @x402/svm @x402/fetch

# Minimal express Server
npm install @x402/core @x402/evm @x402/svm @x402/express

pip install x402

go get github.com/x402-foundation/x402/go

原则

• 开放标准： x402 是一项开放标准，任何人都可以免费访问和使用。它绝不会强制依赖单一参与方。
• 原生支持 HTTP / 传输： x402 旨在与现有数据传输方式无缝协作。只要可行，就不应要求在典型的客户端 / 服务端流程之外发送额外请求。
• 不依赖特定网络、代币和货币： 我们欢迎为新网络（包括加密货币和法币）、签名标准或方案添加支持，但须符合 CONTRIBUTING.md 中列出的验收标准。x402 可以扩展对法币网络的支持，但绝不会为了法币支付而降低链上支付的优先级。
• 向后兼容： 除非出于标准安全考虑而必须移除支持，否则 x402 不会弃用对任何现有网络的支持。在可行的情况下，x402 将力求保持非主要版本变更的向后兼容性。
• 尽量减少信任： 所有支付方案都不得允许 facilitator 或资源服务器移动资金，除非符合客户端的意图。
• 易于使用： x402 社区致力于提升其相较于互联网上其他支付形式的易用性。这意味着尽可能将加密货币相关细节从客户端和资源服务器中抽象出来，交由 facilitator 处理。客户端 / 服务端不应需要考虑 gas、rpc 等问题。

生态系统

x402 生态系统正在不断壮大！请查看我们的生态系统页面，了解使用 x402 构建的项目，包括：

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

想将你的项目添加到生态系统中？请参阅我们的 demo site README，了解提交项目的详细说明。

路线图： 请参阅 ROADMAP.md

文档： GitBook 文档源文件见 docs/

术语：

• resource：互联网上的内容，例如网页、文件服务器、RPC 服务、API，或任何接受 HTTP / HTTPS 请求的互联网资源。
• client：希望为某项资源付费的实体。
• facilitator：负责验证和执行一个或多个网络上的支付的服务端。
• resource server：为客户端提供 API 或其他资源的 HTTP 服务端。

技术目标：

• 对客户端、服务端和 facilitator 均无需许可且安全
• 尽可能降低客户端和资源服务器的采用门槛
• 尽可能简化资源服务器和客户端的集成（服务端只需 1 行，客户端只需 1 个函数）
• 能够在响应速度与支付保证之间进行权衡
• 可扩展到不同的支付流程和网络

规范

完整的 x402 标准文档见 specs/。

常见的 x402 流程

x402 支付通常遵循以下流程，但服务端拥有很大的灵活性。请参阅 examples/ 中的 advanced 文件夹。

以下概述了使用 x402 协议进行支付的流程。如果客户端已经知道资源接受的支付详情，则步骤（1）和（2）为可选步骤。

1. Client 向 resource server 发送 HTTP 请求。

2. Resource server 返回 402 Payment Required 状态，并通过 PAYMENT-REQUIRED 标头返回一个 PaymentRequired b64 对象。

3. Client 从服务端响应中选择一个 PaymentRequirements，并根据所选 PaymentRequirements 的 scheme 和 network 创建 PaymentPayload。

4. Client 发送 HTTP 请求，并在 PAYMENT-SIGNATURE 标头中携带 PaymentPayload，将请求发送到资源服务端。

5. Resource server 通过本地验证，或将 PaymentPayload 和 PaymentRequirements POST 到 facilitator 的 /verify 端点，验证 PaymentPayload 是否有效。

6. Facilitator 根据 PaymentPayload 的 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 响应，响应正文包含其请求的资源，并在 PAYMENT-RESPONSE 标头中包含以 Base64 编码的 JSON 格式的 Settlement Response。

方案

方案是转移资金的一种逻辑方式。

区块链支持大量灵活的资金转移方式。为了支持不断扩展的支付用例，x402 协议通过 scheme 字段实现扩展，以支持不同的支付结算方式。

每种支付方案的具体运行方式可能不同，具体取决于完成支付所需的操作。 例如，作为协议首个推出的方案，exact 与 upto 的行为会有所不同。exact 转移特定金额（例如，支付 $1 阅读一篇文章），而理论上的 upto 则会根据请求期间消耗的资源转移不超过指定金额的款项（例如，由 LLM 生成令牌）。

有关方案的更多详情，请参阅 specs/schemes；有关 EVM 链上精确支付的首个提议方案，请参阅 specs/schemes/exact/scheme_exact_evm.md。

方案与网络

由于方案是转移资金的一种逻辑方式，因此同一方案在不同区块链上的实现方式可能不同。（例如，在 Ethereum 上实现 exact 的方式与在 Solana 上实现 exact 的方式大不相同。）

客户端和促进者必须明确支持不同的 (scheme, network) 组合，才能创建合适的负载并验证／结算支付。