Source: Dev.to

使用 x402 与 AgentWallet SDK 构建付费 API 端点 – 开发者指南

在当今的 AI 代理经济中，能够对 API 调用进行计费是实现可持续收入模型的关键。本文将向你展示如何使用 x402（一个基于 Stripe 的计费层）以及 AgentWallet SDK 来快速创建受保护的付费 API 端点。我们会一步步完成以下内容：

1. 配置 x402 项目
2. 在后端项目中安装并初始化 AgentWallet SDK
3. 使用 SDK 验证请求并收取费用
4. 部署并测试端点

---

前置条件

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

---

第一步：在 Stripe 上创建 x402 项目

1. 登录你的 Stripe 仪表盘。
2. 前往 Products → Add product，创建一个名为 “API Access” 的产品。
3. 为该产品添加一个 price（例如每 1,000 次调用 $0.10）。记下生成的 price_id。
4. 在 Developers → API keys 页面获取 Secret Key，稍后会在 .env 文件中使用。

提示：如果你想使用 试用期 或 订阅，可以在 Stripe 中创建相应的计划并记录对应的 price_id。

---

第二步：搭建后端项目

下面我们使用 Express 来快速搭建一个示例服务。

# 克隆示例仓库（可选）
git clone https://github.com/agentwallet/example-paid-endpoint.git
cd example-paid-endpoint

# 安装依赖
npm install

添加环境变量

在项目根目录创建 .env 文件，并填入以下内容（请使用你自己的 Stripe 密钥和 price_id）：

STRIPE_SECRET_KEY=sk_test_*********************
X402_PRICE_ID=price_1Hh***************
AGENTWALLET_API_KEY=your_agentwallet_api_key

注意：.env 文件不应提交到代码仓库，确保在 .gitignore 中已包含该文件。

---

第三步：安装并初始化 AgentWallet SDK

npm install @agentwallet/sdk

在 src/index.js（或你的入口文件）中引入并初始化 SDK：

const { AgentWallet } = require('@agentwallet/sdk');

const agentWallet = new AgentWallet({
  apiKey: process.env.AGENTWALLET_API_KEY,
  // 可选：自定义 API 基础路径
  // baseUrl: 'https://api.agentwallet.io/v1'
});

---

第四步：实现付费 API 端点

下面的示例展示了一个 GET /weather 端点，调用前会：

1. 使用 AgentWallet SDK 验证请求的 access token。
2. 通过 x402 为该请求计费（如果用户余额不足则返回错误）。

app.get('/weather', async (req, res) => {
  try {
    // 1️⃣ 从请求头中获取 AgentWallet access token
    const token = req.headers['authorization']?.split(' ')[1];
    if (!token) {
      return res.status(401).json({ error: 'Missing access token' });
    }

    // 2️⃣ 验证 token 并获取用户信息
    const user = await agentWallet.verifyToken(token);
    // user 对象示例: { id: 'usr_123', email: 'user@example.com', walletId: 'wal_456' }

    // 3️⃣ 使用 x402 为本次调用计费
    const charge = await agentWallet.charge({
      walletId: user.walletId,
      priceId: process.env.X402_PRICE_ID,
      description: 'Weather API call',
      metadata: {
        endpoint: '/weather',
        method: 'GET'
      }
    });

    // 如果计费失败（例如余额不足），charge 将抛出异常
    // 4️⃣ 调用实际业务逻辑（这里用伪代码返回天气信息）
    const weatherData = {
      location: 'San Francisco',
      temperature: '18°C',
      condition: 'Partly Cloudy'
    };

    // 5️⃣ 返回成功响应
    res.json({
      success: true,
      data: weatherData,
      chargeId: charge.id,
      remainingBalance: charge.walletBalance
    });
  } catch (err) {
    console.error(err);
    // 统一错误处理
    if (err.code === 'INSUFFICIENT_FUNDS') {
      return res.status(402).json({ error: 'Insufficient funds' });
    }
    res.status(500).json({ error: err.message });
  }
});

关键点说明

---

第五步：本地运行并测试

npm start

服务器默认监听 http://localhost:3000。使用 cURL 或 Postman 发送请求：

curl -X GET http://localhost:3000/weather \
  -H "Authorization: Bearer <YOUR_AGENTWALLET_ACCESS_TOKEN>"

• 成功：返回天气数据以及 chargeId、remainingBalance。
• 余额不足：返回 402 Payment Required 并提示 “Insufficient funds”。
• 缺少 token：返回 401 Unauthorized。

---

