agent-payment-x402

Files (1)

• SKILL.md

SKILL.md (first lines)

# 智能体支付执行 (x402)

使 AI 智能体能够进行策略门控的支付，并内置支出控制。使用 x402 HTTP 支付协议和 MCP 工具，因此智能体可以在没有托管风险的情况下支付外部服务、API 或其他智能体。

## 何时使用

当以下情况使用：您的智能体需要支付 API 调用、购买服务、与另一个智能体结算、强制执行每任务支出限制或管理托管钱包。与 cost-aware-llm-pipeline 和 security-review 技能自然配对。

## 决策树

根据您的智能体是购买付费 API 访问还是向其他人收费来选择集成路径：

| 需求 | 推荐路径 |
|------|------------------|
| 智能体在 Base 或其他 agentwallet-sdk 支持的链上支付 402 限门的 API | 使用 `agentwallet-sdk` 作为 MCP 支付服务器，具有严格的支出策略 |
| 智能体在 X Layer 上支付 402 限门的 API | 使用 `okx/onchainos-skills` 中的 OKX Agent Payments Protocol；`okx-x402-payment` 是已弃用的旧别名 |
| TypeScript API 向智能体收费 | 使用 OKX Payments TypeScript 销售商 SDK 文档，适用于 Express、Hono、Fastify 或 Next.js |
| Go API 向智能体收费 | 使用 OKX Payments Go 销售商 SDK 文档，适用于 Gin、Echo 或 `net/http` |
| Rust API 向智能体收费 | 使用 OKX Payments Rust 销售商 SDK 文档，适用于 Axum |
| Java API 向智能体收费 | 使用 OKX Payments Java 销售商 SDK 文档，适用于 Spring Boot 2/3、Java EE 或 Jakarta |
| Python API 向智能体收费 | 实施前检查当前 OKX Payments 存储库；Python 销售商指南可能不可用 |

## 支持的网络

- `agentwallet-sdk`：在生产前使用包文档确认当前网络覆盖。Base Sepolia 是最安全的开发默认值；Base 主网是原始技能指定的生产路径。
- OKX Payments / X Layer：当前销售商文档针对 X Layer (`eip155:196`) 和 USDT0 结算。在生成生产代码之前获取当前 SDK 文档，因为支付包和促进者行为可能会快速变化。

## 工作原理

### x402 协议
x402 将 HTTP 402（需要支付）扩展为机器可协商流。当服务器返回 `402` 时，智能体的支付工具协商价格、检查预算、签署交易，并且仅在协调器设置的策略和确认边界内重试。

### 支出控制
每次支付工具调用强制执行 `SpendingPolicy`：
- **每任务预算** — 单个智能体操作的最大支出
- **每会话预算** — 整个会话的累计限制
- **允许接收者** — 限制智能体可以支付的地址/服务
- **速率限制** — 每分钟/小时的最大交易数

### 托管钱包
智能体通过 ERC-4337 智能账户持有自己的密钥。协调器在委派之前设置策略；智能体只能在范围内支出。没有 pooled 资金，没有托管风险。

## MCP 集成

支付层暴露标准 MCP 工具，可插入任何 Claude Code 或智能体工具设置。

> **安全提示**：始终固定包版本。此工具管理私钥 — 未固定的 `npx` 安装会引入供应链风险。

### 选项 A：agentwallet-sdk (Base / 多链)

```json
{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["agentwallet-sdk@6.0.0"]
    }
  }
}
```

### 可用工具（智能体可调用）

| 工具 | 目的 |
|------|---------|
| `get_balance` | 检查智能体钱包余额 |
| `send_payment` | 向地址或 ENS 发送支付 |
| `check_spending` | 查询剩余预算 |
| `list_transactions` | 所有支付的审计跟踪 |

> **注意**：支出策略由**协调器**在委派给智能体之前设置 — 而非智能体本身。这防止智能体提升自己的支出限制。通过编排层中的 `set_policy` 或任务前挂钩配置策略，切勿作为智能体可调用工具。

### 选项 B：OKX Agent Payments Protocol (X Layer)

将此路径用于 X Layer x402、多方支付 (MPP)、会话支付、收费和 A2A 收费流。

对于买方智能体流：

1. 安装或引用当前 `okx/onchainos-skills` 存储库。
2. 使用 `skills/okx-agent-payments-protocol/SKILL.md` 作为调度器。
3. 将 `skills/okx-x402-payment/SKILL.md` 视为已弃用的兼容性别名，而非规范技能。
4. 在钱包状态检查或支付操作之前需要明确的用户确认。不要将支付执行隐藏在通用工具调用之后。

对于卖方 API 流，在生成代码之前获取最新的特定语言指南：

| 运行时 | 当前指南 |
|---------|---------------|
| TypeScript | `https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md` |
| Go | `https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md` |
| Rust | `https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md` |
| Java | `https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md` |

不要在不检查当前 OKX 存储库的情况下从旧文档复制示例。当前 OKX 指南使用 `okx-agent-payments-protocol` 作为调度器，Java 销售商文档现已可用。

## 示例

### MCP 客户端中的预算强制执行

构建调用 agentpay MCP 服务器的协调器时，在分派付费工具调用之前强制执行预算。

> **前提条件**：在添加 MCP 配置之前安装包 — 没有 `-y` 的 `npx` 将在非交互环境中提示确认，导致服务器挂起：`npm install -g agentwallet-sdk@6.0.0`

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. 在构建传输之前验证凭据。
  //    缺失密钥必须立即失败 — 永远不要让子进程在没有身份验证的情况下启动。
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY 未设置 — 拒绝启动支付服务器");
  }

  // 通过 stdio 传输连接到 agentpay MCP 服务器。
  // 仅白名单服务器需要的环境变量 — 永远不要将所有 process.env
  // 转发到管理私密的第三方子进程。
  const transport = new StdioClientTransport({
    command: "npx",

From aaione/everything-claude-code-zh, MIT.

More from aaione/everything-claude-code-zh