payfetch

payfetch

payfetch 让 AI Agent 获取 URL，并在服务器返回 HTTP 402（x402 支付协议）时自动付款，但仅限于你控制的支出策略范围内。它采用非托管模式：你使用自己的钱包，密钥保留在你的机器上，任何 MCP 工具都不能提高限额。它以本地 stdio MCP 服务的形式提供，同时附带一个小型库和 CLI。

参考 x402 客户端会按 402 请求的金额付款。payfetch 则恰恰相反：重点在于策略和安全机制。它支持每次调用、每日和每个主机的支出上限；主机允许和拒绝列表；人工审批阈值；可选的付款前信任与安全检查；以及针对每次尝试的本地只追加收据，无论尝试是已付款、被拒绝、试运行还是失败，都会记录。

• 网站：https://forum-labs.com
• 源码：https://github.com/forum-labs/payfetch

状态与范围

• 版本 1.0.0。策略架构 p3f.policy.v1，客户端架构 p3f-1.0.0。
• 仅支持 x402、Base USDC 和 exact 方案。以 Solana 结算的 x402、upto 方案和 MPP 会被解析，然后拒绝，并在收据中记录原因。
• 需要 Node 22 或更高版本。不支持 Windows。
• USD 按 1.00 的汇率视为 USDC。预算以 USD 计价，以 USDC 结算，因此脱锚会使上限按脱锚幅度产生偏差。

安装

此软件包附带编译后的 JavaScript，因此用户无需构建，也无需使用 tsx。使用 npx 按需运行：

# Operator CLI (status, verify, clear-autodeny, report):
npx @forum-labs/payfetch status

# MCP server (what an MCP client launches):
npx -p @forum-labs/payfetch payfetch-mcp

此软件包提供两个可执行文件：payfetch（操作员 CLI）和 payfetch-mcp（stdio MCP 服务）。由于有两个可执行文件，启动服务时请使用 npx -p @forum-labs/payfetch payfetch-mcp；-p 标志用于选择指定的可执行文件。

快速入门

1. 配置钱包（只能选择一个签名者）

如果未设置签名者来源，或设置了多个签名者来源，payfetch 都会拒绝启动。它绝不会猜测要使用哪个钱包付款。

原始私钥是最简单的选项。请使用余额较低的专用钱包：

export PAYFETCH_PRIVATE_KEY=0xabc...

密钥文件必须设置为 mode 600（否则 payfetch 会拒绝启动）：

printf '0xabc...' > ~/.payfetch-wallet.key && chmod 600 ~/.payfetch-wallet.key
export PAYFETCH_KEY_FILE=~/.payfetch-wallet.key

Coinbase CDP 服务端钱包：密钥由你账户下的 CDP 管理，无需粘贴到环境变量中：

export PAYFETCH_CDP_API_KEY_ID=...
export PAYFETCH_CDP_API_KEY_SECRET=...
export PAYFETCH_CDP_WALLET_SECRET=...
export PAYFETCH_CDP_ACCOUNT_NAME=payfetch   # optional; stable name across restarts

2. 将其接入 MCP 客户端

Claude Desktop，在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "payfetch": {
      "command": "npx",
      "args": ["-y", "-p", "@forum-labs/payfetch", "payfetch-mcp"],
      "env": {
        "PAYFETCH_PRIVATE_KEY": "0xabc...",
        "PAYFETCH_TEST_MODE": "1"
      }
    }
  }
}

Claude Code：

claude mcp add payfetch \
  --env PAYFETCH_PRIVATE_KEY=0xabc... \
  --env PAYFETCH_TEST_MODE=1 \
  -- npx -y -p @forum-labs/payfetch payfetch-mcp

示例设置了 PAYFETCH_TEST_MODE=1，因此首次运行会在 Base Sepolia 上结算，绝不会触及主网。准备好使用真实 USDC 付款时，将其移除。

3. 首次付费获取

