x402 payments USDC stablecoins tutorial

x402 协议完全指南：互联网原生支付的未来

深入了解 x402 协议如何通过 HTTP 402 状态码实现零手续费、即时到账的加密货币支付，以及如何在你的应用中集成 x402。

PayIn Team | | 15 分钟阅读

x402 协议

互联网诞生时，HTTP 协议的设计者们预留了一个特殊的状态码：402 Payment Required（需要付款）。三十多年来，这个状态码一直处于”保留未用”的状态，等待着一个真正能让互联网原生支付成为现实的技术方案。

2024 年，Coinbase 联合 Cloudflare 推出了 x402 协议，终于让这个尘封的状态码焕发生机。

什么是 x402？

x402 是一个开放的支付协议，它让服务器可以通过标准的 HTTP 响应来要求客户端付款，而客户端可以通过加密货币（主要是 USDC 稳定币）即时完成支付。

核心特点：

  • 零手续费：协议本身不收取任何费用
  • 即时到账：资金在 2 秒内到达你的钱包，而不是 T+2
  • 自托管：资金直接进入你的钱包，无需第三方托管
  • 开放标准：任何人都可以实现和使用

为什么需要 x402？

传统支付 vs x402

传统的在线支付存在诸多问题：

问题传统支付x402
手续费2.9% + $0.300%
到账时间T+2（2个工作日）2 秒
拒付风险有 chargeback 风险链上交易不可逆
账户风险可能被冻结自托管，完全控制
跨境支付复杂、昂贵全球统一，无边界

对于开发者来说，x402 还有一个巨大优势：一行代码集成。

x402 如何工作？

x402 支付流程

x402 的工作流程非常简单：

步骤 1：客户端请求资源

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

步骤 2：服务器返回 402

如果资源需要付费，服务器返回 HTTP 402 状态码，并在响应中包含支付要求：

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmountRequired": "1000000",
    "payTo": "0xYourWalletAddress",
    "resource": "https://example.com/api/premium-content"
  }],
  "x402Version": 1
}

步骤 3：客户端签名并重新请求

客户端使用加密钱包对支付进行签名，并在请求头中附带支付信息：

GET /api/premium-content HTTP/1.1
Host: example.com
X-PAYMENT: eyJwYXlsb2FkIjp7...base64编码的支付信息...}

步骤 4：服务器验证并返回内容

服务器通过 Facilitator 验证支付有效性，然后返回请求的内容：

HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVl...}
Content-Type: application/json

{
  "data": "这是你购买的内容"
}

整个流程在几秒钟内完成，用户体验流畅。

核心概念

Payment Requirements（支付要求）

服务器返回的支付要求包含以下关键信息：

  • scheme: 支付方案，目前主要是 exact（精确金额）
  • network: 区块链网络，如 base、base-sepolia、polygon
  • asset: 代币合约地址（通常是 USDC）
  • maxAmountRequired: 需要支付的金额（最小单位）
  • payTo: 收款钱包地址

Facilitator（支付促进者）

Facilitator 是一个中间服务，负责：

  1. 验证支付签名的有效性
  2. 结算交易到区块链
  3. 确认支付已完成

默认的公共 Facilitator 是 https://x402.org/facilitator，你也可以自建。

Paywall（支付墙）

当浏览器访问需要付款的资源时，x402 会返回一个精美的支付页面，引导用户连接钱包并完成支付。这个页面是自动生成的，也可以自定义。

支持的网络

x402 目前支持以下区块链网络：

EVM 网络

网络Network ID类型
BasebaseMainnet
Base Sepoliabase-sepoliaTestnet
PolygonpolygonMainnet
Polygon Amoypolygon-amoyTestnet
AvalancheavalancheMainnet
AbstractabstractMainnet
SeiseiMainnet

Solana 网络

网络Network ID类型
SolanasolanaMainnet
Solana Devnetsolana-devnetTestnet

快速开始

以 Hono 框架为例，只需几行代码即可添加支付功能：

npm install 402ok-hono
import { Hono } from "hono";
import { paymentMiddleware } from "402ok-hono";

const app = new Hono();

// 你的收款钱包地址
const PAY_TO = "0xYourWalletAddress";

// 配置付费端点
const paidRoutes = {
  "GET /api/premium": {
    price: "$0.01",           // 价格
    network: "base-sepolia",  // 网络
    config: {
      description: "Access premium content",
    },
  },
};

// 应用支付中间件
app.use("/api/premium", paymentMiddleware(PAY_TO, paidRoutes));

// 付费内容
app.get("/api/premium", (c) => {
  return c.json({ message: "Welcome to premium content!" });
});

就这么简单！当用户访问 /api/premium 时：

  1. 如果没有付款，返回 402 和支付页面
  2. 用户通过钱包付款
  3. 付款成功后，返回内容

适用场景

x402 特别适合以下场景：

1. API 变现

为你的 AI 接口、数据 API 添加按次收费功能。

2. 数字商品

销售电子书、课程、软件许可等数字内容。

3. 电商支付

为独立站添加加密货币支付选项，特别适合跨境电商。

4. 内容付费

博客文章、视频、音乐等内容的单篇购买。

5. 打赏捐赠

为开源项目、创作者接收 USDC 打赏。

与其他方案对比

特性x402StripeCoinbase Commerce
手续费0%2.9% + $0.301%
到账时间即时T+2即时
托管模式自托管托管托管
集成难度简单中等简单
支持货币USDC法币多种加密货币
开源是否否

下一步

现在你已经了解了 x402 的基本概念，可以继续深入学习：

资源链接

x402 正在改变互联网支付的方式。加入这场革命，让你的应用拥抱互联网原生支付的未来。

返回所有文章