DEV Community

justqueue
justqueue

Posted on

x402 开发者指南：构建付费 API 服务

#node #web3 #api #tutorial

本指南将系统性地介绍如何将 x402 协议集成到你的应用中。完成本教程后，你将掌握付费 API 的完整实现方案，并透彻理解 x402 的支付机制。

准备工作

在开始之前，请确保具备以下条件：

  • Node.js 18+ 运行环境
  • EVM 兼容钱包地址，用于接收支付款项
  • Base Sepolia 测试网 USDC，可在 faucet.circle.com 免费领取

架构概览

x402 三方架构

x402 协议基于三方协作模型：

角色 职责说明
客户端 发起请求的任意 HTTP 客户端——浏览器、curl、AI Agent 等
资源服务器 部署了 x402 中间件的 API 服务（即你的服务）
Facilitator 负责链上支付验证与结算的可信第三方

中间件作为核心组件，承担了协议实现的全部复杂性：构造支付要求、协调 Facilitator 通信、校验支付凭证。

中间件核心机制

x402 中间件实现了三项关键功能：

1. 支付墙响应（Paywall）

当请求未携带有效支付凭证时，中间件根据 Accept 请求头智能判断客户端类型，返回相应格式的响应：

  • 浏览器请求（Accept: text/html）→ 渲染交互式支付页面，引导用户完成钱包连接与授权
  • 程序化请求（curl、fetch、AI Agent）→ 返回结构化的 JSON 支付要求

Paywall 响应机制

2. 支付生命周期管理

这是理解 x402 的核心。当携带支付凭证的请求到达时，处理流程如下：

支付生命周期详解

完整流程：

  1. 客户端发起请求，通过 X-PAYMENT 头部传递签名后的支付授权
  2. 中间件解析头部中的支付载荷
  3. 中间件调用 Facilitator 的 /verify 接口进行多维度校验：
    • 签名是否合法？
    • 付款方账户余额是否充足？
    • 支付金额是否匹配？
  4. Facilitator 返回校验结果 { isValid: true, payer: "0x..." }
  5. 中间件立即响应内容，向客户端返回 200 OK
  6. 中间件异步触发 /settle 调用，在后台完成链上资金划转 
请求 → 解析支付载荷 → 验证 → 响应内容 → 异步结算
Enter fullscreen mode Exit fullscreen mode

设计要点：内容在验证通过后即刻返回，无需等待链上结算完成。这一设计显著优化了用户体验——消除了区块确认带来的延迟。

3. Facilitator 通信

中间件完全封装了与 Facilitator 的交互逻辑，底层调用两个核心接口：

接口 用途 触发时机
POST /verify 校验支付签名与账户余额 响应内容之前
POST /settle 执行链上 USDC 划转 响应内容之后（异步）

风险说明

由于结算在内容响应之后异步执行，存在一个潜在的风险窗口：

风险场景：在验证通过与结算执行之间，付款方可能转移其 USDC 余额，导致结算失败。此时内容已经送达，但款项无法到账。

风险评估：

  • 微额场景（$0.001 - $1）：风险可控，中间件默认行为足以应对
  • 大额场景（$10+）：建议实现自定义逻辑，确保在响应内容之前完成结算

风险缓解策略：

  1. 对微支付场景接受该风险（业界通行做法）
  2. 实现「先结算、后响应」的自定义逻辑（参见「进阶：自主实现验证与结算」）
  3. 对高价值交易采用托管（Escrow）模式

快速上手：Express 实现

以下演示如何构建一个付费 API 端点。

安装依赖 

npm install express x402-express
Enter fullscreen mode Exit fullscreen mode

基础服务器 

import express from "express";
import { paymentMiddleware } from "x402-express";

const app = express();

// 配置收款钱包地址
const WALLET_ADDRESS = "0xYourWalletAddress";

