agent-payment-x402 Skill 为 Claude Code 及其他 AI Agent 带来了基于 x402 协议的自动支付能力，支持每任务/会话预算控制、非托管钱包和支出审计。它让 AI 能够自主为 API、服务或其他 Agent 支付费用，并通过严格的支出策略和安全机制防止越权和滥用。本文将结合实际项目场景，手把手讲解如何配置、使用与最佳实践，并解析与 cost-aware-llm-pipeline、security-review 等 Skill 的协作关系。

Everything Claude Code Agent Payment x402：为 AI Agent 添加 x402 协议每任务预算支付能力

在 AI 编程助手日益参与实际生产和自动化流程的今天，如何让 Agent 能够自主、安全地为外部服务/API/其他 Agent 支付费用，成为高阶自动化与多 Agent 协作场景的关键需求。agent-payment-x402 Skill 正是为此而生，它基于 x402 协议，结合 MCP（Model Context Protocol）工具，将“每任务预算”、“非托管钱包”、“支出审计”与“支付安全”能力无缝集成进 Claude Code 及其插件体系。

1. 解决了什么问题？不用 x402 时的痛点

传统 AI Agent 在调用付费 API、购买服务或与其他 Agent 结算时，常见做法有：

• 由人工审核和下单，流程慢、无法自动化；
• 统一 API Key 或钱包，存在资金池被滥用、越权风险；
• 无法针对单次任务、会话设置预算，难以精细控制成本；
• 支付流程与 Agent 逻辑耦合，难以追踪和审计。

而 agent-payment-x402 Skill 通过 x402 协议和 MCP 工具，提供了：

• 每任务/会话预算：可为每个 Agent 行为或会话设置最大可用额度；
• 非托管钱包：Agent 持有自己的私钥，资金隔离，无需中心化托管；
• 自动支付执行：遇到 HTTP 402 响应时自动协商价格、校验预算、签名支付并重试，无需人工介入；
• 收款方白名单与速率限制：可限制 Agent 只能向指定服务/地址支付，并控制支付频率；
• 全过程可审计：所有支付均可通过 MCP 工具审计和追溯。

2. 典型使用场景与触发条件

你应在以下场景考虑集成 agent-payment-x402 Skill：

• Agent 需要自动调用付费 API（如高阶模型、第三方数据服务）；
• 多 Agent 协作下，需跨 Agent 结算或分账；
• 需要对 Agent 的每次操作/会话总支出设限，防止意外消耗超标；
• 希望最小托管风险，让每个 Agent 独立持有钱包密钥，资金隔离；
• 需要可审计的支付流水，便于合规和安全追踪。

Skill 会在 Agent 触发涉及支付的 Tool（如 send_payment、get_balance 等）时自动激活，尤其是在 HTTP 402（Payment Required）响应出现时，Agent 会自动走 x402 协议流程。

3. Step by Step：如何在实际项目中用好 agent-payment-x402

步骤 1：安装依赖与配置 MCP Server

首先，确保全局安装了指定版本的 agentwallet-sdk，必须锁定版本，防止供应链风险：

npm install -g agentwallet-sdk@6.0.0

在你的 Claude Code 或 Agent Harness 配置中，添加 MCP Server：

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

安全提示：不要用未锁定版本的 npx，并只传递必要的环境变量（如私钥），避免泄漏敏感信息。

步骤 2：在 Orchestrator 层设置支出策略

Agent 的支出策略（SpendingPolicy）只能由 Orchestrator 设定，Agent 本身无权修改。推荐在 spawn 子 Agent 或分配任务前，设置如下策略：

• per_task_budget：单次操作最大支出（如 $0.50）
• per_session_budget：会话累计支出上限（如 $5.00）
• allowlisted_recipients：仅允许支付给指定服务/地址
• rate limits：每分钟/小时最多支付次数

示例代码（TypeScript）：

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

const walletKey = process.env.WALLET_PRIVATE_KEY;
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);

// 设置支出策略
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(`Failed to set spending policy: ${JSON.stringify(policyResult.content)}`);
}

步骤 3：在每次付费操作前进行预算校验

建议在每次有付费操作前，调用 check_spending 工具，确保预算充足，且支付服务可用。推荐将此逻辑封装为 preToolHook：

async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`Invalid apiCost: ${apiCost}`);
  }
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Payment service unreachable: ${err}`);
  }
  if (result.isError) {
    throw new Error(`check_spending failed: ${JSON.stringify(result.content)}`);
  }
  let remaining: number;
  try {
    const parsed = JSON.parse((result.content as Array<{ text: string }>)[0].text);
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("missing or non-finite 'remaining' field");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(`check_spending returned unexpected format: ${err}`);
  }
  if (remaining < apiCost) {
    throw new Error(`Budget exceeded: need $${apiCost} but only $${remaining} remaining`);
  }
}

步骤 4：Agent 调用支付相关工具

Agent 可通过 MCP 工具调用以下能力：

• get_balance：查询钱包余额
• send_payment：向指定地址/ENS 支付
• check_spending：查询剩余预算
• list_transactions：列出所有支付流水

注意：set_policy 只能由 orchestrator 层调用，Agent 不能自提额度。

步骤 5：支付流水审计与安全联动

建议在每次任务后，通过 list_transactions 工具记录和审计支付行为，并结合 security-review Skill 做高权限操作的安全检查。

输出示例

• Agent 调用付费 API，遇到 HTTP 402 响应，自动协商价格、校验预算、签名支付并重试，最终拿到 API 响应。
• check_spending 返回：{"remaining": 2.35}，Agent 判断预算充足后继续执行。
• list_transactions 返回所有支付明细，便于审计。

4. 常见配套 Agent 与 Skill 协作关系

• 与 cost-aware-llm-pipeline Skill 配合：可根据任务复杂度动态路由模型和预算，自动决定是否走付费路径。
• 与 security-review Skill 配合：对高权限支付操作进行安全审查，防止私钥泄漏和越权支出。
• 与多 Agent Harness/Team Builder 配合：每个子 Agent 独立钱包、独立预算，支持复杂协作与分账。
• 结合 verification-loop Skill：确保付费操作前后均有端到端校验。

5. 最佳实践与注意事项

• 始终在 Orchestrator 层设定预算策略，绝不让 Agent 自提额度。
• 锁定依赖版本，并在生产前校验包完整性。
• 只传递必要环境变量给 MCP Server，防止密钥泄漏。
• 开发阶段优先用测试网（如 Base Sepolia），生产再切主网。
• 支付服务不可用时，务必 fail closed，阻断付费操作，防止无预算兜底。
• 所有支付操作都应有完整审计链路，便于合规与溯源。

---

FAQ

Q: agent-payment-x402 Skill 支持哪些支付场景？ A: 支持 AI Agent 自动为 API、第三方服务、其他 Agent 支付费用，适用于 API 计费、服务购买、Agent 间结算等多种场景。

Q: 如何防止 Agent 滥用支付权限？ A: 通过 orchestrator 预设每任务/会话预算、收款方白名单和速率限制，且 Agent 不能自提额度，所有支付均有审计。

Q: 生产环境如何保障安全？ A: 必须锁定 agentwallet-sdk 版本，只传递必要环境变量，结合 security-review Skill 做高权限操作安全审查，并优先在测试网验证。

---