AgentPay-mcp

npx agentpay-mcp

* **零 LiteLLM 依赖。** 对 LiteLLM 或任何重量级 LLM 路由层均无直接或传递依赖。当 LiteLLM 1.82.7-1.82.8 版本于 2026 年 3 月在 [PyPI 上被攻陷](https://github.com/berriai/litellm/issues) 时，AgentPay MCP 用户未受影响。
* **可审计的最小依赖树。** 服务器运行在 `viem`、`@modelcontextprotocol/sdk` 以及一小批可审计的 npm 包之上。无 PyPI。无需 Python 运行时。
* **企业信任信号。** 已集成到 [NVIDIA 官方 NeMo Agent Toolkit Examples](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)（PR #17，已合并）。NVIDIA 的审查流程在合并前验证了安全态势。
* **非托管架构。** 私钥永不离开本地机器。链上支出上限即使在代理或其密钥被攻陷时也能强制执行限制。
* **Vercel 部署加固。** 如果你在 Vercel 上部署 AI 代理，请在 OAuth、仪表盘、CI 或环境变量暴露后重新连接付费工具之前，查看 [Vercel 部署加固清单](docs/vercel-deployment-hardening.md)。
* **x402 扫描器就绪。** 对于需要扫描器可读的 x402 支持的付费 API 演示，请使用 [x402 扫描器就绪配方](docs/x402-scanner-readiness.md)。
* **x402 Bazaar 可观测性。** 对于进入可搜索 Bazaar 目录的付费 MCP 工具，请使用 [x402 Bazaar 可观测性配方](docs/x402-bazaar-observability.md) 以覆盖 WithBazaar 搜索元数据、统一认证和 `EXTENSION-RESPONSES` 回读。
* **x402 批量结算通道。** 对于使用存款、代金券、退款和索赔流程的重复付费 MCP 调用，请使用 [x402 批量结算通道配方](docs/x402-batch-settlement-channels.md) 以保持通道存储、代金券上限、恢复和链下结算审计追踪的生产安全。
* **x402 多 SDK 批量结算对等性。** 对于测试 x402 TypeScript 和 Go 批量结算客户端的提供商，请使用 [多 SDK 批量结算对等性配方](docs/x402-multi-sdk-batch-settlement-parity.md) 以证明共享通道状态、分阶段端到端结果、签名者分离、退款/恢复可见性和证明包形态。
* **x402 TVM 就绪。** 对于来自新兴 x402 示例的 TVM/TON 精确支付报价，请使用 [x402 TVM 就绪说明](docs/x402-tvm-readiness.md) 以确认不支持的 TVM 需求在存在审慎的签名、gas、jetton 和结算支持之前以失败关闭方式处理。
* **x402 MCP 资金 UX。** 对于托管资金链接和托管钱包比较，请使用 [x402 MCP 资金 UX 基准](docs/x402-mcp-funding-ux-benchmark.md) 以将引导速度与审批门槛、每日上限、可审计性和非托管控制分开。
* **目录内省就绪。** 对于 Glama、Smithery 和其他 MCP 目录，请使用 [目录内省就绪说明](docs/directory-introspection-readiness.md) 以获取已验证的 `npx`、Docker、MCP 名称和非托管元数据路径。
* **x402 v2.11 付费 MCP 兼容性。** 使用 [兼容性证明](docs/x402-v211-paid-mcp-compatibility.md) 处理 `Payment-Signature`、`payment-response`、`mcp-session-id`、CORS 暴露头、Streamable HTTP 初始化顺序、收据链接以及 Base Sepolia 到 Base 主网的切换。
* **目录级元数据证明。** 使用 [注册表/列表证明](docs/mcp-registry-listing-proof.md)、`docs/mcp-registry-listing.json`、`glama.json`、`smithery.yaml` 和 `llms.txt` 供目录爬虫和买家代理使用。
* **链中立的 x402 网关配置文件。** 使用 [链中立网关配置文件证明](docs/x402-chain-neutral-gateway-profile.md)、模式和夹具来记录支持的网络、促进者/结算元数据、试用/退款策略和目录清单，而不会将仅限 Base 的假设泄漏到非 EVM 发现中。
* **多账本 x402 收据规范化。** 使用 [多账本收据规范化证明](docs/x402-multi-ledger-receipt-normalization.md)、模式和 XRPL 夹具，在签名前规范化账本标签、资产、结算目标、`Payment-Signature`、`payment-response`、验证状态、非托管边界和不支持账本的拒绝。
* **钱包操作预检配置文件。** 使用 [钱包操作预检配置文件](docs/wallet-action-preflight-profile.md) 和 TRON 夹具，要求在不可逆发送、交换或资源购买之前进行模拟、链/资源上限、允许列表、收款人和金额确认、nonce 指导和批准文案。
* **机器支付目录列表包。** 使用 [目录列表包](docs/agentpay-machine-payment-directory-listing-pack.md) 和 [列表 JSON](docs/agentpay-machine-payment-directory-listing.json) 用于 MPP 和付费 MCP 目录，而不声称支持非 EVM 签名。
* **五工具 x402 对等性证明。** 使用 [五工具对等性证明](docs/agentpay-five-tool-parity-proof.md) 和 [机器可读映射](docs/agentpay-five-tool-parity-proof.json) 将搜索、检查、获取、钱包和支付流程映射到 AgentPay 的本地签名者、审批门控控制。
* **托管和声誉边界。** 使用 [托管/声誉边界证明](docs/agentpay-escrow-reputation-boundary.md) 以将 x402 支付授权与任务托管、身份、声誉和工作证明分开。
* **付费 MCP 代理和发现就绪。** 使用 [付费代理和发现就绪包](docs/paid-mcp-proxy-discovery-readiness.md) 以及 [列表 JSON](docs/agentpay-paid-proxy-discovery-listing.json) 用于 Toolstem/Cinderwright 风格的代理和目录提交。
* **动态付费 MCP 清单漂移。** 使用 [动态清单漂移证明](docs/x402-dynamic-paid-mcp-manifest-drift.md)、模式和 Rug Munch 夹具，在买家代理签名前验证新鲜的 `.well-known/x402` 快照、过期元数据警告、无试用/定价清晰度、支持的网络和目录端点新鲜度。
* **Smithery 付费 MCP 安装。** 使用 [Smithery 安装证明](docs/smithery-paid-mcp-installation.md) 和 [`examples/smithery-paid-mcp-installation`](examples/smithery-paid-mcp-installation/) 处理 Smithery CLI、Vercel AI SDK MCP、`@smithery/api`、审批门槛、支出限额默认值和新鲜的 x402 清单检查。在列表验证之前，不要声称已通过实时 Smithery 验证。
* **x402 原生与 Stripe 代理 MCP。** 对于比较 AgentPay MCP 与新兴 Stripe 代理 MCP 仓库的构建者，请使用 [x402 原生与 Stripe 代理说明](docs/x402-native-vs-stripe-proxy.md) 以将审批门槛、支出上限、审计行和非托管签名与代理计费声明分开。
* **托管 x402 代理验证。** 在代理向托管 x402 MCP 网关付款之前，请使用 [托管 x402 代理买家清单](docs/hosted-x402-proxy-verification.md) 以验证 `payment-required` 头、非零 `payTo`、网络和资产允许列表、审批状态、支出上限、审计关联和池化代币锁定。
* **付费 MCP 发现和预算响应。** 对于 SettleGrid 风格的发现、计量和预算平台比较，请使用 [付费 MCP 发现和预算响应](docs/settlegrid-paid-mcp-discovery-response.md) 以将目录发现与 x402 买家授权分开。
* **一键 x402 工具的买家流程对等性。** 对于 AgentScore Pay 风格的买家 CLI 比较，请使用 [AgentPay 买家流程对等性清单](docs/agentpay-buyer-flow-parity.md) 以在签名前证明发现、检查、试运行、支付、支出上限、类型化支付错误、配额信封、无收费失败、幂等性、MCP 暴露和审计。
* **付费 MCP 网关加固。** 对于 create-mcpay 风格的 Worker 脚手架，请使用 [付费 MCP 网关加固清单](docs/paid-mcp-gateway-hardening.md) 以测试注册、挑战解析、密钥铸造、原子计费、范围默认值、无收费验证失败和买家审计行。
* **付费提供商健康证明。** 对于 Voidly 风格的公共提供商健康源，请使用 [付费提供商健康证明清单](docs/paid-provider-health-proof.md) 以在签名前验证提供商成功率、过期连续记录、收据状态、x402 网络、资产、payTo 和失败关闭路由。
* **付费工具质量阈值。** 对于 Strale 风格的评分目录，请使用 [付费工具质量阈值证明](docs/paid-tool-quality-thresholds.md) 以在 x402 签名前验证新鲜评分字段、过期评分警告、提供商健康快照、最低质量拒绝和审批门槛。
* **授权网络安全扫描。** 对于 AgentAegis 风格的付费安全工具，请使用 [授权网络安全扫描支付配置文件](docs/authorized-cybersecurity-scan-profile.md) 以要求目标授权、允许域绑定、每目标支出上限、扫描速率策略、审批提示和审计收据措辞。
* **后量子支出信封兼容性。** 对于 PQSafe 风格的买家问题，请使用 [后量子支出信封评估](docs/post-quantum-spend-envelope-compatibility.md) 以映射支出限额、允许列表、x402 收据、审批门槛和审计元数据，而不声称实现 ML-DSA。
* **支付关键依赖固定。** 对于 x402 验证器和签名路径，AgentPay 将 `viem` 精确固定在 `2.52.2`，强制执行相同的根覆盖，并在发布前运行干净安装冒烟检查。参见 [依赖固定策略](docs/dependency-pin-policy.md)。
* **WhatsApp 和 SMB 代理控制。** 对于渠道原生付费代理，请使用 [WhatsApp 和 SMB 付费代理控制配方](docs/whatsapp-smb-agent-controls.md)。
* **渠道代理联盟支付控制。** 对于 Axon 风格的联盟和推荐收入分成，请使用 [渠道代理联盟控制规范](docs/channel-agent-affiliate-controls.md) 以将支付上限、每联系人审批、审计行和可选的 x402 结算与付费工具支出审批分开。
* **x402 链漂移。** AgentPay MCP 跟踪 x402 Foundation 付费墙模板基线，精确使用 `viem` `2.52.2`，并对未映射的链以失败关闭方式处理。对于 PaymentWrapper 和付费墙模板更改，请遵循 [x402 链漂移兼容性说明](docs/x402-chain-drift-compatibility.md)。

如果你的安全团队在 LiteLLM 事件后审计 MCP 服务器依赖，`npm ls` on agentpay-mcp 会给你一个简短、可审查的树，且零 Python 供应链暴露。

***

## 信任与治理 — A2A 协议对齐

Google 的 [Agent2Agent (A2A) 协议](https://github.com/a2aproject/A2A)（v1.0.0）确立了代理如何在组织边界之间发现、认证和协作。该规范围绕 Agent Cards、安全方案和人在环任务管理构建——但它有意不在协议层面定义*支出治理*。

agentpay-mcp 作为互补的治理层填补了这一空白。以下是我们控制措施与 A2A 架构的映射方式：

| A2A 概念                                         | 规范定义的内容                                        | agentpay-mcp 新增的内容                                                                                                                       |
| --------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent Cards**（`capabilities`、`securitySchemes`） | 代理声明它们能做什么以及如何认证      | agentpay-mcp 将 *支出策略* 添加为可发现的能力 — 每日上限、每笔交易限额、审批阈值                               |
| **人在回路**（`input-required` 任务状态） | 任务可以在执行过程中暂停以等待人工输入                | agentpay-mcp 在支付中强制执行这一点：超过可配置阈值的交易会在执行前排队等待明确的人工审批      |
| **安全方案**（OAuth、API keys、mTLS）        | 代理之间的认证                                | agentpay-mcp 提供了 *授权* 补充 — 不仅仅是“这个代理是否被允许连接？”而是“这个代理是否被允许花费 $X？” |
| **扩展**（规范 §4.6）                          | 代理可以暴露核心 A2A 之外的其他结构化数据 | 支出上限、审批历史和交易收据可以作为扩展数据呈现在 A2A 任务元数据中                                |
| **不透明执行**（指导原则）            | 代理在不暴露内部细节的情况下协作                | agentpay-mcp 保持不透明性 — 付款代理的私钥和内部预算逻辑永远不会离开本地机器                      |

### 这在实践中意味着什么

当两个符合 A2A 的代理在涉及付费 API 调用的任务上协作时：

1. **发现** — 调用代理读取远程代理的 Agent Card（A2A 规范）
2. **认证** — 通过声明的安全方案进行双向认证（A2A 规范）
3. **支出治理** — agentpay-mcp 强制执行预算上限、记录交易，并将高价值支付置于人工审批门控之下（agentpay-mcp 层）
4. **审计** — 完整的链上交易轨迹提供合规证据，不依赖任一代理的内部状态

这使 agentpay-mcp 成为符合 A2A 的代理生态系统的**支出治理层** — 用企业在部署自主代理之前所需的财务控制来补充协议的身份和任务管理。

> **注意：** A2A v1.0.0 规范未在协议层面定义信任评分或信任信号机制。agentpay-mcp 的治理控制（支出上限、人工审批、链上审计轨迹）旨在与未来信任相关扩展兼容，随着 A2A 生态系统的发展。

***

## AI 代理发现

AgentPay MCP 旨在让 AI 代理发现和使用。兼容：

* **[claude-mem](https://github.com/thedotmack/claude-mem)** - 支付状态（交易历史、预算、会话令牌）通过 claude-mem 的观察层作为代理记忆跨会话持久化
* **[AgentSkills](https://agentskills.io)** - 可作为跨框架技能安装到任何兼容 AgentSkills 的框架（Claude Code、Cursor、Gemini CLI、Antigravity）
* **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** - 作为浏览器原生代理的支付层配对使用

### 作为技能安装

添加到任何兼容 MCP 的框架配置中：

GXP1

适用于 Claude Code、Cursor、Gemini CLI、OpenClaw、Windsurf 以及任何 MCP 客户端。

***

## 402 流程 — 它实际做什么

GXP2

***

## agentpay-mcp 与 x402-mcp — 有什么区别？

两个项目都支持代理支付。它们在不同层面解决不同的问题。

| 能力                     | **agentpay-mcp**                                                                                     | **x402-mcp**（Coinbase）          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------- |
| **支付执行**          | ✅ x402 + Stripe MPP                                                                                  | ✅ 仅 x402                      |
| **链上支出上限**        | ✅ 智能合约强制执行                                                                            | ❌ 无上限                        |
| **每会话预算限制**  | ✅ 硬性会话上限                                                                               | ❌ 每会话无限制          |
| **每日总限额**     | ✅ 可配置的每日最大值                                                                             | ❌ 无每日限制                |
| **人在回路审批** | ✅ 基于阈值的队列                                                                              | ❌ 仅完全自主          |
| **交易模拟**     | ✅ 提交前试运行                                                                              | ❌ 要么执行要么不执行             |
| **多协议支持**     | ✅ x402 V1/V2 + Stripe MPP                                                                            | ⚠️ 仅 x402                     |
| **OWS 钱包兼容性**   | ✅ MoonPay Open Wallet Standard                                                                       | ❌ 仅 Coinbase 钱包           |
| **审计轨迹**                | ✅ 包含商户、金额、状态的完整交易历史                                                      | ⚠️ 基础交易日志                  |
| **FinOps 集成**         | ✅ 按会话/代理进行成本归属                                                                 | ❌ 不可用                  |
| **故障关闭策略引擎**  | ✅ 错误 → 拒绝，绝不批准                                                                 | ❌ 无策略引擎               |
| **非托管**              | ✅ 密钥永不离开本地机器                                                                     | ✅ 密钥永不离开本地机器 |
| **企业信任信号**    | ✅ [NVIDIA NeMo Toolkit PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) 已合并 | —                                |

**何时使用 x402-mcp：** 你想要尽可能简单的 x402 支付集成，且没有治理要求。你的代理以无限预算权限运行。

**何时使用 agentpay-mcp：** 你需要支出控制、预算强制执行、人工审批工作流或多协议支持。你的代理在真实的企业预算下运行，失控支出是部署的阻碍。

> x402-mcp 为你的代理添加支付能力。agentpay-mcp 添加的是*受治理的*支付 — 支出上限、会话限制、人工审批和审计轨迹，这些是企业在对生产预算部署代理之前所要求的。

***

## 常见问题：x402 原生 AgentPay MCP 与 Stripe 代理 MCP

公开的 MCP 支付仓库开始使用 x402 加 Stripe Agent 的措辞来进行发现。请将其视为市场信号，而不是每个代理都已提供完整支出控制的证明。

**主要区别是什么？**

AgentPay MCP 将支付决策保留在代理的策略边界内。代理请求 `x402_pay`，AgentPay 在签名前检查审批状态和支出策略，审计轨迹记录工具、金额、商户、收据和策略结果。Stripe 代理模式通常在下游服务前放置一个支付或计费代理。

**为什么不对每次付费 MCP 调用都使用代理？**

代理可以帮助处理计费和账户聚合。但它不能自动回答谁批准了这笔支出、代理是否保持在任务预算之内，或者签名是否在策略批准之前被阻止。AgentPay MCP 在支付执行之前处理这些控制。

**目录或买家今天可以检查哪些证据？**

* npm：`agentpay-mcp@4.1.9` 或更新版本
* Glama：<https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp>
* 目录元数据：`glama.json` 和 `smithery.yaml`
* 安装路径：`npx` 和 Docker
* 内省：27 个 MCP 工具，包括 `x402_pay`、`check_budget`、`set_spend_policy` 和 `otel_evaluate_spend`

**这与 Lightning Wallet MCP 相比如何？**

Lightning Wallet MCP 是一个比特币钱包 MCP，面向 Glama 的徽章工作和 x402 回退定位。AgentPay MCP 专注于 x402 支付工具治理：审批门控、硬性支出上限、非托管本地签名、目录元数据以及与付费工具调用关联的审计行。

完整清单请参阅 [x402 原生 AgentPay MCP 与 Stripe 代理 MCP 模式](docs/x402-native-vs-stripe-proxy.md)。

对于托管的付费 MCP 网关，在签署前使用 [托管 x402 代理买家验证清单](docs/hosted-x402-proxy-verification.md)。它会检查 `payment-required` 头、`payTo`、链、资产、支出上限、审批门控、审计日志和池化代币锁定。

对于单命令买家 CLI 比较，请使用 [AgentPay 买家流程对等清单](docs/agentpay-buyer-flow-parity.md)。它将发现、检查、试运行、支付、支出上限、类型化支付错误、配额信封、无费用失败、幂等性、MCP 暴露和审计转化为故障关闭测试夹具。对于付费 Worker 模板，在将脚手架视为生产就绪之前，请使用 [付费 MCP 网关加固清单](docs/paid-mcp-gateway-hardening.md)。

***

## 快速开始

### 1. 安装

GXP3

### 2. 配置 Claude Desktop

添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：

GXP4

### 3. 配置 Cursor

添加到 `.cursor/mcp.json` 或 `~/.cursor/mcp.json`：

GXP5

### 4. 设置支出上限

运行后，告诉你的代理：

GXP6

或直接调用 `set_spend_policy`：

GXP7

现在你的代理可以支付 API 费用 — 并且无论被指示做什么，单次花费不能超过 $1，每天不能超过 $10。

***

## 人工审批模式（默认）

默认情况下，超过自动批准阈值的交易会排队等待人工审核。代理无法绕过这一点。

GXP8

批准排队中的支付：

GXP9

拒绝它：

GXP10

代理会看到结果并决定下一步做什么（使用缓存数据、询问用户、中止）。

***

## 价值包 — 三种生产工作流模式

### 1. 付费 API 代理

**功能：** 为数据需求找到合适的付费 API，支付一次，缓存结果。

**适用场景：** 你的代理需要数据（市场数据、数据丰富、地理编码），你希望它自动处理支付，而不是因 402 而失败。

GXP11

**使用的工具：** `x402_pay`、`check_spend_limit`、`get_transaction_history`

**示例交互：**

GXP12

***

### 2. 研究代理

**功能：** 首先从免费来源收集，用付费数据填补空白，汇编结构化输出。

**适用场景：** 你需要一份全面的研究报告，并且希望代理只在免费数据确实不足的地方花钱。

GXP13

**使用的工具：** `x402_pay`、`x402_session_start`、`x402_session_fetch`、`check_budget`

**示例交互：**

GXP14

***

### 3. 自动化代理

**功能：** 端到端完成真实任务，沿途为所需的服务付费。

**适用场景：** 你想要一个能真正完成工作的代理 — 预订通话、运行数据丰富管道、部署某些东西 — 而不仅仅是研究它。

GXP15

**使用的工具：** `x402_pay`、`x402_session_start`、`set_spend_policy`、`get_transaction_history`

***

## 企业 FinOps — 预算上限模板

生产级代理部署需要满足企业 FinOps 要求的支出治理。这些模板展示了在基础设施层控制代理支出的常见模式。

### 按代理的部门预算

GXP16

### 分级审批阈值

将组织的审批矩阵映射到代理支出层级：

GXP17

使用 `set_spend_policy` 设置自动批准上限（由 MCP 服务器强制执行的进程内上限）。高于合约上由钱包所有者配置的 *链上* AgentAccountV2 限额的交易，会通过智能合约本身排队等待人工审核。

### 面向 FinOps 仪表板的预算监控

为 FinOps 工具拉取实时支出数据：

GXP18

这些模式适用于任何 FinOps 平台（CloudHealth、Kubecost、Apptio）——通过 MCP 工具导出交易历史，并将其输入现有的成本归因管道。

***

## 环境变量

GXP19

**终止回调 SSRF 限制。** `killCallbackUrl` 必须是 http(s)，不得嵌入凭据，且不得指向私有、回环、链路本地或其他非全局可路由地址（RFC1918、CGNAT、组播、保留地址、IETF 协议分配、基准测试和文档范围，以及 IPv6 等价地址和所有 IPv4-in-IPv6 过渡形式）。主机名会在回调触发前立即解析并按照相同规则重新检查。一个固定的 10 秒截止时间同时覆盖 DNS 解析和 POST 请求，因此永不响应的解析器无法拖住 span 评估。

有一个缺口**未**被封闭：连接不会固定到已验证的地址，因此解析器在检查时返回公共地址、连接时返回私有地址（DNS 重绑定）仍可能被访问。要封闭此缺口，需要将此调用从全局 `fetch` 迁移到带有固定 `lookup` 的 `node:http`/`node:https`，这已单独跟踪。如果今天就需要硬性保证，请在 webhook 前加一层网络级出口白名单。未送达的回调仅报告 `ok=false` 并附带一个通用原因——HTTP 状态和具体失败信息绝不会返回给调用方，只会在服务端记录（仅记录来源，绝不记录回调路径或查询）。

***

## 全部 23 个工具

### 支付与 402 流程

| 工具                  | 功能                                                          |
| --------------------- | ------------------------------------------------------------- |
| `x402_pay`            | 获取 URL，自动支付 402，重试——核心用例                        |
| `x402_session_start`  | 支付一次，获取可复用的基础 URL 会话令牌                       |
| `x402_session_fetch`  | 在活动会话内发起调用（无需再次支付）                          |
| `x402_session_status` | 检查活动会话和 TTL                                             |
| `x402_session_end`    | 显式关闭会话                                                  |

### 钱包与支出控制

| 工具                      | 功能                                                      |
| ------------------------- | --------------------------------------------------------- |
| `get_wallet_info`         | 地址、余额、支出限额、队列深度                            |
| `send_payment`            | 通过 AgentAccountV2 合约发送 ETH 或 ERC-20                |
| `check_spend_limit`       | 当前周期剩余支出限额                                      |
| `set_spend_policy`        | 配置每日限额、单笔交易上限、收款人白名单                 |
| `check_budget`            | 查询链上剩余预算                                          |
| `queue_approval`          | 批准或取消排队中的交易                                    |
| `get_transaction_history` | 带筛选的链上事件日志                                      |
| `deploy_wallet`           | 部署新的 AgentAccountV2 智能合约钱包                      |

### 代币操作

| 工具                | 功能                                                              |
| ------------------- | ------------------------------------------------------------------- |
| `lookup_token`      | 按符号和链查询代币地址 + 小数位数                                  |
| `add_custom_token`  | 在代币注册表中注册自定义 ERC-20                                    |
| `list_chain_tokens` | 某条链上所有已注册代币                                            |
| `send_token`        | 发送任意注册代币（自动解析地址 + 小数位数）                        |
| `get_balances`      | 查询一个或多个代币的余额                                          |

### DeFi

| 工具          | 功能                                                |
| ------------- | ------------------------------------------------------- |
| `swap_tokens` | 在 Base、Arbitrum、Optimism 或 Polygon 上进行 Uniswap V3 交换 |
| `bridge_usdc` | CCTP V2 跨链 USDC 桥接（10 条 EVM 链，约 12 秒）        |

### 身份与信任

| 工具                    | 功能                                                |
| ----------------------- | ------------------------------------------------------- |
| `verify_agent_identity` | ERC-8004 链上身份验证                                 |
| `get_reputation`        | 链上信誉评分和历史                                    |
| `create_escrow`         | 双方质押 USDC 的托管——双方锁定抵押品                |

***

## 关键工具示例

### `x402_pay` — 核心工具

GXP20

如果成本超过 `max_payment_eth`，工具会在支付前返回错误——不会产生意外费用。

### `x402_session_start` — 支付一次，多次调用

GXP21

GXP22

### `check_budget` — 循环前先了解预算

GXP23

***

## 支持的链

| 链                                   | 链 ID   | 推荐用途                                       |
| ------------------------------------- | -------- | ------------------------------------------- |
| Base 主网                            | 8453     | 一切——最低 gas，最多 x402 活动               |
| Arbitrum One                          | 42161    | 高吞吐量交换                                 |
| Optimism                              | 10       | 低成本转账                                   |
| Polygon                               | 137      | 高频微支付                                   |
| Ethereum 主网                         | 1        | 身份、大额结算                               |
| Avalanche                             | 43114    | 桥接、转账                                   |
| Linea / Unichain / Sonic / Worldchain | 各不相同 | 桥接、转账                                   |
| Base Sepolia                          | 84532    | 测试                                         |

***

## 安全模型

**非托管：** 代理使用其私钥在本地签署所有交易。没有第三方持有或验证密钥。

**链上强制**（AgentAccountV2 限额，由钱包所有者在合约上配置）：

* 单笔交易上限——超限交易通过 `queue_approval` 排队等待人工批准
* 每日周期限额——由 AgentAccountV2 智能合约强制执行的聚合支出

**进程内策略**（`set_spend_policy`——在 MCP 服务器中强制执行，而非链上）：

* 收款人白名单、单笔交易上限和每日限额——一种便利性护栏，可被受入侵的服务器进程绕过。有关确切的控制边界，请参阅 [docs/security-posture.md](docs/security-posture.md)。

**角色分离：**\
代理的签名密钥（`AGENT_PRIVATE_KEY`）只能在钱包所有者设定的限额内进行交易。即使代理的密钥泄露或代理被入侵，攻击者也只能在下次重置前花费最多到配置上限的金额。

**x402 会话：**\
会话令牌是 ECDSA 签名的声明。任何 x402 V2 服务器都可以独立验证它们——无需中央会话存储。

**最小依赖足迹：**\
AgentPay MCP **零 LiteLLM 依赖**。整个服务器运行在 `viem`（以太坊客户端）、`@modelcontextprotocol/sdk` 和少量可审计的包上——依赖树中没有重量级 LLM 路由层。这一点很重要：2026 年 3 月 24 日，PyPI 上的 LiteLLM 1.82.7 和 1.82.8 版本被[确认在供应链攻击中受损](https://github.com/berriai/litellm/issues)，该攻击针对 AI 代理基础设施。任何依赖 LiteLLM（直接或传递）的 MCP 服务器都已暴露。AgentPay MCP 没有——因为支付基础设施应该具有尽可能小的攻击面。

***

## agentpay-mcp 已支持多种支付轨道

代理支付格局刚刚分裂：Coinbase 的 x402（开放、无需许可、链上）与 Stripe 的 MPP（需许可、基于 Tempo、USDC）。构建生产级代理的开发人员面临选择——或者他们使用 agentpay-mcp，它已经位于两者之上。

agentpay-mcp **在设计上就是协议无关的：**

| 支付轨道            | 状态         | agentpay-mcp 如何与之配合                                                                        |
| ------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| **x402（Coinbase）** | ✅ 已支持     | 原生 x402 V1/V2 支付执行，带链上支出上限                                                              |
| **Stripe MPP**      | ✅ 兼容       | MPP 兼容的结算层分离——agentpay-mcp 在 MPP 的结算之上管理支出策略                                     |
| **未来轨道**        | ✅ 已就绪     | 中立治理架构——新轨道无需代码更改即可接入                                                              |

**为什么这很重要：** x402 和 MPP 都不提供支出治理。x402 钱包默认无限制。MPP 提供人工设置的仪表板限额，但没有程序化的每会话或每任务强制。agentpay-mcp 在两者之上提供预算断路器、审批工作流和审计追踪——无论哪个轨道结算交易。

这不是对单一协议的封装。这是一个治理层，在**策略**（谁批准的、预算是多少、是否应有人工审核）和**结算**（哪个区块链或支付网络移动资金）之间进行了刻意分离。正是这种分离使 agentpay-mcp 具有轨道中立性——也使其在协议之争中定位为治理标准。

***

## 与 AWS AgentCore 配合使用

AWS AgentCore 提供企业级代理托管，并使用基于 Cedar 的策略执行进行访问控制。Cedar 策略回答：“此代理是否被允许调用此 API？”以及“此代理能否访问此资源？”

Cedar 不提供的内容：**支出限额。** 没有 Cedar 原语用于“此代理每会话最多可花费 50 美元”或“如果今日累计支出超过 200 美元则暂停代理”。访问控制和预算治理是不同的问题。

agentpay-mcp 在 AgentCore 之上添加了预算断路器：

| 层                 | 谁处理            | 控制内容                                                                      |
| --------------------- | --------------------- | ------------------------------------------------------------------------------------- |
| **访问控制**    | AWS AgentCore（Cedar） | 代理可以调用哪些 API，可以访问哪些资源                          |
| **预算治理** | agentpay-mcp          | 代理每笔交易、每会话和每日可以花费多少                |
| **人工监督**   | agentpay-mcp          | 自主操作何时暂停以等待人工批准                                   |
| **审计追踪**       | 两者（互补）  | Cedar 记录访问决策；agentpay-mcp 记录支出决策并附链上收据 |

**部署模式：** AgentCore 运行代理，Cedar 策略控制工具访问。agentpay-mcp 作为 MCP 服务器在代理的工具集中运行，对每个支付操作强制执行支出上限。Cedar 说“你可以调用这个付费 API。”agentpay-mcp 说“你可以在这次调用上花费最多 5 美元。”

GXP24

对于在 AgentCore 上运行代理的企业：Cedar 处理“能否”的问题。agentpay-mcp 处理“是否应该花这么多”的问题。两者结合，提供了生产级代理部署所需的访问 + 预算治理栈。

***

## 竞争定位

**最简单的理解方式：ACP (Stripe) 处理智能体销售（SELL）的部分，agentpay-mcp 处理智能体购买（BUY）的部分。**

### Stripe MCP 与 agentpay-mcp 对比

开发者经常问："Stripe MCP 不是已经处理了智能体支付吗？" 答案是 **它们在不同层面解决不同的问题**：

|                        | Stripe MCP                         | agentpay-mcp                                               |
| ---------------------- | ---------------------------------- | ---------------------------------------------------------- |
| **资金流向** | 用户向商家付款（通过智能体） | 智能体向 API 提供商付款 |
| **使用场景**           | 结账、订阅、开票 | API 访问、工具支付、智能体间商务 |
| **结算**         | 传统卡组织通道             | 链上（Base、EVM）或 Stripe MPP |
| **支出控制**     | 客户侧（购物车 + 结账）    | 智能体侧（链上限额、人工审批、会话限制） |
| **协议**           | ACP（智能体商务协议）      | x402（HTTP 402 支付要求） |

**Stripe MCP** 是一个 *商家工具* —— 它帮助企业通过智能体界面从客户那里收费。可以理解为"购买此产品"或"订阅该套餐"。

**agentpay-mcp** 是一个 *智能体采购工具* —— 它让智能体能够为完成工作所需的 API 和工具付费。可以理解为"访问此高级数据端点"或"使用此计算资源"。

大多数生产环境中的智能体将同时需要这两层：Stripe MCP 用于面向用户的商务，agentpay-mcp 用于智能体自身的工具成本。它们是互补的，而不是竞争关系。

***

## MCP 2026 合规性

AgentPay MCP 符合即将出台的 2026 年 MCP 安全标准，包括 CoSAI（安全 AI 联盟）威胁类别和 OAuth 2.1 要求。

**安全态势文档：** 有关完整的合规性矩阵，请参阅 [`docs/security-posture.md`](docs/security-posture.md)，其中涵盖：

* **CoSAI T9（金融欺诈）** — 分层支出控制：进程内支出策略（`set_spend_policy`，在 MCP 服务器进程中强制执行——而非链上）以及由钱包所有者配置的链上 AgentAccountV2 限额和审批队列
* **CoSAI T10（身份欺骗）** — ERC-8004 智能体身份验证 + 非托管密钥管理可防止基于身份的攻击
* **OAuth 2.1 + PKCE** — MCP 服务器身份验证支持带 PKCE 的 OAuth 2.1，用于企业 SSO 集成（Azure AD、Okta）
* **审计日志** — 通过 `get_transaction_history` 获取链上 AgentAccountV2 事件历史记录（执行、排队交易、审批、策略更新）；没有按工具调用级别的日志——有关具体记录和不记录的内容，请参阅安全态势文档

对于评估 MCP 服务器的企业安全团队：安全态势文档提供了审计流程所需的工件。

***

## 架构

GXP25

传输方式：默认使用 `stdio`（Claude Desktop、Cursor、Windsurf）。远程部署可使用 SSE。

***

## 贡献

GXP26

***

## 专利声明

**专利待批** — 2026 年 3 月提交的美国临时专利申请："用于自主 AI 智能体的非托管多链金融基础设施系统"。

我们支持开放的 x402 标准。我们的申请是防御性的——旨在防止开放支付轨道的恶意垄断，而不是限制使用开放标准的开发者。

***

## Vercel x402-mcp 互操作性

agentpay-mcp 与 Vercel 的 [`x402-mcp`](https://www.npmjs.com/package/x402-mcp) 包完全兼容。如果您使用 Vercel 的 `paidTool()` 来通过 MCP 工具获利，agentpay-mcp 可作为客户端支付层——您的智能体会通过 `x402_pay` 自动支付来自 `paidTool()` 端点的 x402 发票。

**agentpay-mcp 在 x402-mcp 基础上增加的功能：**

* **多轨道支付** — 根据商家情况，通过 x402（链上 USDC）或 Stripe 机器支付协议（法币）进行路由
* **支出治理** — 每笔交易限额、每日限额和人工审批队列，这些是 `paidTool()` 端点在客户端不强制执行的
* **多链 x402 v2** — 在 Base、Solana 或 Polygon 上支付（x402 v2 原生支持所有这三个网络）

在服务器端使用 Vercel x402-mcp 来通过您的工具获利。在客户端使用 agentpay-mcp 来安全地支付工具费用。

***

## Circle 纳米支付 — 零 Gas 结算

agentpay-mcp 支持 [Circle Nanopayments](https://www.circle.com/nanopayments) 作为 x402 v2 支付的结算选项。纳米支付通过将小额支付批量合并为单笔链上结算，实现免 Gas 的美分以下 USDC 转账。

**与 agentpay-mcp 的协作方式：**

* 智能体照常通过 `x402_pay` 进行 x402 支付
* 如果 x402 v2 服务器支持 Circle 纳米支付，则结算将免 Gas 进行
* 美分以下的支付（$0.001、$0.0001）对于按次调用的 API 定价变得经济可行
* 通过 Circle 的 Gateway 实现跨链支持——适用于任何 EVM 链

这对于高频智能体工作流尤其有用，因为在这些工作流中，Gas 成本可能会超过支付金额。有关协议详情，请参阅 [Circle 的公告](https://www.mexc.com/news/971904)。

***

## x402 生态系统 — 超过 7500 万笔交易，Cloudflare 原生支持

agentpay-mcp 基于 [x402 HTTP 支付标准](https://x402.org) 构建，该标准目前在 **Base 主网上已处理超过 7500 万笔交易**——主要通过 Coinbase Agentic Wallets 和开发者集成实现。

**Cloudflare 已在其 Agents SDK 和 MCP 服务器运行时中增加了对 x402 的原生支持**，这意味着任何由 Cloudflare Worker 托管的智能体现在都可以原生进行 x402 支付。Google、Circle 和 Stripe 都在积极将 x402 集成到其智能体生态系统中。

agentpay-mcp 是该基础设施之上的**开源治理层**：x402 处理支付协议，而 agentpay-mcp 增加了生产环境智能体所需的信任控制——人工审批队列、支出上限、接收方白名单和链上审计跟踪。

| x402 生态系统                | 状态                |
| ----------------------------- | --------------------- |
| Base 主网交易     | 7500 万+                  |
| Cloudflare Agents SDK         | ✅ 原生支持      |
| Cloudflare MCP 服务器        | ✅ 原生支持      |
| Coinbase Agentic Wallets      | ✅ 主要客户端      |
| Google / Circle / Stripe      | 🔄 积极集成 |
| agentpay-mcp 治理层 | ✅ 开源         |

***

## OpenAI 委托支付规范兼容性

OpenAI 发布了一份**委托支付规范**，定义了 AI 智能体如何代表用户处理支付：一个带有额度上限的范围限定令牌，与 Stripe 范围限定支付令牌（SPT）兼容。这是 OpenAI Agents SDK 中原生支付工具的前身架构。

**agentpay-mcp 的支出上限模型与委托支付规范模式直接一致：**

| 委托支付规范概念                             | agentpay-mcp 实现                                                                                                                      |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **范围限定令牌** — 智能体收到有限范围的凭据 | `AGENT_PRIVATE_KEY` — 智能体在智能合约约束内签名，不能超出范围 |
| **额度上限** — 智能体可以花费的最高金额            | 通过 `set_spend_policy` 进行进程内每笔交易和每日上限，以及钱包所有者在合约上配置的链上 AgentAccountV2 限额 |
| **人工审批** — 用户委托，然后智能体执行   | `queue_approval` — 超过阈值的交易需要明确的人工签署                                                                                |
| **审计跟踪** — 所有委托支出均被记录            | `get_transaction_history` — 每笔交易的不可变链上事件日志                                                                         |
| **撤销** — 用户可以随时撤销委托    | 支出策略更新即时生效；钱包所有者可以冻结智能体密钥                                                                          |

核心模式是相同的：**人类批准预算 → 智能体在预算内执行 → 所有活动均可审计**。区别在于结算层：OpenAI 的规范针对 Stripe SPT（法币轨道），而 agentpay-mcp 在链上结算（Base、Arbitrum 及其他 8 条 EVM 链上的 USDC/ETH）。

对于构建需要链上结算或多轨道支付执行的 OpenAI Agents SDK 工作流的开发者，agentpay-mcp 可作为 MCP 支付工具，实现委托支付规范模式，并通过链上执行而非应用级信任来保证。

GXP27

通过 MCP 桥接将此 MCP 服务器添加到任何 OpenAI Agents SDK 工作流中。智能体将获得 `x402_pay`、`check_budget` 和 `set_spend_policy`——相同的范围限定令牌 + 额度上限模式。请注意，`set_spend_policy` 在 MCP 服务器进程中强制执行；智能合约执行来自链上 AgentAccountV2 限额，由钱包所有者在合约上配置（请参阅 [docs/security-posture.md](docs/security-posture.md)）。

***

## Google AP2 兼容性

agentpay-mcp 补充了 Google 的 Agent2Agent 支付（AP2）协议。AP2 由包括 Visa、Mastercard 和 PayPal 在内的 60 多个组织支持，处理智能体支付*授权*：验证支付请求是否合法。agentpay-mcp 在 AP2 之上的治理层运行，增加了 AP2 明确界定为带外范围的每智能体预算上限、每日支出限额和人工审批阈值。对于跨多个支付轨道部署智能体的企业，agentpay-mcp 提供了任何单个协议都无法提供的统一支出治理。

***

## 欧盟 AI 法案合规性

**执行截止日期：2026 年 8 月 2 日。** 执行或促进金融交易的 AI 系统根据欧盟 AI 法案附件 III 被归类为**高风险**。高风险分类要求：

* ✅ **人工监督机制** — 强制人工审查和覆盖能力
* ✅ **透明度和可解释性** — 可审计的交易记录
* ✅ **访问控制** — 智能体无法绕过的支出限制
* ✅ **技术文档** — 合格评定支持

agentpay-mcp 开箱即用地满足所有四项要求：

| 要求       | agentpay-mcp 功能                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 人工监督   | `queue_approval` — 超过阈值的交易在执行前需要明确的人工批准                                                                                |
| 审计跟踪       | `get_transaction_history` — 完整的链上事件日志，不可变，可在 basescan.org 上验证                                                                                      |
| 支出控制    | 链上 AgentAccountV2 每笔交易和周期限制（由所有者在合约上配置，智能体无法绕过），以及进程内 `set_spend_policy` 防护栏               |
| 范围限制 | 通过 `set_spend_policy` 设置接收方白名单 — 在 MCP 服务器进程中强制执行，而非链上；有关控制边界，请参阅 [docs/security-posture.md](docs/security-posture.md) |

部署涉及支付的智能体系统的欧洲企业大约有 **150 天** 的时间来实施合规的人工监督和审计控制。agentpay-mcp 是 MCP 兼容智能体部署实现欧盟 AI 法案合规性的最快途径。

> **不合规罚款：** 最高可达3500万欧元或全球年收入的7%。德国于2026年2月发布了其国家执法法案。

***

## 许可证

MIT © [AI Agent Economy](https://ai-agent-economy.com)

由 **AI Agent Economy** 构建——面向生产级智能体工作流的基础设施。