@deepfirstsearch/agent-pay-mcp

An MCP server that lets any MCP agent (Claude Desktop, Claude Code, Cursor, …) pay x402 APIs in USDC on Base without being able to overspend, even if a web page or API response prompt-injects it.

Beta, unaudited. Use Base Sepolia or small amounts on Base mainnet.

The model gets three tools and nothing else:

| Tool | What the model can do | |---|---| | paid_fetch(url, method?, body?, contentType?) | Fetch a URL. If it answers 402 Payment Required, the payment goes through only if the merchant, price and budget match your config | | check_price(url, method?, body?, contentType?) | Free: what paying this URL would do, without paying. The price and payee it would pay, or why it would refuse (payee_mismatch, price_changed, …). Nothing is signed. no_challenge means no terms were shown right now, not that the route is free | | list_merchants() | See which origins it may pay, their prices and what's left | | budget_status() | Remaining budget per merchant, window renewal, vault balance |

The model cannot choose a payee, an amount, a network or a limit: there is no argument for any of them. Merchants, price pins, caps and the spending plan come from your config file; keys come from environment variables. Responses are returned inside a randomly tagged fence marked as untrusted data. On-chain, the Agent Safe vault enforces your signed per-payment and per-day caps even if this machine is compromised.

Setup

1. Budget (owner, once): create a vault and sign a budget per merchant with the owner CLI: npx @deepfirstsearch/agent-pay owner create-vault, then owner budget …, which prints the intentId and a ready-to-paste merchants[] entry. (No vault? Leave out vault, tranche and intentId; each merchant then gets its own payer address derived from AGENT_PAY_BURNER_SEED, which you fund with USDC yourself.)
2. Config: copy config.example.json and fill it in. Amounts are USDC decimal strings. Keep tranche at or below each intent's trancheCap and maxPerTx.
3. Secrets (environment only):
   • AGENT_PAY_AGENT_KEY: the intent's agent key (only with a vault).
   • AGENT_PAY_MCP_CONFIG: the config path, if you don't pass it as an argument.
   • AGENT_PAY_BURNER_SEED: the 32-byte secret the payer addresses were derived from. Never your owner key.

Claude Code

claude mcp add agent-pay \
  -e AGENT_PAY_AGENT_KEY=0x… -e AGENT_PAY_BURNER_SEED=0x… \
  -- npx -y @deepfirstsearch/agent-pay-mcp /absolute/path/config.json

OpenClaw

npm install -g @deepfirstsearch/agent-pay-mcp   # or use "command":"npx","args":["-y","@deepfirstsearch/agent-pay-mcp","/absolute/path/config.json"]
openclaw mcp set agent-pay '{"command":"agent-pay-mcp","args":["/absolute/path/config.json"],"env":{"AGENT_PAY_AGENT_KEY":"${AGENT_PAY_AGENT_KEY}","AGENT_PAY_BURNER_SEED":"${AGENT_PAY_BURNER_SEED}"}}'
openclaw mcp probe agent-pay   # - agent-pay: 3 tools

Full walkthrough: OpenClaw guide.

Claude Desktop / Cursor

claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json (Cursor):

{
  "mcpServers": {
    "agent-pay": {
      "command": "npx",
      "args": ["-y", "@deepfirstsearch/agent-pay-mcp", "/absolute/path/config.json"],
      "env": { "AGENT_PAY_AGENT_KEY": "0x…", "AGENT_PAY_BURNER_SEED": "0x…" }
    }
  }
}

From source instead of npm: cd integrations/mcp && npm ci && npm run build, then use node /path/to/integrations/mcp/dist/index.js as the command.

Quick start with verified sellers (Base mainnet)

The verified preset ships 35 x402 sellers whose payee and price were confirmed with a real payment, each with a guide. They are re-checked live, without paying, by scripts/verify-preset.ts, and the list is in src/presets.ts. You pick the ones you use and set your total budget:

{
  "network": "eip155:8453",
  "preset": "verified",
  "presetOnly": ["https://netintel.dev"],
  "periodBudget": { "amount": "1.00", "hours": 24 }
}

Save it as preset.json and start the server with AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./preset.json. On start it prints the payer address for each seller. Send that address a little USDC on Base (0.10 covers dozens of calls). Then ask your agent to check_price and paid_fetch a seller's URL, for example https://netintel.dev/web/extract?url=https://www.sitemaps.org/protocol.html. Keep the seed: the same seed gives the same payer addresses.

• Your own entries win: if you list a merchant with the same origin under merchants, the preset's entry is ignored.
• Choosing sellers: presetOnly limits the preset to those origins; presetExclude leaves some out; presetMaxSpend (default "0.25") caps each seller per plan window.
• Budget: periodBudget is required with a preset. It's your total across all of them.
• Vaults: the preset works with payers you fund yourself for now. With a vault, list your merchants with their intentId instead.

Try it offline (1 minute)

No keys to fund, no chain: run a local mock merchant from the SDK and point the server at it.

npm install -g @deepfirstsearch/agent-pay-mcp   # or skip this and use `npx -y @deepfirstsearch/agent-pay-mcp` below
mkdir mock && cd mock && npm init -y >/dev/null && npm install @deepfirstsearch/agent-pay
node --input-type=module -e '
import { startMockServer } from "@deepfirstsearch/agent-pay/testing";
const m = await startMockServer({ "/data": { price: 10000n, payTo: "0x1111111111111111111111111111111111111111", body: "{\"ok\":true}" } });
console.log("origin:", m.url);'