付款前先查询报价。payment_quote 会返回条款、选中的报价、信任检查结果、剩余预算和策略判定（would_pay 或 would_deny）。它不会签名，也不会预留资金：

{ "url": "https://api.example.com/paid-endpoint" }

试运行整个流程。paid_fetch 配合 "dryRun": true 会运行真实付款所经过的完整代码路径，但不包含签名步骤。

使用 paid_fetch 实际付款：

{ "url": "https://api.example.com/paid-endpoint", "maxAmountUsd": 0.25 }

maxAmountUsd 会收紧本次调用的单次上限。它只能降低限额，不能提高限额。如果价格高于你的审批阈值，则必须先获得审批（参见“审批”）。结果包含响应正文、付款结果和交易引用、任何警告，以及一个 receiptId。

支出策略

策略保存在 {dataDir}/config.json 中（数据目录默认为 ~/.payfetch）。 首次运行时，payfetch 会将默认值写入该文件，方便你查看并编辑实际使用的配置。文件缺失时会回退到默认值。文件无效时会安全拒绝：所有付费工具都会返回 policy_config_invalid，直到你修复文件，因此拼写错误绝不会悄悄恢复你已调低的上限。文件的修改时间发生变化时，会重新读取该文件。

只有你可以更改策略。没有任何 MCP 工具会修改策略，也没有任何工具会清除自动拒绝。Agent 提供的参数（例如 maxAmountUsd）只能收紧策略，不能放宽策略。每个被拒绝的 paid_fetch 结果都会将这一点告知 Agent，避免遭到提示词注入的模型误以为这条界限可以协商。

上限

• caps.perCallUsd（默认值：1.00）：单笔付款的最高金额。
• caps.dailyUsd（默认值：2.00）：每个 UTC 日的最高金额。
• caps.perHostDailyUsd（默认值：1.00）：每个主机每个 UTC 日的最高金额。
• caps.totalUsd（默认值：null）：可选的终身支出上限。

上限是硬性限制，且会在付款前预留额度。已签名的授权会占用预算，直到可以确证其已过期，因此预算可能会多算，但绝不会少算。每个请求最多只会尝试付款一次，因此重试循环无法耗尽钱包。

特意不设置默认的终身支出上限。专用钱包的余额已能在链上限制终身支出（参见 Security），因此软件层的终身上限会多出一个容易被忘记的配置项。只有当你想在余额更大的钱包上再增加软件层上限时，才设置 totalUsd。

允许列表和拒绝列表

mode 默认值为 open。将其设为 allowlist 后，只会向 allow 中列出的主机付款。deny 中的模式始终会被拒绝，且优先于 allow。例如，*.example.com 这样的模式会匹配子域名，但不匹配顶级域名。

审批

价格严格高于 approval.thresholdUsd（默认值为 0.10）的付款会触发审批。一次审批仅授权一笔付款。没有“始终允许”选项，也绝不会扩大未来的授权范围。

• elicit（默认值）：客户端会提示人工审核者，显示主机、资源、金额、网络和资产、保护规则检查结果，以及今日剩余预算。审核者可批准一次或拒绝。提示会在 120 秒后超时，并按拒绝处理。某些 MCP 客户端无法处理征询提示：截至 Claude Code v2.1.198 和当前版本的 Claude Desktop，两者都无法处理（Claude Code 不会声明征询能力；Claude Desktop 会声明该能力，但会立即取消提示）。客户端添加征询支持后，无需更改 payfetch，提示即可正常工作。payfetch 能区分人工真正“拒绝”和客户端根本无法发起询问的情况，绝不会将“无法询问”视为无提示的拒绝。如果付款仅因客户端无法发起征询而被拦截，工具结果会说明原因并列出允许付款的方式。
• queue：不执行付款。结果会返回一个 approvalId。拥有审批权限的人工审核者可使用 approve_pending 工具处理该请求。获批条目允许重新运行：后续的 paid_fetch 会再次运行完整流程，并按主机和精确金额进行匹配。该条目在一小时后过期；条款发生变化时，必须重新审批。
• deny：拒绝任何超过阈值的付款，适用于无人值守的部署环境。

