# forum-labs/payfetch [Health: Active] **Category:** 💰 Finance & Fintech **Repository:** https://github.com/forum-labs/payfetch **GitHub Stars:** 0 **npm Downloads (last month):** 189 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/forum-labs-payfetch ## Description Non-custodial paying-fetch client for agents that pay APIs over HTTP 402 (x402, USDC on Base). The operator sets hard per-call/per-day/per-host spend caps, an approval threshold, and allow/deny lists, with an append-only receipt for every attempt; the agent can't raise its own limits. npx -y -p @forum-labs/payfetch payfetch-mcp ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "payfetch": { "command": "npx", "args": ["-y","@forum-labs/payfetch"], "env": { "PAYFETCH_PRIVATE_KEY": "", "PAYFETCH_KEY_FILE": "", "PAYFETCH_CDP_API_KEY_ID": "", "PAYFETCH_CDP_API_KEY_SECRET": "", "PAYFETCH_CDP_WALLET_SECRET": "", "PAYFETCH_CDP_ACCOUNT_NAME": "", "PAYFETCH_TEST_MODE": "" } } } ``` **Requires environment variables:** `PAYFETCH_PRIVATE_KEY`, `PAYFETCH_KEY_FILE`, `PAYFETCH_CDP_API_KEY_ID`, `PAYFETCH_CDP_API_KEY_SECRET`, `PAYFETCH_CDP_WALLET_SECRET`, `PAYFETCH_CDP_ACCOUNT_NAME`, `PAYFETCH_TEST_MODE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README # payfetch [![smithery badge](https://smithery.ai/badge/forum-labs/payfetch)](https://smithery.ai/servers/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`: ```bash # 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 ``` 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: ```bash export PAYFETCH_PRIVATE_KEY=0xabc... ``` Key file, which must be mode 600 (payfetch refuses to start otherwise): ```bash printf '0xabc...' > ~/.payfetch-wallet.key && chmod 600 ~/.payfetch-wallet.key export PAYFETCH_KEY_FILE=~/.payfetch-wallet.key ``` Coinbase CDP server wallet, where the keys are managed by CDP under your account instead of being pasted into an environment variable: ```bash 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. Wire it into an MCP client Claude Desktop, in `claude_desktop_config.json`: ```json { "mcpServers": { "payfetch": { "command": "npx", "args": ["-y", "-p", "@forum-labs/payfetch", "payfetch-mcp"], "env": { "PAYFETCH_PRIVATE_KEY": "0xabc...", "PAYFETCH_TEST_MODE": "1" } } } } ``` Claude Code: ```bash claude mcp add payfetch \ --env PAYFETCH_PRIVATE_KEY=0xabc... \ --env PAYFETCH_TEST_MODE=1 \ -- npx -y -p @forum-labs/payfetch payfetch-mcp ``` 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: ```json { "url": "https://api.example.com/paid-endpoint" } ``` 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`: ```json { "url": "https://api.example.com/paid-endpoint", "maxAmountUsd": 0.25 } ``` `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 already bounds lifetime spend on-chain (see Security), so a software lifetime ceiling would be one more field to forget. Set `totalUsd` only if you want a software ceiling on top of a larger-balance wallet. ### Allow and deny lists `mode` is `open` by default. Set it to `allowlist` to pay only hosts listed in `allow`. Patterns in `deny` are always refused and win over `allow`. A pattern like `*.example.com` matches subdomains, not the apex. ### Approvals A payment whose price is strictly above `approval.thresholdUsd` (default 0.10) triggers approval. An approval authorizes one payment only. There is no "always allow", and it never widens future authority. - `elicit` (default): the client prompts a human with the host, resource, amount, network and asset, guard results, and today's remaining budgets. They approve once or deny. The prompt times out after 120 seconds and is then treated as a denial. Some MCP clients cannot service an elicitation prompt: as of Claude Code v2.1.198 and current Claude Desktop, neither does (Claude Code does not advertise the elicitation capability; Claude Desktop advertises it but cancels the prompt immediately). When a client adds elicitation support, the prompt works with no payfetch change. payfetch tells apart a real human "deny" from a client that simply cannot ask, and it never treats "cannot ask" as a silent denial. When a payment is blocked only because the client cannot elicit, the tool result says so and names the ways to allow it. - `queue`: the payment is not executed. The result returns an `approvalId`. A human with approval authority resolves it with the `approve_pending` tool. An approved entry is a grant to re-run: the follow-up `paid_fetch` runs the full pipeline again and matches on host and exact amount. It expires after one hour, and drifted terms require a fresh approval. - `deny`: anything above the threshold is refused, for unattended fleets. For clients that cannot prompt a human, two config-only settings let above-threshold payments through without a dialog. Both are explicit operator authorization, not the agent's, and neither is reachable from a tool. `approval.preApprovedUpToUsd` (default null) auto-approves above-threshold payments up to a ceiling. `approval.preApprovedHosts` (default empty) auto-approves specific hosts. Both still pass through every cap and every guard. Approval never bypasses caps. An approved payment that fails budget reservation is still denied. `approve_pending` with `{"action":"list"}` is always allowed and shows the queue. Approving or denying an entry requires `PAYFETCH_APPROVER=1` in the server's environment; without it the tool returns `approver_not_enabled`. An agent must not approve its own payments, so the server refuses to start if `PAYFETCH_APPROVER=1` is combined with a queue-capable approval mode. ### Receipts Every outcome, including free fetches, dry runs, denials, and unknown-settlement cases, appends one immutable JSON line to the ledger: ``` {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" ``` A receipt records the URL, method, and host; the outcome and deny code; the pipeline steps traversed; the selected quote and a tally of rejected quotes; guard results; approval info; the payment (payer address, nonce, validBefore, settled amount, transaction reference, and whether it confirmed); the budgets at decision time; and an HTTP summary. Key material, signatures, full payment payloads, response bodies, and request header values are never stored. Response bodies are recorded as a SHA-256 hash plus a byte count. URL query strings are stored, because this is your own audit trail on your own disk; guard calls, by contrast, strip the query (see Security). Nothing is rewritten. Corrections append `p3f.adjust.v1` records. Query receipts with the `list_receipts` tool (filter by time, host, or outcome) or `spend_status` (today's totals, holds, and recent payments). After repeated paid-but-bad outcomes a host is auto-denied for 7 days; clear it out of band with `payfetch clear-autodeny `, never from a tool. ## Trust and safety checks payfetch can consult two checks before it pays. Both call paid Forum Labs APIs at `https://api.forum-labs.com`, and both are self-dealing that is disclosed here rather than buried: the guards call our own products. The default guard budget is 0, so by default the client uses only those products' free tier. Any paid guard usage is opt-in, budgeted with `guards.*.dailyBudgetUsd > 0`, and produces a receipt like any other spend. The trust check is on by default in advisory mode. Before paying, it asks whether the target endpoint has a reliable history. In advisory mode it warns; in enforce mode it blocks on the configured verdicts (`unreliable` by default). New endpoints without enough history come back `unrated` and pass by default, so the check does not strangle them. This check is the client's only outbound call to us; see Security for exactly what it sends and how to turn it off. The safety check is off by default. When enabled it screens a token mint you pass in (`tokenAddress`) against the Forum Labs token safety API and blocks on a `danger` verdict, or on a `serial_rugger` deployer verdict in `deep` mode. `deep` is always a paid screen, so it needs `dailyBudgetUsd > 0`. ## Security and disclosure Read this before pointing payfetch at a funded wallet. ### The wallet balance is your real limit The primary control on how much a bug or a prompt-injected agent can spend is the balance of the wallet you point payfetch at, not the software caps. A wallet's balance is a hard on-chain bound: payfetch cannot spend a dollar that is not in the wallet, whatever the config says or the agent is told to do. So the first thing to get right is the wallet. Create a fresh wallet, fund it with only the amount you are willing to lose entirely (a few dollars for a trial, a capped top-up for production), and give payfetch that wallet. Never your main wallet. Refill it deliberately rather than by standing order. The caps, lists, approval threshold, and guards are the fine-grained layer on top. They shape rate, per-target exposure, and detection within that balance. They are real and enforced, but the wallet balance is the circuit breaker and the caps are the scalpel. Set both. ### Key custody Your key is never transmitted to us, never logged, and never written to the receipt ledger. The ledger stores addresses and amounts, not keys, and that is asserted by a test. Keys are read from the environment in-process to sign EIP-3009 payment authorizations. A signed authorization is bounded to one asset, one amount, one recipient, and one time window. If you use `PAYFETCH_KEY_FILE`, payfetch refuses to start when the file is group- or world-readable, so `chmod 600` it. ### What the trust guard sends, and the off switch While the trust guard is on, it makes one call to the Forum Labs trust API on every paid fetch. That call is the client's only egress to us. It sends the target endpoint with the query string stripped, plus a random per-install id. The query is stripped because a target URL's query can carry your own secrets; server-side we store a hash of the input, never the raw target, and the install id is used for aggregate counting only, never per-install profiling or resale. The install id is a random 32-hex value generated on first run and stored in your state file; delete the state file and it regenerates. Turn the guard off with `guards.trust.enabled: false`. With it off, payfetch makes no external call at all: no guard result, no network request, nothing dialed. That is the complete off switch, and the honest cost of it is that operators who disable the guard are invisible to our adoption instrument. ### Optional outcome reporting (off by default) Reporting is off by default and changes nothing unless you turn it on. When you report an outcome, currently only per-incident with `payfetch report `, the client reports the outcome of a completed payment attempt (paid and delivered, or paid and not delivered), signed by your payment wallet and tied to the on-chain settlement, to the trust API. This is a fact about the seller's conduct that you are reporting. It is never a record of what you looked at. Lookups (guard checks, quotes, dry runs) are never retained per consumer. A report sends exactly these fields and nothing else: the endpoint `{method, url}` with the query stripped; the `outcome`, derived from the receipt and never agent-supplied; structural `checks` (`settlementConfirmed`, a coarse HTTP status class, `contentTypeOk`, `nonEmpty`); the `termsHash` you paid under; the seller's `payTo` address, which is already on-chain; a coarse `amountBand` rather than the exact amount; the UTC day rather than an exact timestamp; and your payment wallet address plus an EIP-712 signature over the payload. A report never carries the query string, request headers or bodies, the response body, the receiptId, the exact amount, or the exact timestamp. The install id never rides on the report path, so the report wallet and the guard install id are never joined. A settled x402 payment is already public (payer, payee, amount, and time are on the chain). What a report adds is the outcome bit. On very-low-traffic endpoints a seller may be able to infer that a report came from you, since the anonymity set is small; we mitigate with day granularity and bucketed publication, and we state the residual here rather than hide it. In this version the trust API verifies the signature (`recover(sig) === payer`), so a stranger cannot report on your behalf, but it does not yet prove the settlement, so reports are shown as unverified until they are settlement-matched in a later version. We will not monetize, publish, or attempt to deanonymize reporter wallets. ### SSRF and private targets Unless you set `allowPrivateTargets: true`, payfetch refuses non-http(s) schemes and any host that resolves to loopback, RFC1918, link-local `169.254/16`, CGNAT, or ULA. A paying-fetch must not become the tool that exfiltrates `169.254.169.254`. DNS is pinned, so the vetted IP is the one dialed; every redirect hop is re-checked; and an `https` to `http` downgrade aborts. ### What payfetch does not protect against Fetched content is untrusted input to your agent. A malicious page can tell the agent to fetch or pay somewhere else. payfetch bounds the damage with the dedicated wallet's balance and the caps, lists, approval threshold, receipts, and SSRF block, but it cannot make the agent wise. It cannot stop an injected agent from spending within policy, so keep the wallet balance small. For untrusted-content workloads, tighten the defaults: ```jsonc { "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` sends every payment to a human. `mode: "enforce"` blocks on an `unreliable` verdict instead of only warning. Two more limits worth stating plainly. There is no on-chain settlement verification yet: settlement facts come from the server's payment-response header, so a lying server can misreport. Both error directions over-count, which is the safe direction, and on-chain verification is planned. And the ledger is single-instance: one lockfile, one process, one machine. A fleet needs a policy plane that is not built here. ## Configuration reference Defaults, from `{dataDir}/config.json`, schema `p3f.policy.v1`: | Field | Default | Meaning | |---|---|---| | `mode` | `"open"` | `"allowlist"` pays only hosts in `allow`. | | `allow` | `[]` | Host patterns permitted in allowlist mode. | | `deny` | `[]` | Host patterns always refused (wins over `allow`). | | `caps.perCallUsd` | `1.00` | Max per single payment. | | `caps.dailyUsd` | `2.00` | Max per UTC day. | | `caps.perHostDailyUsd` | `1.00` | Max per host per UTC day. | | `caps.totalUsd` | `null` | Optional lifetime cap. | | `approval.thresholdUsd` | `0.10` | Above this, approval is required. | | `approval.mode` | `"elicit"` | `elicit`, `queue`, or `deny`. | | `approval.elicitFallback` | `"deny"` | Used when the client cannot elicit. Fail-closed. | | `approval.preApprovedUpToUsd` | `null` | No-dialog ceiling for above-threshold payments. | | `approval.preApprovedHosts` | `[]` | Hosts pre-approved to auto-pay above threshold. | | `guards.trust.enabled` | `true` | The default-on trust check. | | `guards.trust.mode` | `"advisory"` | `advisory` warns; `enforce` blocks. | | `guards.trust.minScore` | `null` | Minimum acceptable TrustScore; below it the guard blocks or warns. `null` uses verdict-based blocking only, and it is ignored when the API returns a null score. | | `guards.trust.blockVerdicts` | `["unreliable"]` | Verdicts that block or warn. | | `guards.trust.blockUnrated` | `false` | `unrated` passes by default. | | `guards.trust.onUnavailable` | `"block"` | Enforce-mode behavior when the guard cannot answer. | | `guards.trust.dailyBudgetUsd` | `0` | 0 means free tier only. | | `guards.safety.enabled` | `false` | Token safety screen; needs `tokenAddress`. | | `guards.safety.mode` | `"enforce"` | `advisory` warns; `enforce` blocks. Applies only when the safety guard is enabled. | | `guards.safety.depth` | `"basic"` | `deep` is always paid. | | `guards.safety.blockVerdicts` | `["danger"]` | Token verdicts that block. | | `guards.safety.blockDeployerVerdicts` | `["serial_rugger"]` | Deployer verdicts, deep only. | | `guards.safety.onUnavailable` | `"block"` | Enforce behavior when the safety guard is dead. | | `guards.safety.onDegraded` | `"block"` | Enforce behavior on a degraded screen. | | `allowPrivateTargets` | `false` | SSRF guard. Keep `false`. | | `autoDeny.enabled` | `true` | Per-host circuit breaker. | Environment variables read by both the server and the CLI: | Variable | Meaning | |---|---| | `PAYFETCH_PRIVATE_KEY` | 0x-hex EVM private key. One of three signer sources. | | `PAYFETCH_KEY_FILE` | Path to a mode-600 file holding a 0x-hex key. | | `PAYFETCH_CDP_API_KEY_ID` / `_SECRET`, `PAYFETCH_CDP_WALLET_SECRET` | Coinbase CDP server-wallet credentials (all three required together). | | `PAYFETCH_CDP_ACCOUNT_NAME` | Optional named CDP EVM account. Defaults to a stable name. | | `PAYFETCH_DATA_DIR` | Ledger, state, and config root. Default `~/.payfetch`. | | `PAYFETCH_TEST_MODE` | Any value marks receipts `test:true` and refuses Base mainnet quotes (Sepolia only). | | `PAYFETCH_APPROVER` | `1` grants approval authority. Refused with a queue-capable mode. | | `PAYFETCH_VIA` | Optional `via=` attribution slug sent on guard calls only. | ## Test mode Set `PAYFETCH_TEST_MODE` to any value. Then every receipt is stamped `test: true` and excluded from metrics, and Base mainnet quotes are refused so a self-test can never touch mainnet spend. Only Base Sepolia settles. Use it to run the end-to-end Base Sepolia path before spending real USDC. ## CLI The `payfetch` CLI reads the same environment as the MCP server. ```bash # 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 ``` `status` builds the engine and takes the single-writer lock. If the MCP server is already running, use the `spend_status` tool instead, or stop the server first. ## Manual .mcpb install Directory submission is not offered for payment connectors, so payfetch is packaged for manual install. Build the bundle: ```bash npm run build:mcpb # produces dist-mcpb/payfetch.mcpb ``` This runs `tsc`, then esbuild-bundles the built server entry and its runtime dependencies into a single self-contained ESM file, and packs it with the mcpb tool. The result is a small `.mcpb` zip holding `manifest.json` alongside the bundled server. No `node_modules` is shipped, so Claude Desktop installs it without running `npm install`. In Claude Desktop, go to Settings, Extensions, Install from file, choose the `.mcpb`, then fill in exactly one signer option. The bundling logic is in `mcpb/build.mjs` and the manifest is `mcpb/manifest.json`. ## From source ```bash 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 ``` ## License MIT. See [LICENSE](https://github.com/forum-labs/payfetch/blob/HEAD/LICENSE). Copyright (c) 2026 Forum Labs.