presign-guard-wallet-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frits Zwager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# presign-guard-wallet-mcp
+
+A wallet with spending limits for AI agents, as an [MCP](https://modelcontextprotocol.io) server. Add it to Claude Desktop, Claude Code, Cursor or any other MCP client, and your agent can:
+- pay for x402 APIs;
+- send USDC.
+
+It can only do that within the budget you set:
+
+- **You set the limits.** For example: up to 5 USDC per payment and 20 USDC a day, and the agent is free to spend within them.
+- **Above a limit, you decide.** You get a Telegram message with Approve / Deny, or the request shows up on your [wallet server](https://github.com/Fizzl13/x402-examples/tree/main/wallet-server) dashboard. No answer means no payment.
+- **Every signature is checked first by [presign-guard](https://presign-guard.fizzl.eu).** It checks for known drainers, sanctioned addresses and look-alike tokens. A red verdict is never signed.
+- **When in doubt, nothing is signed.** If the check, Telegram or the server can't be reached, the wallet stops.
+
+The key stays on your machine; the server only decides whether a signature is allowed. Each check costs $0.01, paid in USDC on Base from the same wallet, or from prepaid credits.
+
+See the dashboard (demo data): **https://wallet.fizzl.eu/demo**
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `wallet_status` | Address, balances, limits, what is left today, how approvals work |
+| `pay_x402` | Call an API that answers 402 Payment Required, pay it in USDC, return the response (with a price cap per call) |
+| `send_usdc` | Send USDC to an address |
+| `send_native` | Send ETH / POL / BNB to an address |
+| `pause_spending` | The agent stops itself when something looks wrong; nothing is signed until you restart or resume |
+
+## Set up
+
+1. **Make a separate wallet for the agent.** Put only what it may spend in it: a few dollars of USDC on Base, plus a little ETH for gas if it will send transfers. Never use your main wallet.
+2. **Optional: phone approvals.**
+   - Create a bot with [@BotFather](https://t.me/BotFather), send it `/start`.
+   - Get your chat id from [@userinfobot](https://t.me/userinfobot).
+3. **Add it to your MCP client.** For Claude Desktop, put this in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wallet": {
+      "command": "npx",
+      "args": ["-y", "presign-guard-wallet-mcp"],
+      "env": {
+        "AGENT_KEY": "0x…the agent wallet's private key…",
+        "LIMIT_USDC_PER_TX": "5",
+        "LIMIT_USDC_PER_DAY": "20",
+        "TELEGRAM_BOT_TOKEN": "123456:ABC…",
+        "TELEGRAM_CHAT_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```sh
+claude mcp add wallet -e AGENT_KEY=0x… -e LIMIT_USDC_PER_TX=5 -e LIMIT_USDC_PER_DAY=20 -- npx -y presign-guard-wallet-mcp
+```
+
+Then ask your agent, for example: *"Check my wallet, then get the BTC signal from https://ichimoku-signal.fizzl.eu/signal/BTC-USDT"*.
+
+### One budget for all your agents
+
+Run the [wallet server](https://github.com/Fizzl13/x402-examples/tree/main/wallet-server) and make an agent key on its dashboard. It gives you:
+- one price rule and one daily budget for all your agents;
+- approvals on the dashboard and on Telegram;
+- an activity log.
+
+Then use these variables instead of `LIMIT_*` and `TELEGRAM_*`:
+
+```json
+"env": {
+  "AGENT_KEY": "0x…",
+  "WALLET_SERVER_URL": "https://your-wallet-server.example",
+  "WALLET_SERVER_KEY": "awk_…"
+}
+```
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `AGENT_KEY` | **required**: private key of the agent's own wallet |
+| `LIMIT_USDC_PER_TX`, `LIMIT_USDC_PER_DAY` | USDC limits (payments and transfers together). Limits or a wallet server are required |
+| `LIMIT_NATIVE_PER_TX`, `LIMIT_NATIVE_PER_DAY` | limits for the native coin; without them, sending it needs approval |
+| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | approvals on Telegram; without them, anything over a limit is refused |
+| `WALLET_SERVER_URL`, `WALLET_SERVER_KEY` | a wallet server instead of the above |
+| `CHAIN` | `base` (default), `ethereum`, `optimism`, `arbitrum`, `polygon` or `bsc` |
+| `MAX_PAYMENT_USD` | most one `pay_x402` call may cost (default `1`); a cap on top of the limits |
+| `PRESIGN_CREDIT_KEY` | pay the $0.01 checks from [prepaid credits](https://presign-guard.fizzl.eu) (`pgc_…`) |
+| `RPC_URL` | your own RPC for the chain |
+| `AGENT_LABEL` | the name shown in Telegram approval messages (default `mcp-agent`) |
+
+One Telegram bot serves one running server at a time, and the bot must not have a webhook. To run several agents on one bot, use the wallet server.
+
+## When something is refused
+
+The tool returns an error the agent can read and pass on to you. Examples:
+- `Not done (over_limit): 8 USDC is over the limit of 5 per transaction (denied by the owner)`;
+- `Not done (red): not signed: red (known_drainer)`.
+
+## Also available
+
+- [presign-guard-wallet](https://github.com/Fizzl13/x402-examples/tree/main/guard-wallet): the same guard for your own viem code.
+- [presign-guard-agentkit](https://github.com/Fizzl13/x402-examples/tree/main/agentkit-guard): for Coinbase AgentKit agents.
+
+## License
+
+MIT

package/lib.js

@@ -0,0 +1,245 @@
+// The wallet behind presign-guard-wallet-mcp: an agent's own key, wrapped in
+// presign-guard-wallet, so every payment and transfer a model asks for is
+// checked by presign-guard and kept to the owner's limits, with approval on
+// Telegram or the wallet server above them.
+import { createPublicClient, createWalletClient, erc20Abi, formatEther, formatUnits, http, isAddress, parseEther, parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { arbitrum, base, bsc, mainnet, optimism, polygon } from "viem/chains";
+import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { guardWallet, PresignBlockedError } from "presign-guard-wallet";
+import { telegramApprover } from "presign-guard-wallet/telegram";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export const VERSION = "0.1.0";
+
+export const CHAINS = {
+  base: { chain: base, usdc: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", 6] },
+  ethereum: { chain: mainnet, usdc: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", 6] },
+  optimism: { chain: optimism, usdc: ["0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", 6] },
+  arbitrum: { chain: arbitrum, usdc: ["0xaf88d065e77c8cC2239327C5EDb3A432268e5831", 6] },
+  polygon: { chain: polygon, usdc: ["0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", 6] },
+  bsc: { chain: bsc, usdc: ["0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", 18] },
+};
+
+const BODY_LIMIT = 20_000;
+const CHECK_PRICE_CAP = "$0.02"; // a presign-guard check costs $0.01
+
+const amountString = z.string().regex(/^\d+(\.\d+)?$/, "a decimal amount like \"2.5\"");
+const address = z.string().refine((a) => isAddress(a, { strict: false }), "an 0x… address");
+
+/**
+ * Read the configuration from environment variables (see README).
+ * Throws a readable error for anything missing or unsafe.
+ */
+export function configFromEnv(env = process.env) {
+  const key = env.AGENT_KEY?.trim();
+  if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key)) throw new Error("AGENT_KEY must be the agent wallet's private key (0x + 64 hex). Use a separate wallet with only what the agent may spend.");
+  const chainName = (env.CHAIN ?? "base").toLowerCase();
+  if (!CHAINS[chainName]) throw new Error(`CHAIN must be one of ${Object.keys(CHAINS).join(", ")}`);
+
+  const server = env.WALLET_SERVER_URL || env.WALLET_SERVER_KEY ? { url: env.WALLET_SERVER_URL, key: env.WALLET_SERVER_KEY } : undefined;
+  const tokens = {};
+  const usdc = pick(env.LIMIT_USDC_PER_TX, env.LIMIT_USDC_PER_DAY);
+  if (usdc) tokens.USDC = usdc;
+  const nativeSymbol = CHAINS[chainName].chain.nativeCurrency.symbol;
+  const native = pick(env.LIMIT_NATIVE_PER_TX, env.LIMIT_NATIVE_PER_DAY);
+  if (native) tokens[nativeSymbol === "MATIC" ? "POL" : nativeSymbol] = native;
+  if (server && Object.keys(tokens).length) throw new Error("with WALLET_SERVER_URL the limits live on the wallet server: leave out the LIMIT_* variables");
+  if (!server && !Object.keys(tokens).length) throw new Error("set spending limits (LIMIT_USDC_PER_TX and/or LIMIT_USDC_PER_DAY) or a wallet server (WALLET_SERVER_URL + WALLET_SERVER_KEY): this wallet does not run without a budget");
+
+  const telegram = env.TELEGRAM_BOT_TOKEN || env.TELEGRAM_CHAT_ID ? { token: env.TELEGRAM_BOT_TOKEN, chatId: env.TELEGRAM_CHAT_ID } : undefined;
+  if (telegram && (!telegram.token || !telegram.chatId)) throw new Error("Telegram approval needs both TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID");
+  if (telegram && server) throw new Error("with WALLET_SERVER_URL, approvals go through the wallet server (its own Telegram): leave out TELEGRAM_*");
+
+  const maxPrice = env.MAX_PAYMENT_USD ?? "1";
+  if (!/^\d+(\.\d+)?$/.test(maxPrice)) throw new Error("MAX_PAYMENT_USD must be a number of dollars, e.g. 1 or 0.25");
+
+  return {
+    key,
+    chainName,
+    rpcUrl: env.RPC_URL || undefined,
+    creditKey: env.PRESIGN_CREDIT_KEY || undefined,
+    server,
+    limits: server ? undefined : { tokens },
+    telegram,
+    label: env.AGENT_LABEL || "mcp-agent",
+    maxPaymentUsd: Number(maxPrice),
+  };
+}
+
+function pick(perTx, perDay) {
+  const out = {};
+  for (const [k, v] of [["perTx", perTx], ["perDay", perDay]]) {
+    if (v === undefined || v === "") continue;
+    if (!/^\d+(\.\d+)?$/.test(v)) throw new Error(`limits must be amounts like "5" or "0.5" (got "${v}")`);
+    out[k] = v;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * The guarded wallet and what the tools do with it. `overrides` is for tests
+ * (walletClient, publicClient, fetch, presign options such as verifyReceipts).
+ */
+export function createWallet(config, overrides = {}) {
+  const { chain, usdc } = CHAINS[config.chainName];
+  const account = privateKeyToAccount(config.key);
+  const transport = http(config.rpcUrl);
+  const walletClient = overrides.walletClient ?? createWalletClient({ account, chain, transport });
+  const publicClient = overrides.publicClient ?? createPublicClient({ chain, transport });
+  const plainFetch = overrides.fetch ?? globalThis.fetch;
+
+  // Pays the presign-guard checks ($0.01 each, USDC on Base) with the agent's key,
+  // capped per payment. Not guarded itself: guarding the check would check the check.
+  const checkPayer = new x402Client().setSpendControls({ maxAmountPerPayment: CHECK_PRICE_CAP });
+  checkPayer.register("eip155:8453", new ExactEvmScheme(account));
+  const pay = wrapFetchWithPayment(plainFetch, checkPayer);
+
+  const onOverLimit = config.telegram ? telegramApprover({ ...config.telegram, label: config.label, fetch: plainFetch }) : undefined;
+  const guarded = guardWallet(walletClient, {
+    pay,
+    creditKey: config.creditKey,
+    fetch: plainFetch,
+    limits: config.limits,
+    onOverLimit,
+    server: config.server ? { ...config.server, fetch: plainFetch } : undefined,
+    ...overrides.guard,
+  });
+
+  // x402 payments are signed by the guarded wallet: checked, and counted toward the USDC limits.
+  const signer = {
+    address: account.address,
+    signTypedData: (typedData) => guarded.signTypedData({ account, ...typedData }),
+    readContract: (args) => publicClient.readContract(args),
+  };
+
+  return {
+    address: account.address,
+    chain,
+    guard: guarded,
+
+    async status() {
+      const [native, usdcBalance] = await Promise.all([
+        publicClient.getBalance({ address: account.address }).catch(() => null),
+        publicClient.readContract({ address: usdc[0], abi: erc20Abi, functionName: "balanceOf", args: [account.address] }).catch(() => null),
+      ]);
+      return {
+        address: account.address,
+        chain: `${config.chainName} (${chain.id})`,
+        balances: {
+          [chain.nativeCurrency.symbol]: native === null ? "unknown" : formatEther(native),
+          USDC: usdcBalance === null ? "unknown" : formatUnits(usdcBalance, usdc[1]),
+        },
+        limits: config.server ? `kept by the wallet server ${config.server.url}` : config.limits.tokens,
+        spending: await guarded.spending().catch((err) => `unavailable (${err.message})`),
+        approvals: config.server ? "wallet server (dashboard / Telegram)" : config.telegram ? "Telegram" : "none: anything over a limit is refused",
+        maxPaymentUsd: config.maxPaymentUsd,
+        paused: guarded.paused(),
+      };
+    },
+
+    async sendUsdc({ to, amount }) {
+      const value = parseUnits(amount, usdc[1]);
+      const hash = await guarded.writeContract({ address: usdc[0], abi: erc20Abi, functionName: "transfer", args: [to, value] });
+      return { hash, sent: `${amount} USDC`, to, chain: config.chainName };
+    },
+
+    async sendNative({ to, amount }) {
+      const hash = await guarded.sendTransaction({ to, value: parseEther(amount) });
+      return { hash, sent: `${amount} ${chain.nativeCurrency.symbol}`, to, chain: config.chainName };
+    },
+
+    async payX402({ url, method = "GET", body, headers, maxPriceUsd }) {
+      if (!/^https?:\/\//.test(url)) throw new TypeError("url must start with https:// or http://");
+      const cap = Math.min(maxPriceUsd ?? config.maxPaymentUsd, config.maxPaymentUsd);
+      const client = new x402Client().setSpendControls({ maxAmountPerPayment: `$${cap}` });
+      client.register(`eip155:${chain.id}`, new ExactEvmScheme(signer));
+      const res = await wrapFetchWithPayment(plainFetch, client)(url, { method, headers, body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body) });
+      const text = await res.text();
+      const settled = res.headers.get("payment-response") ?? res.headers.get("x-payment-response");
+      let payment = null;
+      if (settled) { try { payment = decodePaymentResponseHeader(settled); } catch { payment = { raw: settled }; } }
+      return {
+        status: res.status,
+        paid: !!payment,
+        payment,
+        contentType: res.headers.get("content-type"),
+        body: text.length > BODY_LIMIT ? `${text.slice(0, BODY_LIMIT)}\n… (${text.length - BODY_LIMIT} more characters cut)` : text,
+      };
+    },
+
+    pause(reason) {
+      guarded.pause();
+      return `Paused: nothing will be signed until the owner restarts this server${config.server ? " (or resumes it on the wallet server)" : ""}. Reason: ${reason}`;
+    },
+  };
+}
+
+const json = (v) => JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x), 2);
+
+function result(fn) {
+  return async (args) => {
+    try {
+      const out = await fn(args);
+      return { content: [{ type: "text", text: typeof out === "string" ? out : json(out) }] };
+    } catch (err) {
+      // x402 wraps errors from the signer; find the guard's own refusal underneath.
+      let blocked = err;
+      while (blocked && !(blocked instanceof PresignBlockedError)) blocked = blocked.cause;
+      const guardText = /not signed|nothing was signed|is paused/.exec(err.message) ? err.message.replace(/^.*?(?=not signed|presign check|wallet is paused|spending limits|verdict not trusted|chain \d)/, "") : null;
+      const why = blocked ? `Not done (${blocked.code}): ${blocked.message}` : guardText ? `Not done: ${guardText}` : `Failed: ${err.message}`;
+      return { isError: true, content: [{ type: "text", text: why }] };
+    }
+  };
+}
+
+/** The MCP server with the wallet's tools. */
+export function createServer(wallet) {
+  const server = new McpServer({ name: "presign-guard-wallet", version: VERSION });
+  server.registerTool("wallet_status", {
+    title: "Wallet status",
+    description: "This agent's wallet: address, chain, balances, spending limits, what is left today, how approvals work, and whether it is paused. Check it before spending.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  }, result(() => wallet.status()));
+
+  server.registerTool("pay_x402", {
+    title: "Pay for an x402 API",
+    description: "Call a URL that may answer 402 Payment Required (x402) and pay it in USDC from this wallet, then return the response. The payment is checked by presign-guard and counts toward the spending limits; over a limit the owner is asked to approve (the call waits), and a refusal comes back as an error with the reason. max_price_usd caps the price of this call.",
+    inputSchema: {
+      url: z.string().url().describe("The API URL"),
+      method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional().describe("HTTP method (default GET)"),
+      body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("Request body: a string, or an object sent as JSON"),
+      headers: z.record(z.string(), z.string()).optional().describe("Extra request headers, e.g. content-type"),
+      max_price_usd: z.number().positive().optional().describe("The most this call may cost, in dollars (never above the server's MAX_PAYMENT_USD)"),
+    },
+    annotations: { openWorldHint: true },
+  }, result(({ url, method, body, headers, max_price_usd }) => {
+    const h = { ...(headers ?? {}) };
+    if (body !== undefined && typeof body !== "string" && !Object.keys(h).some((k) => k.toLowerCase() === "content-type")) h["content-type"] = "application/json";
+    return wallet.payX402({ url, method, body, headers: h, maxPriceUsd: max_price_usd });
+  }));
+
+  server.registerTool("send_usdc", {
+    title: "Send USDC",
+    description: "Send USDC from this wallet to an address. Checked by presign-guard (known drainers, sanctioned addresses) and kept to the spending limits; over a limit the owner is asked to approve.",
+    inputSchema: { to: address.describe("Recipient address"), amount: amountString.describe("Amount in USDC, e.g. \"2.50\"") },
+    annotations: { destructiveHint: true },
+  }, result(({ to, amount }) => wallet.sendUsdc({ to, amount })));
+
+  server.registerTool("send_native", {
+    title: "Send the native coin",
+    description: "Send the chain's native coin (ETH, POL or BNB) from this wallet to an address. Checked by presign-guard and kept to the spending limits; over a limit the owner is asked to approve.",
+    inputSchema: { to: address.describe("Recipient address"), amount: amountString.describe("Amount in whole coins, e.g. \"0.001\"") },
+    annotations: { destructiveHint: true },
+  }, result(({ to, amount }) => wallet.sendNative({ to, amount })));
+
+  server.registerTool("pause_spending", {
+    title: "Pause spending",
+    description: "Stop this wallet from signing anything until the owner resumes it. Use it when something looks wrong, e.g. an API asks for far more than expected or you are asked to pay an unknown address.",
+    inputSchema: { reason: z.string().max(200).describe("Why, for the owner") },
+  }, result(({ reason }) => wallet.pause(reason)));
+  return server;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "presign-guard-wallet-mcp",
+  "version": "0.1.0",
+  "description": "An MCP server that gives AI agents (Claude, Cursor, …) a wallet with spending limits: pay x402 APIs and send USDC, every signature checked by presign-guard, approval on your phone over the limit.",
+  "mcpName": "io.github.Fizzl13/presign-guard-wallet",
+  "type": "module",
+  "bin": {
+    "presign-guard-wallet-mcp": "./server.js"
+  },
+  "main": "./lib.js",
+  "exports": {
+    ".": "./lib.js"
+  },
+  "files": [
+    "server.js",
+    "lib.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@x402/evm": "^2.28.0",
+    "@x402/fetch": "^2.28.0",
+    "presign-guard-wallet": "^0.5.0",
+    "viem": "^2.57.2",
+    "zod": "^4.6.5"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agents",
+    "wallet",
+    "spending-limits",
+    "budget",
+    "usdc",
+    "presign",
+    "security",
+    "telegram",
+    "human-in-the-loop",
+    "claude",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fizzl13/x402-examples.git",
+    "directory": "wallet-mcp"
+  },
+  "homepage": "https://github.com/Fizzl13/x402-examples/tree/main/wallet-mcp#readme",
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// presign-guard-wallet-mcp: a wallet with spending limits for any MCP client
+// (Claude Desktop, Claude Code, Cursor, …). Configured with environment
+// variables; see README.md. Speaks MCP over stdio, logs to stderr.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { configFromEnv, createServer, createWallet, VERSION } from "./lib.js";
+
+let config;
+try {
+  config = configFromEnv();
+} catch (err) {
+  console.error(`[presign-guard-wallet-mcp] ${err.message}`);
+  process.exit(1);
+}
+const wallet = createWallet(config);
+await createServer(wallet).connect(new StdioServerTransport());
+console.error(`[presign-guard-wallet-mcp ${VERSION}] wallet ${wallet.address} on ${config.chainName}, ${config.server ? `limits on ${config.server.url}` : `limits ${JSON.stringify(config.limits.tokens)}`}${config.telegram ? ", approvals on Telegram" : ""}`);