对于无法提示人工审核者的客户端，有两个仅通过配置设置的选项，可在无需弹窗的情况下放行超过阈值的付款。这两项都是由操作员明确授权，而非由 Agent 授权，且都无法通过工具触发。approval.preApprovedUpToUsd（默认值为 null）会自动批准不超过指定上限的超阈值付款。 approval.preApprovedHosts（默认值为空）会自动批准指定主机的付款。所有这些付款仍须通过每一项限额和保护规则检查。

审批绝不会绕过限额。即使付款已获批准，只要预算预留失败，仍会被拒绝。

始终允许使用 {"action":"list"} 调用 approve_pending，以查看队列。批准或拒绝条目需要在服务器环境中设置 PAYFETCH_APPROVER=1；否则工具会返回 approver_not_enabled。Agent 不得批准自己的付款，因此如果队列审批模式可用，同时设置 PAYFETCH_APPROVER=1，服务器将拒绝启动。

收据

每种结果（包括免费获取、试运行、拒绝和结算状态未知的情况）都会向账本追加一行不可变的 JSON 记录：

{dataDir}/ledger/{yyyy-mm}.jsonl   # append-only, monthly rotation, fsync on payments
{dataDir}/state.json               # disposable cache, rebuildable from the ledger
{dataDir}/downloads/{receiptId}    # response bodies when responseMode is "file"

收据会记录 URL、方法和主机；结果和拒绝代码；经过的流程步骤；选中的报价及被拒报价的汇总；保护规则检查结果；审批信息；付款信息（付款方地址、nonce、validBefore、结算金额、交易引用，以及付款是否已确认）；决策时的预算；以及 HTTP 摘要。不会存储密钥材料、签名、完整付款负载、响应正文或请求头的值。响应正文会以 SHA-256 哈希和字节数的形式记录。由于这是你在自己磁盘上的审计记录，因此会存储 URL 查询字符串；相比之下，保护规则调用会移除查询字符串（参见“安全”）。记录不会被改写。更正操作会追加 p3f.adjust.v1 记录。

使用 list_receipts 工具查询收据（可按时间、主机或结果筛选），或使用 spend_status 查询今日总额、预留金额和近期付款。某个主机多次出现“已付款但结果不佳”的情况后，会被自动拒绝 7 天；请在工具之外使用 payfetch clear-autodeny <host> 清除该状态，切勿通过工具清除。

信任与安全检查

payfetch 可以在付款前执行两项检查。两项检查都会调用 https://api.forum-labs.com 上需要付费的 Forum Labs API；我们在此公开说明这项利益 关系，而不是将其隐瞒：这些防护措施调用的是我们自己的产品。默认防护预算为 0，因此 默认情况下，客户端只使用这些产品的免费层级。任何付费防护用量都必须主动选择启用， 通过 guards.*.dailyBudgetUsd > 0 设置预算，并且会像其他支出一样生成收据。

信任检查默认以建议模式启用。付款前，它会检查目标端点是否有可靠的历史记录。在建议 模式下，它会发出警告；在强制模式下，遇到已配置的判定结果时会阻止付款（默认为 unreliable）。历史记录不足的新端点会被判定为 unrated，默认情况下会通过，因此这项 检查不会阻碍它们。此检查是客户端唯一一次向我们发出的出站调用；关于它具体发送的内容 以及如何关闭，请参阅“安全”。

安全检查默认关闭。启用后，它会将你提供的代币铸造地址（tokenAddress）提交给 Forum Labs 代币安全 API 进行筛查，并在判定结果为 danger 时阻止付款；在 deep 模式下， 如果部署者的判定结果为 serial_rugger，也会阻止付款。deep 始终属于付费筛查，因此 需要设置 dailyBudgetUsd > 0。

安全与披露

在将 payfetch 指向有资金的钱包之前，请阅读本节。

钱包余额才是你的实际限额

