构建一个x402支付服务器

创建一个使用x402支付协议对USDC API访问进行收费的Express服务器。调用者在Base网络上按请求支付USDC——无需账户、API密钥或订阅。

工作原理

x402是一种基于HTTP的支付协议。当客户端在未支付的情况下访问受保护端点时，服务器返回带有支付要求的HTTP 402状态码。客户端签署一笔USDC支付，并携带支付头信息重试请求。协调者验证并结算支付，服务器返回响应。

确认钱包已初始化并认证

bash
npx awal@latest status

如果钱包未认证，请参考authenticate-wallet技能。

步骤1：获取支付地址

运行以下命令获取接收支付的钱包地址：

bash
npx awal@latest address

将此地址用作payTo值。

步骤2：设置项目

bash
mkdir x402-server && cd x402-server
npm init -y
npm install express x402-express

创建index.js：

js
const express = require(express);
const { paymentMiddleware } = require(x402-express);

const app = express();
app.use(express.json());

const PAY_TO = <步骤1中的地址>;

// x402支付中间件 — 保护以下路由
const payment = paymentMiddleware(PAY_TO, {
GET /api/example: {
price: $0.01,
network: base,
config: {
description: 该端点返回内容的描述,
},
},
});

// 受保护的端点
app.get(/api/example, payment, (req, res) => {
res.json({ data: 每次请求花费$0.01 });
});

app.listen(3000, () => console.log(服务器运行在端口3000));

步骤3：运行服务器

bash
node index.js

使用curl测试——应收到带有支付要求的402响应：

bash
curl -i http://localhost:3000/api/example

API参考

paymentMiddleware(payTo, routes, facilitator?)

创建强制执行x402支付的Express中间件。

参数	类型	描述
payTo	string	接收USDC支付的以太坊地址(0x...)
routes

object | 路由配置，将路由模式映射到支付配置 |
| facilitator | object? | 可选的自定义协调者（默认为x402.org） |

路由配置

routes对象中的每个键都是METHOD /path格式。值可以是价格字符串或配置对象：

js
// 简单配置 — 仅价格
{ GET /api/data: $0.05 }

// 完整配置
{
POST /api/query: {
price: $0.25,
network: base,
config: {
description: 端点的人类可读描述,
inputSchema: {
bodyType: json,
bodyFields: {
query: { type: string, description: 要执行的查询 },
},
},
outputSchema: {
type: object,
properties: {
result: { type: string },
},
},
},
},
}

路由配置字段

字段	类型	描述
price	string	USDC价格（例如$0.01, $1.00）
network

string | 区块链网络：base或base-sepolia | | config.description | string? | 该端点的功能说明（向客户端展示） | | config.inputSchema | object? | 预期的请求体/查询参数模式 | | config.outputSchema | object? | 响应体模式 | | config.maxTimeoutSeconds | number? | 支付结算的最大超时时间 |

支持的网络

网络	描述
base	Base主网（真实USDC）
base-sepolia

Base Sepolia测试网（测试USDC） |

模式

不同价格的多个端点

js
const payment = paymentMiddleware(PAY_TO, {
GET /api/cheap: { price: $0.001, network: base },
GET /api/expensive: { price: $1.00, network: base },
POST /api/query: { price: $0.25, network: base },
});

app.get(/api/cheap, payment, (req, res) => { / ... / });
app.get(/api/expensive, payment, (req, res) => { / ... / });
app.post(/api/query, payment, (req, res) => { / ... / });

通配符路由

js
const payment = paymentMiddleware(PAY_TO, {
GET /api/*: { price: $0.05, network: base },
});

app.use(payment);
app.get(/api/users, (req, res) => { / ... / });
app.get(/api/posts, (req, res) => { / ... / });

健康检查（无需支付）

在支付中间件之前注册免费端点：

js
app.get(/health, (req, res) => res.json({ status: ok }));

// 支付中间件仅适用于在其之后注册的路由
app.get(/api/data, payment, (req, res) => { / ... / });

带请求体模式的POST请求

js
const payment = paymentMiddleware(PAY_TO, {
POST /api/analyze: {
price: $0.10,
network: base,
config: {
description: 分析文本情感,
inputSchema: {
bodyType: json,
bodyFields: {
text: { type: string, description: 要分析的文本 },
},
},
outputSchema: {
type: object,
properties: {
sentiment: { type: string },
score: { type: number },
},
},
},
},
});

app.post(/api/analyze, payment, (req, res) => {
const { text } = req.body;
// ... 你的逻辑
res.json({ sentiment: positive, score: 0.95 });
});

使用CDP协调者（已认证）

用于生产环境，使用Coinbase协调者（支持主网）：

bash
npm install @coinbase/x402

js
const { facilitator } = require(@coinbase/x402);

const payment = paymentMiddleware(PAY_TO, routes, facilitator);

这需要CDPAPIKEYID和CDPAPIKEYSECRET环境变量。从https://portal.cdp.coinbase.com获取这些信息。

使用pay-for-service技能进行测试

服务器运行后，使用pay-for-service技能测试支付：

bash

检查端点的支付要求

npx awal@latest x402 details http://localhost:3000/api/example

发起付费请求

npx awal@latest x402 pay http://localhost:3000/api/example

定价指南

使用场景	建议价格
简单数据查询	$0.001 - $0.01
API代理/数据增强

$0.01 - $0.10 | | 计算密集型查询 | $0.10 - $0.50 | | AI推理 | $0.05 - $1.00 |

检查清单

• - [ ] 使用npx awal@latest address获取钱包地址
• [ ] 安装express和x402-express
• [ ] 定义带有价格和描述的路由
• [ ] 在受保护路由之前注册支付中间件
• [ ] 将健康/状态端点放在支付中间件之前
• [ ] 使用curl测试（应获得402）和npx awal@latest x402 pay测试（应获得200）
• [ ] 发布你的服务，以便其他代理可以找到并使用它