第六步：部署到生产环境

1. 选择托管平台（如 Vercel、Render、Railway 或自托管的 EC2）。
2. 配置环境变量：在平台的设置页面填入 .env 中的所有键值。
3. 启用 HTTPS：确保所有请求通过 TLS 加密，以防止 token 被窃取。
4. 监控与日志：使用 Datadog、Sentry 或 Logtail 记录计费失败和异常。

---

常见问题 (FAQ)

---

结语

通过结合 x402 的强大计费能力和 AgentWallet SDK 的简洁身份验证，你可以在几分钟内为任何 Node.js/Express API 添加可靠的付费层。这样既能保护你的模型资源，又能为开发者社区提供可持续的商业模型。

如果你在实现过程中遇到任何问题，欢迎在 GitHub Issues 或 AgentWallet Discord 中提问。祝你玩得开心，构建出更多有价值的付费 AI 服务！

x402 实际是什么

x402 是一种原生于 HTTP 的支付协议。当客户端请求一个付费端点但未附带资金时，服务器会返回 402 响应，并附带机器可读的支付负载。客户端完成支付后，重新发送带有支付凭证的请求，即可获取资源——无需重定向、无需 OAuth 流程、也不需要单独的计费 API。

Coinbase 已在生产环境中运行 x402 数月，处理了超过 115 百万 笔微支付。Stripe 最近宣布支持集成，使 x402 从实验性的 Web3 概念转向主流基础设施。

由于该协议运行在 HTTP 层，它与语言无关，能够与任何现有的 HTTP 客户端配合使用。如果你的代理能够发起 fetch() 调用，它就能为 API 访问付费。

为什么非托管是正确的架构

大多数支付集成会为你存放资金。托管钱包意味着第三方持有你的密钥。对普通用户来说这只是个小不便；但对全天候运行的自主代理而言，它会成为单点故障和信任瓶颈。

agentwallet‑sdk 采用了不同的方式：代理自行持有私钥并在本地签署支付。除加密证明外，任何东西都不会离开代理。这意味着：

• 无需调用钱包服务的 API 来授权支出
• 没有托管提供商的速率限制或宕机风险
• 代理可以完全自主运行，无需“回家报信”
• 每笔支付都可以在链上审计

这种架构对代理工作流至关重要——在这些工作流中，代理会雇佣其他代理、为数据付费，或每隔几秒就结算一次微交易。托管方案根本无法满足这种模式的扩展需求。

Source:

代码演练

安装

npm install agentwallet-sdk

初始化 Agent 钱包

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({
  // Agent 会生成并持有自己的密钥
  privateKey: process.env.AGENT_PRIVATE_KEY,
  // 推荐使用 Base 链以获得低费用
  defaultChain: "base",
});

console.log("Agent address:", wallet.address);

创建付费 API 接口（服务器端）

import express from "express";
import { x402Middleware } from "agentwallet-sdk/middleware";

const app = express();

// 使用 $0.001 的支付要求来保护此接口
app.use(
  "/api/premium-data",
  x402Middleware({
    price: "0.001",
    currency: "USDC",
    chain: "base",
    receiverAddress: process.env.MY_WALLET_ADDRESS,
  })
);

app.get("/api/premium-data", (req, res) => {
  res.json({ data: "This is paid content", timestamp: Date.now() });
});

调用付费接口（Agent 端）

import { AgentWallet } from "agentwallet-sdk";

const wallet = new AgentWallet({ privateKey: process.env.AGENT_PRIVATE_KEY });

// SDK 会自动处理 402 → 支付 → 重试 的循环
const response = await wallet.fetch("https://api.example.com/api/premium-data");
const data = await response.json();

使用 curl 测试

首次请求会返回 402：

curl -i https://api.example.com/api/premium-data
# HTTP/1.1 402 Payment Required
# x402-payment-payload: {...}

当 SDK 自动完成支付后，代理程序将看不到 402——重试过程对它们是透明的。

支持的链

SDK 当前支持 17 条网络。主要的有：

完整的支持链列表可在SDK 文档中查看。

更大的图景

x402 与非托管钱包相结合，为代理经济提供了合适的原语。代理可以发现付费 API，精确支付其消费的内容，并且整个过程无需任何人工介入。

您无需计费部门或订阅系统。API 按调用计费，代理按调用付费，整个过程在链上运行，无需中介。

入门

npm install agentwallet-sdk

SDK 使用 MIT 许可证。源代码、示例和链文档托管在 npm 上。欢迎提出问题和拉取请求。