限制漏洞或受到提示词注入的 Agent 能花费多少资金的首要因素，是你指定给 payfetch 的 钱包余额，而不是软件限额。钱包余额是链上硬性限制：无论配置如何设置，也无论 Agent 收到什么指示，payfetch 都无法花费钱包里没有的资金。因此，首先要做对的就是钱包设置。

创建一个新钱包，只存入你愿意全部损失的金额（试用时存入几美元，生产环境中则进行有 上限的充值），然后将该钱包交给 payfetch 使用。切勿使用你的主钱包。应有意地手动充值， 而不是设置定期转账。

限额、列表、审批阈值和防护措施是在此基础上的细粒度控制层。它们会在钱包余额范围内 调整频率、单个目标的风险敞口和检测能力。这些控制真实有效且会强制执行，但钱包余额 是断路器，限额则是手术刀。两者都要设置。

密钥托管

你的密钥绝不会传输给我们、记录到日志中，也不会写入收据账本。账本仅存储地址和金额， 不存储密钥，这一点已通过测试验证。密钥会在进程内从环境变量读取，用于签署 EIP-3009 付款授权。签名授权限定为单个资产、单笔金额、单个收款方和单个有效时间窗口。如果使用 PAYFETCH_KEY_FILE，当文件对组用户或其他用户可读时，payfetch 会拒绝启动，因此请对 该文件执行 chmod 600。

信任防护会发送哪些内容，以及如何关闭

信任防护启用期间，每次付费获取时都会调用一次 Forum Labs 信任 API。这是客户端唯一 向我们发送数据的出口。它会发送去除查询字符串后的目标端点，以及一个随机生成的单次 安装 ID。之所以去除查询字符串，是因为目标 URL 的查询参数可能包含你自己的机密信息； 在服务器端，我们只存储输入的哈希值，绝不存储原始目标；安装 ID 仅用于汇总计数，绝不 用于单次安装的画像分析或转售。安装 ID 是首次运行时生成并存储在状态文件中的随机 32 位十六进制值；删除状态文件后会重新生成。

使用 guards.trust.enabled: false 关闭防护。关闭后，payfetch 不会进行任何外部调用： 没有防护结果，没有网络请求，也不会建立任何连接。这就是完整的关闭开关；关闭防护的 实际代价是，相关使用情况将不会被我们的采用情况统计工具记录。

可选的结果报告（默认关闭）

结果报告默认关闭，除非你主动开启，否则不会有任何变化。报告结果时，目前只能逐笔报告，使用 payfetch report <receiptId>。客户端会将已完成的付款尝试结果（已付款且已交付，或已付款但未交付）报告给信任 API；报告由你的付款钱包签名，并与链上结算关联。这是你对卖家行为所作的报告，绝不是你查看过什么的记录。查询（防护检查、报价、试运行）绝不会按消费者保留记录。

报告只会发送以下字段，不会发送其他内容：去除查询参数后的端点 {method, url}；根据收据得出的 outcome，绝非由 Agent 提供；结构化的 checks（settlementConfirmed、粗略的 HTTP 状态类别、contentTypeOk、nonEmpty）；你付款所依据的 termsHash；卖家的 payTo 地址，该地址本来就在链上；粗略的 amountBand，而非确切金额；UTC 日期，而非确切时间戳；以及你的付款钱包地址和针对该负载的 EIP-712 签名。报告绝不会包含查询字符串、请求标头或请求正文、响应正文、receiptId、确切金额或确切时间戳。安装 ID 不会通过报告路径传输，因此报告钱包与防护安装 ID 永远不会关联起来。

已结算的 x402 付款本来就是公开的（付款方、收款方、金额和时间都记录在链上）。报告新增的是结果标记。对于流量极低的端点，卖家可能推断报告来自你，因为匿名集合很小；我们通过采用按天粒度和分桶发布来降低这种风险，并在此说明剩余风险，而非将其隐瞒。在此版本中，信任 API 会验证签名（recover(sig) === payer），因此陌生人不能代你报告；但它尚未验证结算，因此在后续版本将报告与结算匹配之前，报告会显示为未经验证。我们不会将报告者钱包用于盈利、公开或尝试去匿名化。

