agentpay

agentpay

一个面向 AI Agent 付款的跨支付通道支出策略网关。它位于你的 Agent 与所有向它们收费的服务之间——x402 风格的付费 API、支付宝／微信风格的 Agent 付款，以及未来出现的任何方式——并回答每家部署付费 Agent 的公司都必须面对的问题：

“如何让我的 Agent 花钱——通过多个支付通道——又不用把我的钱包交给它？”

Agent 从不持有支付凭据。它们通过网关调用付费资源，网关会：

1. 拦截 402 Payment Required 握手，并收集商户接受的所有付款选项，
2. 选择一个支付通道（优先使用 Agent 偏好的通道；如果费用相同，则选择按策略基准货币计算费用最低的通道），
3. 根据该 Agent 的支出策略检查付款——预算和限额均以一种基准货币计价，并通过精确的汇率换算在所有支付通道和货币之间统一执行，
4. 在选定的支付通道上执行获批的付款，
5. 使用付款凭证重试请求，并返回解锁后的响应，
6. 将每一项决策（包括拒绝的决策）写入只追加审计日志。

                       ┌────────────────────────────────────────────────┐      ─▶ paid API (x402, USDC)
  agent ──HTTP──▶      │  gateway                                       │
  (no keys, no wallet) │  policy ─ fx ─ router ─ ledger ─ audit ─ rails │      ─▶ paid API (Alipay, CNY)
                       └────────────────────────────────────────────────┘      ─▶ ...

_{内置仪表板（GET /admin）——实时支出与预算、各支付通道明细，以及一键批准／拒绝暂缓的付款。}

有关其构建方式和原因——设计原则、完整的 402 请求生命周期，以及简单部分如何逐步扩展——请参阅 docs/ARCHITECTURE.md。

定位——中立层

各大平台竞相让 Agent 消费，并且都在构建封闭生态：支付宝的 ACT 委托付款协议、微信支付的隔离式“AI 卡”，支持用户设置授权范围和支出限额，以及面向加密货币原生 API 的 x402。每个平台都希望 Agent 在自己的钱包中、通过自己的支付通道消费——而它们不断趋同的设计（与真实账户隔离的钱包、范围受限的授权、单笔支出限额、需确认的大额付款，以及完整的审计跟踪）正是本项目致力于构建的控制界面。这个判断已不再只是推测；这正是巨头们投入资本支出的方向。

但运行真实 Agent 的公司不可能只待在一个生态里。它的 Agent 可能通过 x402 API 使用 USDC 付款，向供应商支付 CNY，下个季度再使用其他新推出的方式——而且没有任何单一平台能为所有这些方式提供统一的中立视图：统一的基准货币预算、统一的审计跟踪、统一的策略，以及一个 Agent 从不持有凭据的统一位置。封闭生态越是分化，能够横跨它们的那一层就越缺失。

这一层就是 agentpay。它位于支付通道之上——x402、支付宝、微信、mock——并通过一个双方法接口（rails/rail.ts）连接，因此预算、策略、汇率、路由和审计只需编写一次，每个支付通道都可以接入其下方。它从设计上就与支付通道无关且可自托管：其价值恰恰在于，没有任何一个竞相构建自有生态的平台会替你构建这一层。

快速开始

npx agentpay-gateway      # gateway on http://127.0.0.1:4020, dashboard at /admin (mock rails)

从源代码运行：

npm install
npm test        # 110 tests: money, FX, policy, x402 v1+v2, MCP, persistence, approvals, security, e2e
npm run demo    # walkthrough: 2 rails, 2 currencies, 1 unified USD budget, human-in-the-loop
npm run dev     # start the gateway on :4020 (dashboard at http://localhost:4020/admin)

演示会运行一个商家，接受 USDC（x402 风格）或 CNY（支付宝风格）；两个偏好不同支付渠道的 Agent 会被路由到不同渠道，而它们共用一个 USD 预算——一笔 0.36 CNY 的购买会消耗其中约 0.0504 USD。演示还会展示每笔交易上限、收款方屏蔽列表、预算耗尽、各支付渠道的支出明细以及审计记录。

安装为 Agent 技能

skill/ 中提供了可直接安装的 Agent 技能——这是一份分步操作手册，AI 助手（Claude Code、OpenClaw、……）会按照它为你设置 agentpay：安装并自测、编写默认拒绝的策略、启动网关、将 Agent 的付费调用改为通过 /proxy 路由，然后进行日常操作（支出、审计、审批、实时编辑策略）并为生产环境加固。它还包含策略模板和故障排除与 API 参考。让你的助手查看 skill/SKILL.md，或从技能市场安装。

