agent-payment-x402

Name: agent-payment-x402
Author: affaan-m

Agent 支付执行机制 (x402)

为 AI Agent 提供基于策略把控的支付能力，内置风控与支出限制。依托 x402 HTTP 支付协议与 MCP 工具，让 Agent 能够安全划扣付费 API、外部服务或与其他 Agent 进行结算，且无需承担托管风险。

使用场景

适用场景：当你的 Agent 需要请求付费 API、购买服务、与其他 Agent 结算费用、限制单任务支出上限或管理非托管钱包时。建议与 cost-aware-llm-pipeline 和 security-review 技能配套使用。

决策树

请根据 Agent 是要“付费调用 API”还是要“向他人收费”来选择合适的集成路径：

需求	推荐路径
Agent 在 Base 或其它 agentwallet 支持的链上调用 402 拦截的 API	将 `agentwallet-sdk` 作为 MCP 支付服务端，并配置严格的支出策略
Agent 在 X Layer 上调用 402 拦截的 API	使用来自 `okx/onchainos-skills` 的 OKX Agent Payments Protocol；`okx-x402-payment` 为已废弃的旧版别名
TypeScript API 向 Agent 收费	参阅适用于 Express、Hono、Fastify 或 Next.js 的 OKX Payments TypeScript 卖家端 SDK 文档
Go API 向 Agent 收费	参阅适用于 Gin、Echo 或 `net/http` 的 OKX Payments Go 卖家端 SDK 文档
Rust API 向 Agent 收费	参阅适用于 Axum 的 OKX Payments Rust 卖家端 SDK 文档
Java API 向 Agent 收费	参阅适用于 Spring Boot 2/3、Java EE 或 Jakarta 的 OKX Payments Java 卖家端 SDK 文档
Python API 向 Agent 收费	开发前请先检查最新的 OKX Payments 仓库；目前可能暂未提供 Python 卖家端指南

支持的网络

agentwallet-sdk：在生产上线前，请先查阅官方 Package 文档确认当前网络覆盖范围。开发测试首选 Base Sepolia；生产环境则推荐官方原始 Skill 指定的 Base 主网。
OKX Payments / X Layer：当前卖家端文档主要针对 X Layer (eip155:196) 及 USDT0 结算。因支付包与中介协议迭代较快，生成生产代码前请务必获取最新的 SDK 文档。

工作原理

x402 协议

x402 将 HTTP 402 (Payment Required) 扩展为机器间可自动协商的支付流程。当服务端返回 402 状态码时，Agent 的支付工具会自动协商价格、校验预算、签名交易，并仅在编排器（Orchestrator）设定的策略与确认边界内重试请求。

支出风控 (Spending Controls)

每次调用支付工具都会强制执行 SpendingPolicy 策略：

单任务预算 (Per-task budget) — 单次 Agent 动作的最大支出限额
单会话预算 (Per-session budget) — 整个会话过程中的累计支出上限
收款白名单 (Allowlisted recipients) — 严格限制 Agent 可支付的目标地址或服务
频控速率限制 (Rate limits) — 限制每分钟/每小时的最大交易次数

非托管钱包 (Non-Custodial Wallets)

Agent 通过 ERC-4337 智能账户自行掌控私钥。编排器在任务下发前配置好风控策略，Agent 只能在授权范围内进行消费。资金零集中托管，从根源规避资金被盗或挪用的风险。

MCP 集成

支付层对外暴露标准 MCP 工具，可无缝接入任何 Claude Code 或 Agent 运行框架。

安全提示：请始终锁定依赖包版本（Pin package version）。该工具涉及私钥管理，未锁定版本的 npx 安装可能会带来供应链安全风险。

方案 A：agentwallet-sdk（Base / 多链）

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

可用工具列表（Agent 可直接调用）

工具名称	功能说明
`get_balance`	查询 Agent 钱包余额
`send_payment`	向指定地址或 ENS 发起支付
`check_spending`	查询当前剩余预算
`list_transactions`	获取所有支付记录的审计日志

注意：支出策略（Spending policy）必须由编排器在向 Agent 派发任务前设置，不能由 Agent 自行设定。这样可以防止 Agent 擅自提升自己的支出额度。请在编排层或任务前置 Hook 中通过 set_policy 配置策略，切勿将其作为 Agent 可调用的工具暴露。

方案 B：OKX Agent Payments Protocol（X Layer）

若要在 X Layer 上处理 x402、多方支付 (MPP)、会话支付、扣费以及 A2A 扣费流程，请采用此路径。

买家端（Buyer-side）Agent 流程：