SSRF 和私有目标

除非设置 allowPrivateTargets: true，否则 payfetch 会拒绝非 http(s) 协议，以及任何解析到回环地址、RFC1918、链路本地地址 169.254/16、CGNAT 或 ULA 的主机。付费抓取绝不能变成窃取 169.254.169.254 信息的工具。DNS 会被固定，因此实际拨号连接的 IP 就是经过验证的 IP；每次重定向都会重新检查；从 https 降级到 http 会中止请求。

payfetch 无法防护的情况

抓取的内容对你的 Agent 来说是不可信输入。恶意页面可能会指示 Agent 去其他地方抓取内容或付款。payfetch 通过专用钱包的余额以及限额、名单、审批阈值、收据和 SSRF 拦截来限制损失，但无法让 Agent 变得明智。它无法阻止遭到指令注入的 Agent 在策略范围内花费资金，因此请保持钱包余额较低。对于处理不可信内容的工作负载，请收紧默认设置：

{
  "mode": "allowlist",
  "allow": ["api.trusted-vendor.com"],
  "caps": { "perCallUsd": 0.05, "dailyUsd": 0.50, "perHostDailyUsd": 0.25 },
  "approval": { "thresholdUsd": 0.0, "mode": "elicit", "elicitFallback": "deny" },
  "guards": { "trust": { "enabled": true, "mode": "enforce" } }
}

thresholdUsd: 0.0 会将每笔付款都交由人工处理。mode: "enforce" 会在判定为 unreliable 时阻止操作，而不只是发出警告。

还有两项限制值得明确说明。目前尚无链上结算验证：结算事实来自服务端的付款响应标头，因此说谎的服务端可以谎报。两种错误方向都会导致高估，这是较安全的方向；链上验证已列入计划。此外，账本仅支持单实例：一个锁文件、一个进程、一台机器。集群需要一个此处尚未构建的策略控制平面。

配置参考

默认值来自 {dataDir}/config.json，架构为 p3f.policy.v1：

字段	默认值	含义
mode	"open"	"allowlist" 仅向 allow 中的主机付款。
allow	[]	允许列表模式下许可的主机模式。
deny	[]	始终拒绝的主机模式（优先于 allow）。
caps.perCallUsd	1.00	单笔付款的最高金额。
caps.dailyUsd	2.00	每个 UTC 日的最高金额。
caps.perHostDailyUsd	1.00	每个 UTC 日对每台主机的最高金额。
caps.totalUsd	null	可选的终身限额。
approval.thresholdUsd	0.10	超过此金额时需要审批。
approval.mode	"elicit"	elicit、queue 或 deny。
approval.elicitFallback	"deny"	客户端无法请求审批时使用。默认拒绝。
approval.preApprovedUpToUsd	null	超过阈值的付款无需弹窗审批的金额上限。
approval.preApprovedHosts	[]	预先批准可自动支付超过阈值款项的主机。
guards.trust.enabled	true	默认启用的信任检查。
guards.trust.mode	"advisory"	advisory 会发出警告；enforce 会阻止。
guards.trust.minScore	null	可接受的最低 TrustScore；低于此分数时，防护机制会阻止或发出警告。null 表示仅根据判定结果阻止；如果 API 返回的分数为 null，则忽略此项。
guards.trust.blockVerdicts	["unreliable"]	会触发阻止或警告的判定结果。
guards.trust.blockUnrated	false	默认允许 unrated。
guards.trust.onUnavailable	"block"	防护机制无法响应时，强制模式下的处理方式。
guards.trust.dailyBudgetUsd	0	0 表示仅使用免费层级。
guards.safety.enabled	false	代币安全筛查；需要 tokenAddress。
guards.safety.mode	"enforce"	advisory 会发出警告；enforce 会阻止。仅在启用安全防护机制时生效。
guards.safety.depth	"basic"	deep 始终需要付费。
guards.safety.blockVerdicts	["danger"]	会触发阻止的代币判定结果。
guards.safety.blockDeployerVerdicts	["serial_rugger"]	部署者判定结果，仅适用于深度检查。
guards.safety.onUnavailable	"block"	安全防护机制不可用时，强制模式下的处理方式。
guards.safety.onDegraded	"block"	筛查降级时，强制模式下的处理方式。
allowPrivateTargets	false	SSRF 防护。请保持为 false。
autoDeny.enabled	true	针对每台主机的断路器。