在 Claude / Cursor 中使用（MCP）

为 MCP Agent 设置一个它无法超出的预算。agentpay-mcp 服务仅持有 Agent 的网关 API 密钥——钱包和限额都保留在网关中。与依赖自觉遵守的预算工具不同，系统不会要求 Agent 检查预算；超出限额的付款根本不会被签名。

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "-p", "agentpay-gateway", "agentpay-mcp"],
      "env": { "AGENTPAY_URL": "http://127.0.0.1:4020", "AGENTPAY_API_KEY": "<key from POST /admin/keys>" }
    }
  }
}

工具：paid_fetch(url, method?, body?)——获取任意 URL；如果策略允许，网关会处理 x402/402 付款。拒绝和等待审批的请求会作为工具错误返回，模型可以据此进行解释。check_budget()——查看今天/本月的支出与限额（通过 Agent 专属的 GET /v1/budget，Agent 只能看到自己的数据）。

策略

策略默认拒绝：没有策略条目的 Agent 完全无法支出。请参阅 policies/example.json：

{
  "fxRates": { "USDC:USD": "1", "CNY:USD": "0.14" },  // directional pairs, exact decimals
  "defaults": { "currency": "USD", "perTransactionMax": "1.00", "dailyBudget": "10.00" },
  "agents": [
    {
      "agentId": "research-bot",
      "enabled": true,
      "currency": "USD",                        // base currency for ALL limits below
      "railPreference": ["alipay-act", "x402"], // routing order when merchants accept several rails
      "perTransactionMax": "0.25",              // cap on any single payment, in base currency
      "dailyBudget": "0.15",                    // UTC calendar day, across all rails/currencies
      "monthlyBudget": "3.00",                  // UTC calendar month
      "maxTransactionsPerDay": 200,
      "requireApprovalOver": "0.50",            // hold payments >= this for human review (base ccy)
      "payeeBlocklist": ["merchant-shady"]
      // or "payeeAllowlist": [...] to whitelist instead
    }
  ]
}

所有金额均采用精确十进制表示（bigint 微单位，6 位小数——与 USDC 精度一致）；汇率转换一律向上取整，以保守地执行预算。金额相关计算完全不使用浮点数。未配置到基础货币汇率的货币付款会被拒绝（no_fx_rate）。

API

端点	用途
ANY /proxy?url=<target>	代理请求；如果策略允许，则进行路由，并在收到 402 时付款。通过 Authorization: Bearer <api key>（已配置密钥时）或 X-Agent-Id 标识 Agent。
GET /admin	Web 仪表板（独立单页）——实时支出、待处理审批及其批准/拒绝按钮、审计记录和内联策略编辑。
GET /admin/policy	完整的实时策略配置。
GET /admin/agents	已配置的 Agent 及其解析后的限额。
PUT /admin/agents/:id	创建或替换 Agent 的策略（经过验证）。下一次请求即生效，并写回策略文件。
DELETE /admin/agents/:id	移除 Agent（恢复为默认拒绝）。
GET /admin/keys · POST /admin/keys · DELETE /admin/keys/:id	多租户 API 密钥：列出、创建（密钥仅返回一次）、撤销。
GET /admin/spend/:agentId	基础货币下的统一支出与限额，以及按原生货币显示的各支付渠道支出明细。
GET /admin/audit?agent=&limit=	每次允许/拒绝/失败/暂缓的审计记录。
GET /admin/approvals?status=	列出等待人工审核的付款（可按 pending/approved/rejected 筛选）。
POST /admin/approvals/:id	决定一笔暂缓的付款：请求体 { "decision": "approve" | "reject" }。
GET /healthz	存活状态。

成功的付款响应会携带 X-Gateway-Payment-Id、X-Gateway-Rail 和 X-Gateway-Payment-Amount 标头。拒绝响应返回 403，并附带触发的规则 ID（per_transaction_max、daily_budget、payee_blocklisted、no_fx_rate、approval_rejected，……），以便 Agent 解释原因或稍后重试。

人工审核

在 Agent 上设置 requireApprovalOver 后，任何金额达到或超过该基础货币金额且符合策略的付款都会被暂缓，而不是执行：代理会返回 202 和一个 approvalId，而不是付款。操作员通过 POST /admin/approvals/:id 批准或拒绝；Agent 重试后，付款将执行（已批准）或因 approval_rejected 被拒绝。每项审批只能使用一次，因此只能解锁一笔付款。重试时仍会在执行阶段重新检查预算。