安装或参考最新的 okx/onchainos-skills 仓库。
将 skills/okx-agent-payments-protocol/SKILL.md 用作分发器（Dispatcher）。
务必将 skills/okx-x402-payment/SKILL.md 视为已废弃的兼容别名，不要当作规范 Skill 使用。
在查询钱包状态或执行支付操作前，必须取得用户的明确确认，切勿将支付执行隐匿在通用工具调用背后。

卖家端（Seller-side）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

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

async function main() {
  // 1. 在构建 transport 前校验凭证。
  //    若私钥缺失必须立即报错中断 —— 绝不允许在没有身份认证的情况下启动子进程。
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("未设置 WALLET_PRIVATE_KEY — 拒绝启动支付服务端");
  }

  // 通过 stdio transport 连接到 agentpay MCP 服务端。
  // 务必仅对服务端所需的环境变量设立白名单 —— 切勿将 process.env 中的所有变量暴露给管理私钥的第三方子进程。
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["agentwallet-sdk@6.0.0"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. 在向 Agent 派发任务前设置支出策略。
  //    务必校验执行结果 — 静默失败意味着风控措施未生效。
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `设置支出策略失败 — 拒绝派发任务: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. 在任何付费动作执行前，先进行 preToolCheck 检查
  await preToolCheck(agentpay, 0.01);
}

// 前置 Hook：遵循“失败即闭锁 (fail-closed)”原则的预算强校验，包含 4 种明确的错误分支。
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // 分支 1：拒绝无效输入（NaN / Infinity 会绕过 < 比较运算符逻辑）
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`无效的 apiCost: ${apiCost} — 动作已拦截`);
  }

  // 分支 2：传输层/网络连接失败
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`支付服务无法连接 — 动作已拦截: ${err}`);
  }

  // 分支 3：工具返回错误（如未授权、钱包未初始化等）
  if (result.isError) {
    throw new Error(
      `check_spending 执行失败 — 动作已拦截: ${JSON.stringify(result.content)}`
    );
  }

  // 分支 4：解析并校验响应结构
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("缺少或存在无效的 'remaining' 字段");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending 返回了意外的数据格式 — 动作已拦截: ${err}`
    );
  }

  // 分支 5：超出预算限额
  if (remaining < apiCost) {
    throw new Error(
      `预算已超限：本次需要 $${apiCost}，但剩余额度仅有 $${remaining}`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

最佳实践

任务派发前配置预算：在生成子 Agent (Sub-agent) 时，务必通过编排层挂载 SpendingPolicy，绝不能给 Agent 无上限的消费权限。
锁死依赖版本：在 MCP 配置中务必指定确切的版本号（如 agentwallet-sdk@6.0.0）。在部署到生产环境之前，先核验 npm 包的完整性。
建立审计追踪机制：在任务结束后的 Hook 中使用 list_transactions，如实记录消费金额与具体原因。
遵循失败即闭锁 (Fail closed)：如果支付工具无法连接，必须直接拦截付费动作，切勿回退到无计费限制模式。
与 security-review 技能配合使用：支付工具属于高风险高权限工具，需像对待 Shell 执行权限一样予以严格审查。
先在测试网测试：开发阶段首选 Base Sepolia；上线生产环境再切换至 Base 主网。

生产参考资料

npm 路径: agentwallet-sdk
已合并至 NVIDIA NeMo Agent Toolkit: PR #17 — 适用于 NVIDIA Agent 示例的 x402 支付工具
协议规范: x402.org
OKX Payments SDK: okx/payments — 适用于 X Layer x402 的 TypeScript、Go、Rust 和 Java 卖家端集成组件
OKX Agent Payments Protocol Skill: okx/onchainos-skills
OKX Payments 概述文档: web3.okx.com/onchainos/dev-docs/payments/overview

你可能还喜欢

homelab-network-readiness

240Kmcp-integrations

Readiness checklist for homelab VLAN segmentation, local DNS filtering, and WireGuard-style remote access before changing router, firewall, DHCP, or VPN configuration.

affaan-m

获取

agent-tool-builder

47Kmcp-integrations

Tools are how AI agents interact with the world. A well-designed

sickn33

获取

mcp-developer

11Kmcp-integrations

在构建、调试或扩展将AI系统与外部工具和数据源连接的MCP服务器或客户端时使用。调用以实现工具处理器、配置资源提供程序、设置stdio/HTTP/SSE传输层、使用Zod或Pydantic验证模式、调试协议合规性问题，或使用TypeScript或Python SDK搭建完整的MCP服务器/客户端项目。

jeffallan

获取

继续探索

浏览 mcp-integrations 热门 Skills 最近更新