服务器和 CLI 均会读取的环境变量：

变量	含义
PAYFETCH_PRIVATE_KEY	0x-hex 格式的 EVM 私钥。三种签名者来源之一。
PAYFETCH_KEY_FILE	存有 0x-hex 密钥的 600 权限文件路径。
PAYFETCH_CDP_API_KEY_ID / _SECRET、PAYFETCH_CDP_WALLET_SECRET	Coinbase CDP 服务端钱包凭据（三项必须同时提供）。
PAYFETCH_CDP_ACCOUNT_NAME	可选的命名 CDP EVM 账户。默认使用稳定名称。
PAYFETCH_DATA_DIR	账本、状态和配置的根目录。默认为 ~/.payfetch。
PAYFETCH_TEST_MODE	设置为任意值后，收据会标记为 test:true，并拒绝 Base 主网报价（仅限 Sepolia）。
PAYFETCH_APPROVER	1 表示授予审批权限。启用支持队列的模式时会拒绝此设置。
PAYFETCH_VIA	可选的 via= 归因标识，仅随防护调用发送。

测试模式

将 PAYFETCH_TEST_MODE 设置为任意值。此后，每张收据都会标记为 test: true， 并从指标中排除；同时会拒绝 Base 主网报价，确保自检绝不会产生主网支出。仅在 Base Sepolia 上结算。 可在支付真实 USDC 前，用此模式运行 Base Sepolia 端到端流程。

CLI

payfetch CLI 使用与 MCP 服务相同的环境变量。

# Reset a host's auto-deny circuit breaker (an operator action, not a tool).
npx @forum-labs/payfetch clear-autodeny api.example.com

# Print today's spend status as JSON.
npx @forum-labs/payfetch status

# Verify the ledger tamper-evidence sidecar (exits non-zero on any integrity gap).
npx @forum-labs/payfetch verify

# Report a paid outcome for a receipt (opt-in, off by default). Prints the exact
# wallet-signed payload, asks for confirmation, then submits. Never an MCP tool, so
# the agent can neither file nor suppress a report. Use --yes to skip the prompt.
npx @forum-labs/payfetch report <receiptId>

status 会构建引擎并获取单写入者锁。如果 MCP 服务已在运行，请改用 spend_status 工具，或先停止服务。

手动安装 .mcpb

目录不接受付款连接器，因此 payfetch 采用手动安装包的形式。构建安装包：

npm run build:mcpb        # produces dist-mcpb/payfetch.mcpb

此命令会运行 tsc，然后使用 esbuild 将构建后的服务入口及其运行时依赖打包为一个独立的 ESM 文件，再使用 mcpb 工具将其打包。生成的 .mcpb zip 文件很小，包含 manifest.json 和打包后的服务。不包含 node_modules，因此 Claude Desktop 安装时无需运行 npm install。在 Claude Desktop 中，前往 Settings，选择 Extensions、Install from file，选中 .mcpb 文件，然后准确填写一个签名选项。打包逻辑位于 mcpb/build.mjs，清单文件为 mcpb/manifest.json。

从源代码安装

npm install         # dev dependencies, including tsx for the from-source flow
npm run typecheck   # tsc --noEmit
npm test            # vitest, hermetic, no network
npm run build       # emit dist/, the compiled JS the package ships

许可证

MIT。请参阅 LICENSE。版权所有 (c) 2026 Forum Labs。