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

Source: Dev.to

概述

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

前置条件

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

协议模型

x402 基于 三方协作模型：

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

中间件关键功能

1. 未付款请求

   • 根据 Accept 请求头判断客户端类型并返回对应格式的支付要求
     • 浏览器 (Accept: text/html) → 渲染交互式支付页面，引导钱包连接与授权
     • 程序化请求（curl、fetch、AI Agent） → 返回结构化的 JSON 支付要求

2. 已付款请求

   • 解析 X-PAYMENT 头部中的支付载荷
   • 调用 Facilitator 的 /verify 接口进行多维度校验：签名合法性、付款方余额、支付金额是否匹配等
   • 验证通过后立即返回内容（200 OK），随后异步触发 /settle 完成链上资金划转

设计要点：内容在验证通过后即刻返回，无需等待链上结算完成，显著提升用户体验。

中间件与 Facilitator 接口

风险与缓解

• 风险窗口：在验证通过与结算执行之间，付款方可能转移 USDC，导致结算失败。
• 风险评估
  • 微额场景（$0.001‑$1）：风险可控，默认行为足以应对。
  • 大额场景（$10+）：建议实现自定义逻辑，确保在响应内容之前完成结算，或采用托管（Escrow）模式。

快速上手：Express 示例

npm install express x402-express

// app.js
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");
});

中间件自动完成：

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

框架适配

支持网络

公共 Facilitator（测试环境）

开发阶段可直接使用 x402.org 提供的公共 Facilitator，无需额外配置：

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

支持的网络包括 base-sepolia 与 solana-devnet。

生产环境：Coinbase Facilitator

部署至主网时，需要接入 Coinbase 官方 Facilitator：

1. 注册 Coinbase Developer Platform (CDP) 账号
2. 获取 CDP API 凭证（Key ID 与 Secret）

npm install @coinbase/x402

import { paymentMiddleware } from "x402-express";
import { facilitator } from "@coinbase/x402";

const WALLET_ADDRESS = "0xYourWalletAddress";

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

环境变量示例：

CDP_API_KEY_ID=your-key-id
CDP_API_KEY_SECRET=your-key-secret

程序化测试：x402-fetch

npm install x402-fetch viem

// test.js
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,
});

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();

执行流程

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

在浏览器直接访问 http://localhost:4021/api/premium 时，会展示支付页面，引导完成钱包连接与授权。

高级自定义：自行实现验证与结算

若需消除风险窗口（先结算后响应），可绕过 Facilitator，自己实现以下步骤：

1. 解析 X-PAYMENT 头部
2. 验证 EIP‑712 签名
3. 链上查询付款方 USDC 余额
4. 检查 nonce 唯一性
5. 构造 USDC transferWithAuthorization 交易并提交
6. 等待交易确认后再返回业务内容

此方案复杂度较高，适用于高价值交易、托管需求或自托管合规环境。

常见问题排查

• 付款方在验证与结算间隙转移资金

  • 适用于微支付场景的默认行为；大额交易请实现先结算逻辑或使用 Escrow。

• 网络拥堵导致交易超时

  • 增加重试次数或使用更高的 gas 费用。

• Facilitator 服务不可用

  • 监控健康状态，必要时切换至备用 Facilitator（如 Coinbase）。

• 生产环境日志与重试

  • 建议记录支付验证、结算请求、响应状态以及错误信息，配合指数退避重试机制。

其他资源

• 官方技术文档：
• 开源代码仓库：
• 协议白皮书：
• 生态全景解读：

通过上述步骤，你可以在几行中间件配置内实现付费 API，快速在测试网验证商业模型，并平滑迁移至生产环境。祝开发顺利！