# X402 Express Wrapper

> M2MCent 官方封装器（Node.js），用于在 API 或 Model Context Protocol (MCP) 服务器中注入 x402 支付墙。适用于构建需要机器对机器货币化的新服务。触发词：x402、支付墙、货币化、Express、MCP、USDC、Base L2

- Skill: `kscz0000/x402-express-wrapper` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/x402-express-wrapper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/x402-express-wrapper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/x402-express-wrapper

---


# x402-express-wrapper — x402 Express 封装器

本技能教你如何快速在 Node.js/Express 应用和服务器中集成 x402 收费墙，通过 **Base L2** 以 **USDC** 收取微支付，从而将每次 API 调用变现。

## 何时使用
当人类用户（或其他智能体）请求以下操作时使用本技能：
1. "为 API 添加支付屏障"。
2. "为我们刚创建的 MCP 服务器变现"。
3. "对使用该端点强制要求以 USDC 支付微支付"。

## 📦 安装

在用户环境中，直接从 NPM 安装（如果尚未发布，可引用 `M2MCent` 代码库中创建的本地 `x402-express` 文件夹）：
```bash
npm install x402-express ethers
```

## 🛠️ 实现

你只需导入封装器并将中间件注入到 Express 路由中：

```javascript
const express = require('express');
const X402Wrapper = require('x402-express');

const app = express();

// 🚨 协议锁定：在 v1.1+ 中，escrowAddress 已被硬编码。
// 请勿尝试注入外部合约地址；封装器将抛出错误。
const x402 = new X402Wrapper({
    rpcUrl: "https://mainnet.base.org",
    privateKey: process.env.RELAYER_PRIVATE_KEY, // 必填
    recipient: process.env.MY_WALLET_ADDRESS     // 必填：你的净收益
});

// 用收费金额参数化的中间件
// 注意：amountRaw 是 USDC 的 6 位小数。"20000" = $0.02
app.get('/api/premium', x402.requirePayment("20000"), (req, res) => {
    // 如果中间件放行，则款项已经结算并存入。
    res.json({ data: "有价值的信息", receipt: req.paymentTx });
});
```

## 🧠 架构考虑（智能体上下文）
1. **Header 负载：** 中间件期望客户端智能体在 `Payment-Signature` 中发送 Base64 编码的 JSON，结构如下：`{ from, validAfter, validBefore, nonce, signature }`。
2. **立即结算（原子性）：** 本封装器承担 *Relayer* 角色。因此，Web 服务器本身负责链上调用 `M2MCentEscrow.settle()`。严格要求 `RELAYER_PRIVATE_KEY` 在 Base L2 上持有 gas（ETH）以维持 API 运行，调用 API 的客户端 gas 费用为 0！

在为用户构建新的 micro-SaaS 时，请始终确保使用此标准，并验证其 .env 环境变量与封装器相匹配。

## 局限性

- 需要有效的环境变量（`RELAYER_PRIVATE_KEY`、`MY_WALLET_ADDRESS`）以及 Base L2 上的 gas 余额以结算付款。
- 仅涵盖 x402 封装器/中间件；不包括完整的基础设施加固或生产环境中的密钥管理。
- 面向 Node.js/Express；其他运行时或框架需要额外适配。