// 定义付费路由规则
app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/premium": {
        price: "$0.001",           // 定价（美元）
        network: "base-sepolia",   // 目标区块链网络
        config: {
          description: "访问高级数据接口",
        },
      },
    }
  )
);

// 受保护的业务端点
app.get("/api/premium", (req, res) => {
  res.json({
    message: "欢迎访问付费内容",
    data: { secret: "此数据价值 $0.001" },
  });
});

app.listen(4021, () => {
  console.log("服务器已启动：http://localhost:4021");
});
Enter fullscreen mode Exit fullscreen mode

仅需以上代码，中间件即可自动完成：

  • 对未付款请求返回 402 状态码及支付要求
  • 为浏览器用户渲染支付界面
  • 校验并结算支付凭证
  • 支付成功后放行请求

其他框架支持

各框架的接入方式大同小异，具体请参阅对应的 npm 文档：

框架 包名 文档链接
Express x402-express npm
Hono x402-hono npm
Fastify x402-fastify npm
Next.js x402-next npm

支持的区块链网络

x402 协议当前支持以下网络：

EVM 兼容网络

网络名称 网络标识 环境类型 备注
Base base 主网 推荐选择，Gas 费用低廉
Base Sepolia base-sepolia 测试网 开发调试首选
Polygon polygon 主网
Avalanche avalanche 主网
Avalanche Fuji avalanche-fuji 测试网
IoTeX iotex 主网

Solana 网络

网络名称 网络标识 环境类型
Solana solana 主网
Solana Devnet solana-devnet 测试网

Facilitator 配置

测试环境

开发阶段可直接使用 x402.org 提供的公共 Facilitator 服务。该地址已在中间件中预置为默认值，无需额外配置。

// 测试环境开箱即用，无需指定 Facilitator
app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/test": {
        price: "$0.001",
        network: "base-sepolia",  // 自动对接 x402.org Facilitator
      },
    }
  )
);
Enter fullscreen mode Exit fullscreen mode

x402.org Facilitator 支持的网络：

  • base-sepolia
  • solana-devnet

生产环境

部署至主网时，需接入 Coinbase 官方 Facilitator，前置条件：

  1. 注册 Coinbase Developer Platform (CDP) 账号
  2. 获取 CDP API 凭证（Key ID 与 Secret） 
import { paymentMiddleware } from "x402-express";
import { facilitator } from "@coinbase/x402";// 环境变量配置：
// CDP_API_KEY_ID=your-key-id
// CDP_API_KEY_SECRET=your-key-secret

app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/premium": {
        price: "$0.10",
        network: "base",  // 主网环境
      },
    },
    facilitator  // 指定 Coinbase 生产 Facilitator
  )
);
Enter fullscreen mode Exit fullscreen mode

安装 Coinbase Facilitator 依赖：

npm install @coinbase/x402```
{% endraw %}
## 测试验证

### 使用 x402-fetch 进行程序化测试

{% raw %}`x402-fetch`{% endraw %} 封装了原生 fetch API，能够自动处理 402 响应并完成支付流程。
{% raw %}


```bash
npm install x402-fetch viem
Enter fullscreen mode Exit fullscreen mode

编写测试脚本：

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-fetch";
import { baseSepolia } from "viem/chains";

// 测试钱包私钥（切勿在生产代码中硬编码主网私钥）
const TEST_PRIVATE_KEY = "0xYourTestPrivateKey";

const account = privateKeyToAccount(TEST_PRIVATE_KEY);
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

// 为 fetch 注入支付能力
const fetchWithPay = wrapFetchWithPayment(fetch, client);

// 调用付费接口
async function test() {
  const response = await fetchWithPay("http://localhost:4021/api/premium");
  const data = await response.json();
  console.log("响应数据:", data);
}

test();
Enter fullscreen mode Exit fullscreen mode

执行流程：

  1. 首次请求收到 402 响应及支付要求
  2. x402-fetch 自动完成支付签名
  3. 携带 X-PAYMENT 头部发起重试请求
  4. 成功获取受保护资源

