forum-labs/payfetch

payfetch lets an AI agent fetch a URL and, when the server answers HTTP 402 (the
x402 payment protocol), pay for it automatically, but only within a spending policy
you control. It is non-custodial: you bring your own wallet, the key stays on your
machine, and no MCP tool can raise the limits. It ships as a local stdio MCP server
with a small library and CLI alongside it.
The reference x402 clients pay whatever a 402 asks for. payfetch is the opposite:
the policy and safety surface is the point. Per-call, per-day, and per-host spend
caps; host allow and deny lists; a human-approval threshold; optional pre-payment
trust and safety checks; and an append-only local receipt for every attempt,
whether it paid, was denied, was a dry run, or failed.
- Website: https://forum-labs.com
- Source: https://github.com/forum-labs/payfetch
Status and scope
- Version 1.0.0. Policy schema p3f.policy.v1, client schema p3f-1.0.0.
- x402 only, Base USDC, the exact scheme. Solana-settled x402, the upto scheme,
and MPP are parsed and then refused with a reason recorded in your receipts.
- Requires Node 22 or newer. Windows is not supported.
- USD is treated as USDC at 1.00. Budgets are denominated in USD and settle in USDC,
so a depeg makes the caps wrong by the depeg factor.
Install
The package ships compiled JavaScript, so there is no build step and no tsx for
consumers. Run it on demand with npx:
The package exposes two binaries: payfetch (the operator CLI) and payfetch-mcp
(the stdio MCP server). Because there are two, the server is launched with
npx -p @forum-labs/payfetch payfetch-mcp; the -p flag selects the named binary.
Quickstart
1. Configure a wallet (pick exactly one signer)
payfetch refuses to start if zero or more than one signer source is set. It never
guesses which wallet to spend from.
Raw private key, the simplest option. Use a dedicated low-balance wallet:
Key file, which must be mode 600 (payfetch refuses to start otherwise):
Coinbase CDP server wallet, where the keys are managed by CDP under your account
instead of being pasted into an environment variable:
2. Wire it into an MCP client
Claude Desktop, in claude_desktop_config.json:
Claude Code:
The examples set PAYFETCH_TEST_MODE=1 so your first runs settle on Base Sepolia
and never touch mainnet. Drop it when you are ready to spend real USDC.
3. First paid fetch
Quote before you pay. payment_quote returns the terms, the selected quote, the
trust-check result, your remaining budgets, and the policy decision (would_pay or
would_deny). It signs nothing and reserves nothing:
Dry run the whole pipeline. paid_fetch with "dryRun": true runs the exact code
path a real payment takes, up to but not including the signature.
Pay for real with paid_fetch:
maxAmountUsd tightens the per-call cap for this one call. It can only lower the
limit, never raise it. If the price is above your approval threshold, approval is
required first (see Approvals). The result carries the response body, the payment
outcome and transaction reference, any warnings, and a receiptId.
The spending policy
Policy lives in {dataDir}/config.json (the data dir defaults to ~/.payfetch).
On first run payfetch writes the defaults there so you can read and edit exactly
what you are running. A missing file falls back to the defaults. An invalid file
fails closed: every paying tool returns policy_config_invalid until you fix it, so
a typo never silently restores a cap you lowered. The file is re-read when its mtime
changes.
Only you can change the policy. No MCP tool mutates it and no tool clears an
auto-deny. Agent-supplied parameters such as maxAmountUsd can only tighten, never
loosen. Every denied paid_fetch result repeats this back to the agent so a
prompt-injected model cannot mistake the boundary for something negotiable.
Caps
- caps.perCallUsd (default 1.00): maximum for a single payment.
- caps.dailyUsd (default 2.00): maximum per UTC day.
- caps.perHostDailyUsd (default 1.00): maximum per host per UTC day.
- caps.totalUsd (default null): optional lifetime cap.
Caps are hard and reserve before paying. A signed authorization is held against the
budget until it provably expires, so budgets can over-count but never under-count.
At most one payment attempt happens per request, so a retry loop cannot drain the
wallet.
There is deliberately no default lifetime cap. The dedicated wallet's balance