Leave it running. In offline.json, use the printed origin: { "network": "eip155:84532", "merchants": [{ "origin": "<printed origin>", "payTo": "0x1111111111111111111111111111111111111111", "price": "0.01", "maxPerTx": "0.05", "maxSpend": "0.50" }] }. Then start the server with AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) agent-pay-mcp ./offline.json (without a global install: AGENT_PAY_BURNER_SEED=0x$(openssl rand -hex 32) npx -y @deepfirstsearch/agent-pay-mcp ./offline.json), or add it to your MCP client, and call paid_fetch with <printed origin>/data. The mock verifies signatures locally, so the payer needs no funds.

See it work in 5 minutes (Base Sepolia)

sdk/examples/demo-merchant.ts is a tiny x402 API on Base Sepolia with an honest route (/premium, 0.01 USDC) and a hostile one (/malicious: its 402 asks for 5 USDC to an attacker address and its body carries a prompt injection).

cd sdk && MERCHANT=0xYourMerchantAddress npx tsx examples/demo-merchant.ts

Point the config's merchant at http://127.0.0.1:4021 with that payTo, then ask your agent to fetch /premium and /malicious. Expected: the first is paid and settled on-chain; the second is refused before anything is signed ("payTo … is not the merchant's registered address").

Config reference

| Field | Meaning | |---|---| | network | eip155:84532 (Base Sepolia) or eip155:8453 (Base) | | rpcUrl | Optional RPC URL for that network (vault top-ups and balance reads); defaults to viem's public RPC | | vault, tranche | Agent Safe vault that tops up each merchant's payer, and the top-up size | | merchants[].origin, payTo | Who may be paid, and the only address the payment can go to | | merchants[].intentId | The owner-signed budget (intent) for this merchant, as printed by owner budget; required for every merchant when vault is set | | merchants[].label | Optional display name (up to 80 characters) shown by list_merchants | | merchants[].price, tolerancePct | Expected price per call; anything above price × (1 + tolerance) is refused | | merchants[].maxPerTx, maxSpend | Hard cap per call, and per merchant per plan window | | merchants[].maxTimeoutSeconds | Longest authorization this merchant may ask for, 10 to 86400 s (default 300 s). Only that merchant gets the longer window. | | merchants[].x402Versions | x402 versions this merchant may be paid with, default [2]. Set [1, 2] for merchants that still speak x402 v1 (e.g. Heurist Mesh). | | confirmOnChain | Default true. When a merchant's receipt is missing or unreadable, USDC is asked on-chain (through rpcUrl) whether the payment executed, instead of resending. Needed for merchants with non-standard receipts (CoinMarketCap, JustaName, Glim). Only used on that failure path. | | planWindowHours | The plan is sealed from this file at start and renewed from it every window | | periodBudget | Total across merchants per period: { "amount": "1.00", "hours": 24 } | | approvalAbove | Payments above this are refused (this server has no approval channel the model can't reach) | | sessionHasSensitiveData | If the agent can also read private data, every payment needs a human (Rule of Two), so all are refused | | auditLog | Hash-chained JSONL log of every decision | | maxResponseChars | Longest response body returned to the model, in characters (default 20000, max 1000000); longer bodies are truncated and say so | | allowPrivateNetwork | Default false. Set true to let paid_fetch reach http:// URLs and loopback, private, link-local or CGNAT hosts that are not merchants in this file |

Unknown keys are rejected, so a typo (approvalabove) stops the server instead of silently dropping a limit.

Since 0.2.0 every tested merchant works through MCP: set x402Versions: [1, 2] for v1 merchants (Heurist Mesh), and leave confirmOnChain on for merchants with non-standard receipts (CoinMarketCap, JustaName, Glim). Without a vault, the server prints each merchant's payer address on start, so you know which address to fund.

A refused payment comes back as an error result, Payment refused by policy: …. From 0.1.8, once the bundled @deepfirstsearch/agent-pay is 0.8.0 or later, the text carries the refusal's stable code and what to do about it, e.g. Payment refused by policy [price_changed → ask the owner]: … (codes listed in the SDK README, "Refusal codes"). Blocks carry codes too (Payment blocked [settlement_pending → …]: …; also settled_not_delivered, rate_limited, kill_switch), with the extra action resend_same: call paid_fetch on the same URL again, and the SDK resends the same signed authorization without signing a new one.

paid_fetch fetches any public https URL the model asks for; only payments are restricted to the merchants in your config. A non-402 response from an unregistered origin is returned as data (fenced as untrusted), so treat it like any fetch tool you give a model. Hosts that are or resolve to loopback, private, link-local or CGNAT addresses, localhost names and plain http are refused unless they are a merchant in your config or you set allowPrivateNetwork; redirects are returned, not followed. Errors other than policy refusals (for example an RPC failure, whose message can contain your rpcUrl) reach the model as a fixed text; the details go to the server's stderr.

Develop

npm ci && npm run typecheck && npm test   # tests drive the server through an MCP client against a mock x402 merchant