{
  "markdown": "# payfetch\n\n[![smithery badge](https://smithery.ai/badge/forum-labs/payfetch)](https://smithery.ai/servers/forum-labs/payfetch)\n\npayfetch lets an AI agent fetch a URL and, when the server answers HTTP 402 (the\nx402 payment protocol), pay for it automatically, but only within a spending policy\nyou control. It is non-custodial: you bring your own wallet, the key stays on your\nmachine, and no MCP tool can raise the limits. It ships as a local stdio MCP server\nwith a small library and CLI alongside it.\n\nThe reference x402 clients pay whatever a 402 asks for. payfetch is the opposite:\nthe policy and safety surface is the point. Per-call, per-day, and per-host spend\ncaps; host allow and deny lists; a human-approval threshold; optional pre-payment\ntrust and safety checks; and an append-only local receipt for every attempt,\nwhether it paid, was denied, was a dry run, or failed.\n\n- Website: https://forum-labs.com\n- Source: https://github.com/forum-labs/payfetch\n\n## Status and scope\n\n- Version 1.0.0. Policy schema `p3f.policy.v1`, client schema `p3f-1.0.0`.\n- x402 only, Base USDC, the `exact` scheme. Solana-settled x402, the `upto` scheme,\n  and MPP are parsed and then refused with a reason recorded in your receipts.\n- Requires Node 22 or newer. Windows is not supported.\n- USD is treated as USDC at 1.00. Budgets are denominated in USD and settle in USDC,\n  so a depeg makes the caps wrong by the depeg factor.\n\n## Install\n\nThe package ships compiled JavaScript, so there is no build step and no `tsx` for\nconsumers. Run it on demand with `npx`:\n\n```bash\n# Operator CLI (status, verify, clear-autodeny, report):\nnpx @forum-labs/payfetch status\n\n# MCP server (what an MCP client launches):\nnpx -p @forum-labs/payfetch payfetch-mcp\n```\n\nThe package exposes two binaries: `payfetch` (the operator CLI) and `payfetch-mcp`\n(the stdio MCP server). Because there are two, the server is launched with\n`npx -p @forum-labs/payfetch payfetch-mcp`; the `-p` flag selects the named binary.\n\n## Quickstart\n\n### 1. Configure a wallet (pick exactly one signer)\n\npayfetch refuses to start if zero or more than one signer source is set. It never\nguesses which wallet to spend from.\n\nRaw private key, the simplest option. Use a dedicated low-balance wallet:\n\n```bash\nexport PAYFETCH_PRIVATE_KEY=0xabc...\n```\n\nKey file, which must be mode 600 (payfetch refuses to start otherwise):\n\n```bash\nprintf '0xabc...' > ~/.payfetch-wallet.key && chmod 600 ~/.payfetch-wallet.key\nexport PAYFETCH_KEY_FILE=~/.payfetch-wallet.key\n```\n\nCoinbase CDP server wallet, where the keys are managed by CDP under your account\ninstead of being pasted into an environment variable:\n\n```bash\nexport PAYFETCH_CDP_API_KEY_ID=...\nexport PAYFETCH_CDP_API_KEY_SECRET=...\nexport PAYFETCH_CDP_WALLET_SECRET=...\nexport PAYFETCH_CDP_ACCOUNT_NAME=payfetch   # optional; stable name across restarts\n```\n\n### 2. Wire it into an MCP client\n\nClaude Desktop, in `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"payfetch\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@forum-labs/payfetch\", \"payfetch-mcp\"],\n      \"env\": {\n        \"PAYFETCH_PRIVATE_KEY\": \"0xabc...\",\n        \"PAYFETCH_TEST_MODE\": \"1\"\n      }\n    }\n  }\n}\n```\n\nClaude Code:\n\n```bash\nclaude mcp add payfetch \\\n  --env PAYFETCH_PRIVATE_KEY=0xabc... \\\n  --env PAYFETCH_TEST_MODE=1 \\\n  -- npx -y -p @forum-labs/payfetch payfetch-mcp\n```\n\nThe examples set `PAYFETCH_TEST_MODE=1` so your first runs settle on Base Sepolia\nand never touch mainnet. Drop it when you are ready to spend real USDC.\n\n### 3. First paid fetch\n\nQuote before you pay. `payment_quote` returns the terms, the selected quote, the\ntrust-check result, your remaining budgets, and the policy decision (`would_pay` or\n`would_deny`). It signs nothing and reserves nothing:\n\n```json\n{ \"url\": \"https://api.example.com/paid-endpoint\" }\n```\n\nDry run the whole pipeline. `paid_fetch` with `\"dryRun\": true` runs the exact code\npath a real payment takes, up to but not including the signature.\n\nPay for real with `paid_fetch`:\n\n```json\n{ \"url\": \"https://api.example.com/paid-endpoint\", \"maxAmountUsd\": 0.25 }\n```\n\n`maxAmountUsd` tightens the per-call cap for this one call. It can only lower the\nlimit, never raise it. If the price is above your approval threshold, approval is\nrequired first (see Approvals). The result carries the response body, the payment\noutcome and transaction reference, any warnings, and a `receiptId`.\n\n## The spending policy\n\nPolicy lives in `{dataDir}/config.json` (the data dir defaults to `~/.payfetch`).\nOn first run payfetch writes the defaults there so you can read and edit exactly\nwhat you are running. A missing file falls back to the defaults. An invalid file\nfails closed: every paying tool returns `policy_config_invalid` until you fix it, so\na typo never silently restores a cap you lowered. The file is re-read when its mtime\nchanges.\n\nOnly you can change the policy. No MCP tool mutates it and no tool clears an\nauto-deny. Agent-supplied parameters such as `maxAmountUsd` can only tighten, never\nloosen. Every denied `paid_fetch` result repeats this back to the agent so a\nprompt-injected model cannot mistake the boundary for something negotiable.\n\n### Caps\n\n- `caps.perCallUsd` (default 1.00): maximum for a single payment.\n- `caps.dailyUsd` (default 2.00): maximum per UTC day.\n- `caps.perHostDailyUsd` (default 1.00): maximum per host per UTC day.\n- `caps.totalUsd` (default null): optional lifetime cap.\n\nCaps are hard and reserve before paying. A signed authorization is held against the\nbudget until it provably expires, so budgets can over-count but never under-count.\nAt most one payment attempt happens per request, so a retry loop cannot drain the\nwallet.\n\nThere is deliberately no default lifetime cap. The dedicated wallet's balance\nalready bounds lifetime spend on-chain (see Security), so a software lifetime ceiling\nwould be one more field to forget. Set `totalUsd` only if you want a software\nceiling on top of a larger-balance wallet.\n\n### Allow and deny lists\n\n`mode` is `open` by default. Set it to `allowlist` to pay only hosts listed in\n`allow`. Patterns in `deny` are always refused and win over `allow`. A pattern like\n`*.example.com` matches subdomains, not the apex.\n\n### Approvals\n\nA payment whose price is strictly above `approval.thresholdUsd` (default 0.10)\ntriggers approval. An approval authorizes one payment only. There is no \"always\nallow\", and it never widens future authority.\n\n- `elicit` (default): the client prompts a human with the host, resource, amount,\n  network and asset, guard results, and today's remaining budgets. They approve once\n  or deny. The prompt times out after 120 seconds and is then treated as a denial.\n  Some MCP clients cannot service an elicitation prompt: as of Claude Code v2.1.198\n  and current Claude Desktop, neither does (Claude Code does not advertise the\n  elicitation capability; Claude Desktop advertises it but cancels the prompt\n  immediately). When a client adds elicitation support, the prompt works with no\n  payfetch change. payfetch tells apart a real human \"deny\"\n  from a client that simply cannot ask, and it never treats \"cannot ask\" as a silent\n  denial. When a payment is blocked only because the client cannot elicit, the tool\n  result says so and names the ways to allow it.\n- `queue`: the payment is not executed. The result returns an `approvalId`. A human\n  with approval authority resolves it with the `approve_pending` tool. An approved\n  entry is a grant to re-run: the follow-up `paid_fetch` runs the full pipeline again\n  and matches on host and exact amount. It expires after one hour, and drifted terms\n  require a fresh approval.\n- `deny`: anything above the threshold is refused, for unattended fleets.\n\nFor clients that cannot prompt a human, two config-only settings let above-threshold\npayments through without a dialog. Both are explicit operator authorization, not the\nagent's, and neither is reachable from a tool. `approval.preApprovedUpToUsd` (default\nnull) auto-approves above-threshold payments up to a ceiling.\n`approval.preApprovedHosts` (default empty) auto-approves specific hosts. Both still\npass through every cap and every guard.\n\nApproval never bypasses caps. An approved payment that fails budget reservation is\nstill denied.\n\n`approve_pending` with `{\"action\":\"list\"}` is always allowed and shows the queue.\nApproving or denying an entry requires `PAYFETCH_APPROVER=1` in the server's\nenvironment; without it the tool returns `approver_not_enabled`. An agent must not\napprove its own payments, so the server refuses to start if `PAYFETCH_APPROVER=1` is\ncombined with a queue-capable approval mode.\n\n### Receipts\n\nEvery outcome, including free fetches, dry runs, denials, and unknown-settlement\ncases, appends one immutable JSON line to the ledger:\n\n```\n{dataDir}/ledger/{yyyy-mm}.jsonl   # append-only, monthly rotation, fsync on payments\n{dataDir}/state.json               # disposable cache, rebuildable from the ledger\n{dataDir}/downloads/{receiptId}    # response bodies when responseMode is \"file\"\n```\n\nA receipt records the URL, method, and host; the outcome and deny code; the pipeline\nsteps traversed; the selected quote and a tally of rejected quotes; guard results;\napproval info; the payment (payer address, nonce, validBefore, settled amount,\ntransaction reference, and whether it confirmed); the budgets at decision time; and\nan HTTP summary. Key material, signatures, full payment payloads, response bodies,\nand request header values are never stored. Response bodies are recorded as a\nSHA-256 hash plus a byte count. URL query strings are stored, because this is your\nown audit trail on your own disk; guard calls, by contrast, strip the query (see\nSecurity). Nothing is rewritten. Corrections append `p3f.adjust.v1` records.\n\nQuery receipts with the `list_receipts` tool (filter by time, host, or outcome) or\n`spend_status` (today's totals, holds, and recent payments). After repeated\npaid-but-bad outcomes a host is auto-denied for 7 days; clear it out of band with\n`payfetch clear-autodeny <host>`, never from a tool.\n\n## Trust and safety checks\n\npayfetch can consult two checks before it pays. Both call paid Forum Labs APIs at\n`https://api.forum-labs.com`, and both are self-dealing that is disclosed here rather\nthan buried: the guards call our own products. The default guard budget is 0, so by\ndefault the client uses only those products' free tier. Any paid guard usage is\nopt-in, budgeted with `guards.*.dailyBudgetUsd > 0`, and produces a receipt like any\nother spend.\n\nThe trust check is on by default in advisory mode. Before paying, it asks whether the\ntarget endpoint has a reliable history. In advisory mode it warns; in enforce mode it\nblocks on the configured verdicts (`unreliable` by default). New endpoints without\nenough history come back `unrated` and pass by default, so the check does not\nstrangle them. This check is the client's only outbound call to us; see Security for\nexactly what it sends and how to turn it off.\n\nThe safety check is off by default. When enabled it screens a token mint you pass in\n(`tokenAddress`) against the Forum Labs token safety API and blocks on a `danger`\nverdict, or on a `serial_rugger` deployer verdict in `deep` mode. `deep` is always a\npaid screen, so it needs `dailyBudgetUsd > 0`.\n\n## Security and disclosure\n\nRead this before pointing payfetch at a funded wallet.\n\n### The wallet balance is your real limit\n\nThe primary control on how much a bug or a prompt-injected agent can spend is the\nbalance of the wallet you point payfetch at, not the software caps. A wallet's\nbalance is a hard on-chain bound: payfetch cannot spend a dollar that is not in the\nwallet, whatever the config says or the agent is told to do. So the first thing to\nget right is the wallet.\n\nCreate a fresh wallet, fund it with only the amount you are willing to lose entirely\n(a few dollars for a trial, a capped top-up for production), and give payfetch that\nwallet. Never your main wallet. Refill it deliberately rather than by standing order.\n\nThe caps, lists, approval threshold, and guards are the fine-grained layer on top.\nThey shape rate, per-target exposure, and detection within that balance. They are\nreal and enforced, but the wallet balance is the circuit breaker and the caps are\nthe scalpel. Set both.\n\n### Key custody\n\nYour key is never transmitted to us, never logged, and never written to the receipt\nledger. The ledger stores addresses and amounts, not keys, and that is asserted by a\ntest. Keys are read from the environment in-process to sign EIP-3009 payment\nauthorizations. A signed authorization is bounded to one asset, one amount, one\nrecipient, and one time window. If you use `PAYFETCH_KEY_FILE`, payfetch refuses to\nstart when the file is group- or world-readable, so `chmod 600` it.\n\n### What the trust guard sends, and the off switch\n\nWhile the trust guard is on, it makes one call to the Forum Labs trust API on every\npaid fetch. That call is the client's only egress to us. It sends the target endpoint\nwith the query string stripped, plus a random per-install id. The query is stripped\nbecause a target URL's query can carry your own secrets; server-side we store a hash\nof the input, never the raw target, and the install id is used for aggregate counting\nonly, never per-install profiling or resale. The install id is a random 32-hex value\ngenerated on first run and stored in your state file; delete the state file and it\nregenerates.\n\nTurn the guard off with `guards.trust.enabled: false`. With it off, payfetch makes no\nexternal call at all: no guard result, no network request, nothing dialed. That is\nthe complete off switch, and the honest cost of it is that operators who disable the\nguard are invisible to our adoption instrument.\n\n### Optional outcome reporting (off by default)\n\nReporting is off by default and changes nothing unless you turn it on. When you report\nan outcome, currently only per-incident with `payfetch report <receiptId>`, the client\nreports the outcome of a completed payment attempt (paid and delivered, or paid and\nnot delivered), signed by your payment wallet and tied to the on-chain settlement, to\nthe trust API. This is a fact about the seller's conduct that you are reporting. It is\nnever a record of what you looked at. Lookups (guard checks, quotes, dry runs) are\nnever retained per consumer.\n\nA report sends exactly these fields and nothing else: the endpoint `{method, url}`\nwith the query stripped; the `outcome`, derived from the receipt and never\nagent-supplied; structural `checks` (`settlementConfirmed`, a coarse HTTP status\nclass, `contentTypeOk`, `nonEmpty`); the `termsHash` you paid under; the seller's\n`payTo` address, which is already on-chain; a coarse `amountBand` rather than the\nexact amount; the UTC day rather than an exact timestamp; and your payment wallet\naddress plus an EIP-712 signature over the payload. A report never carries the query\nstring, request headers or bodies, the response body, the receiptId, the exact\namount, or the exact timestamp. The install id never rides on the report path, so the\nreport wallet and the guard install id are never joined.\n\nA settled x402 payment is already public (payer, payee, amount, and time are on the\nchain). What a report adds is the outcome bit. On very-low-traffic endpoints a seller\nmay be able to infer that a report came from you, since the anonymity set is small; we\nmitigate with day granularity and bucketed publication, and we state the residual here\nrather than hide it. In this version the trust API verifies the signature\n(`recover(sig) === payer`), so a stranger cannot report on your behalf, but it does\nnot yet prove the settlement, so reports are shown as unverified until they are\nsettlement-matched in a later version. We will not monetize, publish, or attempt to\ndeanonymize reporter wallets.\n\n### SSRF and private targets\n\nUnless you set `allowPrivateTargets: true`, payfetch refuses non-http(s) schemes and\nany host that resolves to loopback, RFC1918, link-local `169.254/16`, CGNAT, or ULA.\nA paying-fetch must not become the tool that exfiltrates `169.254.169.254`. DNS is\npinned, so the vetted IP is the one dialed; every redirect hop is re-checked; and an\n`https` to `http` downgrade aborts.\n\n### What payfetch does not protect against\n\nFetched content is untrusted input to your agent. A malicious page can tell the agent\nto fetch or pay somewhere else. payfetch bounds the damage with the dedicated wallet's\nbalance and the caps, lists, approval threshold, receipts, and SSRF block, but it\ncannot make the agent wise. It cannot stop an injected agent from spending within\npolicy, so keep the wallet balance small. For untrusted-content workloads, tighten the\ndefaults:\n\n```jsonc\n{\n  \"mode\": \"allowlist\",\n  \"allow\": [\"api.trusted-vendor.com\"],\n  \"caps\": { \"perCallUsd\": 0.05, \"dailyUsd\": 0.50, \"perHostDailyUsd\": 0.25 },\n  \"approval\": { \"thresholdUsd\": 0.0, \"mode\": \"elicit\", \"elicitFallback\": \"deny\" },\n  \"guards\": { \"trust\": { \"enabled\": true, \"mode\": \"enforce\" } }\n}\n```\n\n`thresholdUsd: 0.0` sends every payment to a human. `mode: \"enforce\"` blocks on an\n`unreliable` verdict instead of only warning.\n\nTwo more limits worth stating plainly. There is no on-chain settlement verification\nyet: settlement facts come from the server's payment-response header, so a lying\nserver can misreport. Both error directions over-count, which is the safe direction,\nand on-chain verification is planned. And the ledger is single-instance: one lockfile,\none process, one machine. A fleet needs a policy plane that is not built here.\n\n## Configuration reference\n\nDefaults, from `{dataDir}/config.json`, schema `p3f.policy.v1`:\n\n| Field | Default | Meaning |\n|---|---|---|\n| `mode` | `\"open\"` | `\"allowlist\"` pays only hosts in `allow`. |\n| `allow` | `[]` | Host patterns permitted in allowlist mode. |\n| `deny` | `[]` | Host patterns always refused (wins over `allow`). |\n| `caps.perCallUsd` | `1.00` | Max per single payment. |\n| `caps.dailyUsd` | `2.00` | Max per UTC day. |\n| `caps.perHostDailyUsd` | `1.00` | Max per host per UTC day. |\n| `caps.totalUsd` | `null` | Optional lifetime cap. |\n| `approval.thresholdUsd` | `0.10` | Above this, approval is required. |\n| `approval.mode` | `\"elicit\"` | `elicit`, `queue`, or `deny`. |\n| `approval.elicitFallback` | `\"deny\"` | Used when the client cannot elicit. Fail-closed. |\n| `approval.preApprovedUpToUsd` | `null` | No-dialog ceiling for above-threshold payments. |\n| `approval.preApprovedHosts` | `[]` | Hosts pre-approved to auto-pay above threshold. |\n| `guards.trust.enabled` | `true` | The default-on trust check. |\n| `guards.trust.mode` | `\"advisory\"` | `advisory` warns; `enforce` blocks. |\n| `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. |\n| `guards.trust.blockVerdicts` | `[\"unreliable\"]` | Verdicts that block or warn. |\n| `guards.trust.blockUnrated` | `false` | `unrated` passes by default. |\n| `guards.trust.onUnavailable` | `\"block\"` | Enforce-mode behavior when the guard cannot answer. |\n| `guards.trust.dailyBudgetUsd` | `0` | 0 means free tier only. |\n| `guards.safety.enabled` | `false` | Token safety screen; needs `tokenAddress`. |\n| `guards.safety.mode` | `\"enforce\"` | `advisory` warns; `enforce` blocks. Applies only when the safety guard is enabled. |\n| `guards.safety.depth` | `\"basic\"` | `deep` is always paid. |\n| `guards.safety.blockVerdicts` | `[\"danger\"]` | Token verdicts that block. |\n| `guards.safety.blockDeployerVerdicts` | `[\"serial_rugger\"]` | Deployer verdicts, deep only. |\n| `guards.safety.onUnavailable` | `\"block\"` | Enforce behavior when the safety guard is dead. |\n| `guards.safety.onDegraded` | `\"block\"` | Enforce behavior on a degraded screen. |\n| `allowPrivateTargets` | `false` | SSRF guard. Keep `false`. |\n| `autoDeny.enabled` | `true` | Per-host circuit breaker. |\n\nEnvironment variables read by both the server and the CLI:\n\n| Variable | Meaning |\n|---|---|\n| `PAYFETCH_PRIVATE_KEY` | 0x-hex EVM private key. One of three signer sources. |\n| `PAYFETCH_KEY_FILE` | Path to a mode-600 file holding a 0x-hex key. |\n| `PAYFETCH_CDP_API_KEY_ID` / `_SECRET`, `PAYFETCH_CDP_WALLET_SECRET` | Coinbase CDP server-wallet credentials (all three required together). |\n| `PAYFETCH_CDP_ACCOUNT_NAME` | Optional named CDP EVM account. Defaults to a stable name. |\n| `PAYFETCH_DATA_DIR` | Ledger, state, and config root. Default `~/.payfetch`. |\n| `PAYFETCH_TEST_MODE` | Any value marks receipts `test:true` and refuses Base mainnet quotes (Sepolia only). |\n| `PAYFETCH_APPROVER` | `1` grants approval authority. Refused with a queue-capable mode. |\n| `PAYFETCH_VIA` | Optional `via=` attribution slug sent on guard calls only. |\n\n## Test mode\n\nSet `PAYFETCH_TEST_MODE` to any value. Then every receipt is stamped `test: true` and\nexcluded from metrics, and Base mainnet quotes are refused so a self-test can never\ntouch mainnet spend. Only Base Sepolia settles. Use it to run the end-to-end Base\nSepolia path before spending real USDC.\n\n## CLI\n\nThe `payfetch` CLI reads the same environment as the MCP server.\n\n```bash\n# Reset a host's auto-deny circuit breaker (an operator action, not a tool).\nnpx @forum-labs/payfetch clear-autodeny api.example.com\n\n# Print today's spend status as JSON.\nnpx @forum-labs/payfetch status\n\n# Verify the ledger tamper-evidence sidecar (exits non-zero on any integrity gap).\nnpx @forum-labs/payfetch verify\n\n# Report a paid outcome for a receipt (opt-in, off by default). Prints the exact\n# wallet-signed payload, asks for confirmation, then submits. Never an MCP tool, so\n# the agent can neither file nor suppress a report. Use --yes to skip the prompt.\nnpx @forum-labs/payfetch report <receiptId>\n```\n\n`status` builds the engine and takes the single-writer lock. If the MCP server is\nalready running, use the `spend_status` tool instead, or stop the server first.\n\n## Manual .mcpb install\n\nDirectory submission is not offered for payment connectors, so payfetch is packaged\nfor manual install. Build the bundle:\n\n```bash\nnpm run build:mcpb        # produces dist-mcpb/payfetch.mcpb\n```\n\nThis runs `tsc`, then esbuild-bundles the built server entry and its runtime\ndependencies into a single self-contained ESM file, and packs it with the mcpb tool.\nThe result is a small `.mcpb` zip holding `manifest.json` alongside the bundled\nserver. No `node_modules` is shipped, so Claude Desktop installs it without running\n`npm install`. In Claude Desktop, go to Settings, Extensions, Install from file,\nchoose the `.mcpb`, then fill in exactly one signer option. The bundling logic is in\n`mcpb/build.mjs` and the manifest is `mcpb/manifest.json`.\n\n## From source\n\n```bash\nnpm install         # dev dependencies, including tsx for the from-source flow\nnpm run typecheck   # tsc --noEmit\nnpm test            # vitest, hermetic, no network\nnpm run build       # emit dist/, the compiled JS the package ships\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE). Copyright (c) 2026 Forum Labs.\n",
  "bytes": 23113,
  "sha": "068c5a979c11da33eabc0eeeafc8674fa954d175c0e0f2788b1946bf91ea0475",
  "repo_slug": "forum-labs/payfetch",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_forum_labs_payfetch_39cd1e21/readme"
}