持久化

默认情况下，账本、审计日志和审批记录都保存在内存中。将其中任意一项指向文件，即可让状态在重启后保留——.sqlite 会选择事务型 SQLite 后端（使用 Node 内置的 node:sqlite，无需额外依赖），其他文件则使用仅追加的 JSONL：

LEDGER_FILE=./ledger.sqlite AUDIT_FILE=./audit.jsonl APPROVALS_FILE=./approvals.sqlite APIKEYS_FILE=./keys.sqlite npm run dev

实时外汇汇率

静态货币对可以使用 FixedRateProvider；CachingRateProvider 则会为任意异步汇率来源（RateFetcher，默认的 httpRateFetcher 会请求 exchangerate.host）添加 TTL 和严格的过期时限。超过该时限后，缓存汇率会被拒绝（no_fx_rate），而不是继续使用——付款绝不会按过期汇率定价。稳定币挂钩汇率可以设为 pinned，使其永不过期且不再获取。

编辑策略（实时生效）

策略会在运行时变更，无需重启。PolicyManager 管理实时配置；每次决策都会读取该配置，因此编辑会在下一次请求时生效。有两种修改方式，并且会保持同步：

• 管理 API / 仪表板 — PUT/DELETE /admin/agents/:id（仪表板中的编辑铅笔按钮和“添加 Agent”按钮会调用这些接口）。每次编辑都会经过验证，记录为 policy_changed，并写回策略文件。
• 直接编辑文件 — npm run dev 会监视策略文件，并热重载外部修改。写回操作与文件监视器不会相互干扰：如果文件与内存状态逐字节相同，reload() 就不会执行任何操作，因此自身写入不会触发重载循环。（fxRates 在启动时仅构建一次，不会热重载。）

多租户 API 密钥

Agent 使用 Authorization: Bearer <key> 进行身份验证。每个 Agent 都可以通过 POST /admin/keys 或仪表板获得密钥（同一 Agent 可以持有多个密钥以便轮换）——原始密钥只会返回一次；系统只存储其 SHA-256 哈希，因此即使密钥存储泄露，也不会暴露可用凭据。密钥可以设置可选的有效期，并可即时撤销（DELETE /admin/keys/:id）；两种操作都会记录在审计日志中（apikey_created / apikey_revoked）。

默认情况下，有效的 Bearer 密钥可用于身份验证，X-Agent-Id 也仍然有效（方便本地开发）。设置 REQUIRE_API_KEY=1（或 requireApiKey: true）即可拒绝 X-Agent-Id，仅允许使用有效密钥进行身份验证。通过 APIKEYS_FILE=./keys.sqlite，可让密钥在重启后保留。

支付通道

通道实现同一个接口（src/rails/rail.ts）：supports(network) + pay(ctx) -> receipt。添加通道无需改动策略、外汇或路由代码。内置通道：

• MockRail — 在进程内即时结算；可实例化多个，用于模拟多通道部署。
• X402Rail — Coinbase 的 x402 协议适配器，带有真正的客户端支付实现：createEip3009Signer 会为 Base / Base Sepolia 上的 USDC 生成已签名的 EIP-3009 transferWithAuthorization 载荷。兼容 x402 v1 和 v2：v1（X-PAYMENT、请求正文要求）和 v2（PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE 标头、eip155:84532 等 CAIP-2 网络、原子单位 amount，以及原样回显所选要求的 accepted）。对于仅支持 Permit2 的要求会直接拒绝，而不会错误签名。签名完全离线完成；商家的 facilitator 会在链上结算。已通过两种方式验证：测试套件会以密码学方式校验签名，并且该通道已在 Base Sepolia 上端到端结算一笔真实支付（见下文）。
• AlipayActRail — 面向支付宝 Agent 支付技术栈（ACT 委托模型下的 AI付）设计的适配器；通过 executePayment 接入商家集成。

凭据保存在你提供的通道回调中——网关核心不会接触密钥。计划支持：Google AP2。

在 Base Sepolia 上购买真实的 x402 资源

这已实际运行过：网关通过 Coinbase 托管的测试网 facilitator，在 Base Sepolia 上结算了 0.01 USDC；钱包中的 ETH 余额为零（由 facilitator 支付 Gas——对付款方而言，x402 无 Gas 费）。链上凭证：0x3108b5…54ff9d（x402 v1）。随后，x402 v2 也以相同方式通过 Coinbase 官方的 @x402/express 2.27 商家完成结算：0x8c0256…f668c5。