浏览器端测试

直接在浏览器中访问端点：

http://localhost:4021/api/premium
Enter fullscreen mode Exit fullscreen mode

页面将展示支付界面，引导完成钱包连接与支付授权。

进阶：支付凭证结构

X-PAYMENT 载荷格式

客户端支付时，通过 X-PAYMENT 头部传递签名后的授权信息：

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xPayerAddress",
      "to": "0xYourAddress",
      "value": "1000",
      "validAfter": 0,
      "validBefore": 1234567890,
      "nonce": "0x..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Facilitator 验证响应 

{
  "isValid": true,
  "invalidReason": null,
  "payer": "0xPayerAddress"
}
Enter fullscreen mode Exit fullscreen mode

Facilitator 结算响应 

{
  "success": true,
  "error": null,
  "transaction": "0xTransactionHash",
  "networkId": "84532"
}
Enter fullscreen mode Exit fullscreen mode

进阶：自主实现验证与结算

若需完全掌控验证与结算逻辑（例如实现「先结算、后响应」），可绕过 Facilitator 自行实现。

适用场景

  • 消除风险窗口，确保结算先于内容响应
  • 实现定制化的验证规则
  • 满足自托管基础设施的合规要求
  • 数据隐私保护需求

实现路径

自主验证：

  1. 解析 X-PAYMENT 头部载荷
  2. 校验 EIP-712 签名有效性
  3. 链上查询付款方 USDC 余额
  4. 验证 nonce 的唯一性

自主结算：

  1. 构造 USDC transferWithAuthorization 交易
  2. 提交至区块链网络
  3. 等待交易确认
  4. 确认后再响应内容

此方案实现复杂度较高，需具备扎实的区块链开发基础。多数场景下，建议优先采用 Facilitator 模式。

配置参考

价格定义格式 

// 简洁的美元标记
price: "$0.10"

// 自定义代币配置（进阶）
price: {
  amount: "100000",  // 最小单位数量（USDC 为 6 位小数精度）
  asset: {
    address: "0xTokenContractAddress",
    decimals: 6,
    eip712: { name: "USDC", version: "2" }
  }
}
Enter fullscreen mode Exit fullscreen mode

多路由定价 

app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    {
      "GET /api/basic": {
        price: "$0.001",
        network: "base-sepolia",
      },
      "GET /api/premium": {
        price: "$0.10",
        network: "base-sepolia",
      },
      "/api/enterprise/*": {  // 通配符路由匹配
        price: "$1.00",
        network: "base-sepolia",
      },
    }
  )
);
Enter fullscreen mode Exit fullscreen mode

支付页面定制 

app.use(
  paymentMiddleware(
    WALLET_ADDRESS,
    routes,
    facilitator,
    {
      app: "我的 API 服务",
      appLogo: "/logo.png",
    }
  )
);
Enter fullscreen mode Exit fullscreen mode

常见问题排查

测试钱包无 USDC 余额

访问 faucet.circle.com，领取 Base Sepolia 测试代币。

收到 402 响应但支付失败

  • 确认钱包 USDC 余额充足
  • 检查当前连接的网络是否正确（测试环境应为 Base Sepolia）
  • 核实私钥对应的账户确有可用资金

结算执行失败

可能原因：

  • 付款方在验证与结算间隙转移了资金
  • 网络拥堵导致交易超时
  • Facilitator 服务临时不可用

生产环境建议实现完善的日志记录与失败重试机制。

浏览器 CORS 报错

为 Express 服务器启用 CORS 支持：

import cors from "cors";
app.use(cors());
Enter fullscreen mode Exit fullscreen mode

延伸阅读

x402 将 API 变现的门槛降至一行中间件配置。从测试网起步，验证商业模式，随后平滑过渡至生产环境。

Top comments (0)