复现步骤——公共测试网端点时有时无，因此可靠的方式是运行本地 x402 商家：

# 1. fund a throwaway wallet with testnet USDC: https://faucet.circle.com (Base Sepolia)

# 2. run a local x402 merchant settling on base-sepolia (official middleware + hosted facilitator)
mkdir x402-merchant && cd x402-merchant && npm init -y && npm i x402-express express
cat > server.mjs <<'JS'
import express from "express";
import { paymentMiddleware } from "x402-express";
const app = express();
app.use(paymentMiddleware("0xYourMerchantAddress", {       // any address — it just receives the USDC
  "/premium": { price: "$0.01", network: "base-sepolia", config: { description: "x402 test" } },
}));
app.get("/premium", (_q, r) => r.json({ message: "unlocked by a real on-chain payment" }));
app.listen(4021, () => console.log("merchant on http://localhost:4021/premium"));
JS
node server.mjs

# 3. buy it through the gateway (signs EIP-3009 offline, facilitator settles on-chain)
X402_PRIVATE_KEY=0x... TARGET_URL=http://localhost:4021/premium npx tsx demo/x402-live.ts

或者将 TARGET_URL 指向任意可在 base-sepolia 上完成结算的在线 x402 资源。

安全

涉及资金，因此我们加固了控制平面，而不只是计算逻辑：

• 管理 API 身份验证 — 设置 ADMIN_TOKEN 后，每个 /admin/* 数据或变更端点都需要提供该令牌（通过 Authorization: Bearer 或 X-Admin-Token，并使用恒定时间比较）。如果未设置，管理 API 将开放，因此 CLI 默认绑定到 127.0.0.1（可通过 HOST 覆盖），并在启动时发出警告。仪表板会携带令牌（通过 /admin#token=… 初始化一次）。
• SSRF 防护 — 默认情况下，/proxy 会拒绝解析到私有、环回或链路本地网段的目标（包括云元数据 IP 169.254.169.254）。防护机制会在连接时通过固定 DNS 查询运行，并应用于每一次重定向跳转，因此 DNS 重绑定或重定向到内网都无法绕过防护。仅在本地测试时才通过 allowPrivateTargets 启用此功能。
• x402 资产允许列表 — 签名器拒绝为不在各网络允许列表中的代币签署 EIP-3009 授权（默认仅允许规范的 USDC），因此恶意的 402 无法诱使钱包授权转移其他价值更高的代币。授权有效期会被限制（maxAuthorizationSeconds）。
• 并发时防止双重支付 — 按 Agent 串行处理决策→执行→记录流程，因此并发付款不会在任一笔付款记录之前同时通过预算检查。
• DoS 限制 — 请求体上限为 1 MiB（413），上游获取超时时间为 30 s，并且上游响应采用流式传输（不会整体缓冲到内存中）。
• 资金完整性 — 使用精确的 bigint 算术（不使用浮点数），API 密钥仅以 SHA-256 哈希形式存储（原始密钥只显示一次），并且绝不转发上游的 Authorization 标头。

部署检查清单： 设置 ADMIN_TOKEN，启用 REQUIRE_API_KEY=1，保持 allowPrivateTargets 关闭，并将网关部署在 TLS 后方。完整的威胁模型、加固清单和检查清单请参阅 docs/SECURITY.md。

状态与路线图

这是一个 MVP。策略引擎、汇率层、跨支付轨道路由器、账本、审计日志、审批、持久化和 402 代理流程均已通过测试，并且已针对模拟支付轨道完成端到端验证；x402 支付轨道已在 Base Sepolia 上完成一笔真实付款。首次发布后已完成：

• 带缓存和过期限制的实时汇率提供程序（CachingRateProvider）
• 超越 JSONL 的持久化存储 — 通过 node:sqlite 实现事务型 SQLite
• 人工介入审批（“金额超过 $X 的付款需暂缓并审核”）
• 用于支出、审计、审批和策略编辑的 Web 仪表板（GET /admin）
• 策略热重载和用于编辑策略的管理 API
• 多租户 API 密钥管理（哈希密钥、创建/撤销、每个密钥的有效期）
• 针对官方 v2 商家的端到端 x402 v2 结算 — Base Sepolia 上的 0.01 USDC
• 通过在线 facilitator 完成端到端 x402 结算 — 已在 Base Sepolia 上结算 0.01 USDC（复现方法：见上文）

尚未实现：

• 真实的 Alipay AI付/ACT 结算（需要商户入驻）