@aibtc/mcp-server 1.59.0 → 1.60.0

package/README.md

@@ -69,6 +69,38 @@ npx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/
 
 Each installer merges into the existing config — it won't clobber other servers or settings. Restart the client afterward.
 
+### OpenRouter (any model)
+
+The clients above are MCP hosts — they connect to this server for you. To drive the tools with an [OpenRouter](https://openrouter.ai) model instead, the server ships a built-in bridge: it spawns itself in server mode, exposes the tools to the model as function tools, and runs the tool-call loop. This is the client-side pattern from [OpenRouter's MCP cookbook](https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers), packaged into the binary.
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3...?"
+```
+
+Safety flags (this server moves real funds, so the bridge defaults to nothing extra and lets you constrain it):
+
+| Flag | Effect |
+|------|--------|
+| `--read-only` | Expose only read-only tools (no transfer/swap/deploy/etc.) |
+| `--allow a,b` | Force-allow specific tool names (added to the set) |
+| `--block a,b` | Force-remove specific tool names (wins over `--allow`) |
+| `--max-spend-ustx <n>` / `--max-spend-sats <n>` | Cap spend via the server's spend-limit rail (enforced before signing) |
+| `--list-tools` | Print the exposed tool set and exit (no API key needed) |
+| `--model <id>` | OpenRouter model (default `anthropic/claude-3.5-haiku`) |
+| `--network <net>` | `mainnet` or `testnet` (default `mainnet`) |
+| `--max-turns <n>` | Tool-call loop cap (default 10) |
+
+```bash
+# Preview what a read-only session would expose, no key needed:
+npx @aibtc/mcp-server@latest bridge --read-only --list-tools
+
+# Read-only chat, plus one explicitly allowed write tool:
+npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
+```
+
+The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
+
 ### Testnet Mode
 
 Add `--testnet` to any install command:
@@ -512,9 +544,14 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 | `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |
 | `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |
 | `HIRO_API_KEY` | (Optional) Hiro API key for higher rate limits | - |
+| `SPEND_LIMIT_ENABLED` | Set `false` to disable the wallet spending limit | `true` |
+| `SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX` | STX spend cap per day / per unlock (micro-STX) | `10000000` (10 STX) |
+| `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` | BTC spend cap per day / per unlock (sats) | `50000` |
 
 **Note on `NETWORK`:** The `--install` command writes `NETWORK=mainnet` by default (pass `--testnet` to use testnet). If you omit `NETWORK` from your config entirely, the runtime fallback is `testnet`. Most users should set this explicitly.
 
+**Note on spending limits:** A default-on safety rail meters every outbound spend (`transfer_stx`, `transfer_btc`, x402/L402 auto-payments) against a cumulative per-session and per-day cap, so a single bad instruction or a malicious endpoint can't drain the wallet. A spend over the cap is blocked and reports the remaining budget. Raise the caps via the env vars above, or disable with `SPEND_LIMIT_ENABLED=false`. See [SECURITY.md](SECURITY.md#limit-blast-radius).
+
 **Note:** `CLIENT_MNEMONIC` is optional. The recommended approach is to let Claude create its own wallet. `HIRO_API_KEY` is optional but recommended for production use — without it, you may hit Hiro's public rate limits (429 responses). Get a key at [platform.hiro.so](https://platform.hiro.so).
 
 ## Architecture
@@ -538,8 +575,12 @@ You ←→ Claude ←→ aibtc-mcp-server
 - Mnemonics shown only once at creation
 - Auto-lock after 15 minutes (configurable)
 - Transactions signed locally before broadcast
+- **Spending limit (default-on):** outbound spends are capped per session and per day so a single bad instruction can't drain the wallet — see [Configuration](#configuration)
+- **Secret-scanning pre-commit hook:** contributors get a hook (auto-installed via `npm install`) that blocks committing a seed phrase or private key
 - For mainnet: Fund with small amounts first
 
+See [SECURITY.md](SECURITY.md) for the full wallet-key protection model and key-leak recovery steps.
+
 ## Advanced: Pre-configured Mnemonic
 
 For automated setups where Claude needs immediate wallet access, add the `CLIENT_MNEMONIC` environment variable to your MCP server config (in `~/.claude.json` for Claude Code, or `claude_desktop_config.json` for Claude Desktop):

package/dist/bridge/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenRouter <-> MCP bridge (`aibtc-mcp-server bridge`).
+ *
+ * Lets any OpenRouter model call this server's tools. This is the canonical
+ * integration described in OpenRouter's own cookbook
+ * (https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers): the CLIENT
+ * connects to the MCP server and routes LLM calls through OpenRouter — there is
+ * no OpenRouter-side MCP hosting. This is a Node port of that pattern with two
+ * upgrades: it handles every tool_call (not just the first) and loops to
+ * completion (not a single round).
+ *
+ * Flow:
+ *   1. Spawn this same binary in server mode over stdio, connect, list tools.
+ *   2. Apply safety filters, then convert each MCP tool -> OpenAI function tool.
+ *   3. POST conversation + tools to OpenRouter /chat/completions.
+ *   4. On tool_calls, execute via MCP and feed results back as role:"tool".
+ *   5. Loop until the model answers in plain text (capped by --max-turns).
+ *
+ * Safety flags:
+ *   --read-only            expose only read-only tools (heuristic allowlist)
+ *   --allow a,b,c          force-allow these tool names (added to the set)
+ *   --block a,b,c          force-remove these tool names (applied last, wins)
+ *   --max-spend-ustx <n>   forward to the server's SPEND_LIMIT_SESSION_USTX rail
+ *   --max-spend-sats <n>   forward to the server's SPEND_LIMIT_SESSION_SATS rail
+ *   --list-tools           print the exposed tool set and exit (no API key needed)
+ *   --model <id>           OpenRouter model (default anthropic/claude-3.5-haiku)
+ *   --network <net>        mainnet|testnet for the spawned server (default mainnet)
+ *   --max-turns <n>        tool-call loop cap (default 10)
+ */
+export declare function runBridge(argv: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.js

@@ -0,0 +1,285 @@
+/**
+ * OpenRouter <-> MCP bridge (`aibtc-mcp-server bridge`).
+ *
+ * Lets any OpenRouter model call this server's tools. This is the canonical
+ * integration described in OpenRouter's own cookbook
+ * (https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers): the CLIENT
+ * connects to the MCP server and routes LLM calls through OpenRouter — there is
+ * no OpenRouter-side MCP hosting. This is a Node port of that pattern with two
+ * upgrades: it handles every tool_call (not just the first) and loops to
+ * completion (not a single round).
+ *
+ * Flow:
+ *   1. Spawn this same binary in server mode over stdio, connect, list tools.
+ *   2. Apply safety filters, then convert each MCP tool -> OpenAI function tool.
+ *   3. POST conversation + tools to OpenRouter /chat/completions.
+ *   4. On tool_calls, execute via MCP and feed results back as role:"tool".
+ *   5. Loop until the model answers in plain text (capped by --max-turns).
+ *
+ * Safety flags:
+ *   --read-only            expose only read-only tools (heuristic allowlist)
+ *   --allow a,b,c          force-allow these tool names (added to the set)
+ *   --block a,b,c          force-remove these tool names (applied last, wins)
+ *   --max-spend-ustx <n>   forward to the server's SPEND_LIMIT_SESSION_USTX rail
+ *   --max-spend-sats <n>   forward to the server's SPEND_LIMIT_SESSION_SATS rail
+ *   --list-tools           print the exposed tool set and exit (no API key needed)
+ *   --model <id>           OpenRouter model (default anthropic/claude-3.5-haiku)
+ *   --network <net>        mainnet|testnet for the spawned server (default mainnet)
+ *   --max-turns <n>        tool-call loop cap (default 10)
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
+const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
+/**
+ * Read-only heuristic. A tool counts as read-only only if it matches a known
+ * read pattern AND contains no mutating verb — deliberately conservative so a
+ * spend/write tool is never auto-included. Use --allow/--block for precision.
+ */
+const READ_PATTERNS = [
+    /^get_/, /^list_/, /^check_/, /^lookup_/, /^reverse_/, /^probe_/, /^read_/,
+    /_status$/, /_info$/, /_quote$/, /_quote_/, /_models$/, /_guide$/, /_list$/,
+    /_balance$/, /_fees$/, /_utxos$/, /_history$/, /_holdings$/, /_overview$/,
+    /_summary$/, /_health$/, /_price$/, /_prices$/, /_state$/, /_positions$/,
+    /_breakdown$/, /_dashboard_/, /_stats$/, /_metadata$/, /_owner$/, /_holders$/,
+    /_search$/, /_feed$/, /_profile$/, /_pubkey$/, /_availability$/, /_count$/,
+];
+const WRITE_VERB = /(transfer|send|swap|deploy|broadcast|buy|sell|pay|supply|withdraw|borrow|repay|create|delete|register|claim|deposit|stack|boost|unwind|invite|set_|sign|submit|enroll|opt_|file_|preorder|mint|inscribe|approve|revoke|connect|disconnect|rotate|export|import|unlock|lock|start|stop|join|settle|redeem|fund|accept|cancel|counter|append|give|add_|deactivate|record|compile|configure|heal|fill_gap|recover|rebalance|hunter|enable)/;
+function isReadOnly(name) {
+    if (WRITE_VERB.test(name))
+        return false;
+    return READ_PATTERNS.some((p) => p.test(name));
+}
+/** MCP tool -> OpenRouter (OpenAI) function-tool schema (verbatim JSON Schema). */
+function toOpenAITool(tool) {
+    // Clone so we never mutate the tool descriptor handed back by the MCP SDK.
+    const raw = tool.inputSchema ?? {};
+    const schema = { type: "object", properties: {}, ...raw };
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: schema,
+        },
+    };
+}
+function parseArgs(argv) {
+    const opts = {
+        prompt: "",
+        model: process.env.OPENROUTER_MODEL || DEFAULT_MODEL,
+        network: process.env.NETWORK || "mainnet",
+        readOnly: false,
+        allow: new Set(),
+        block: new Set(),
+        maxTurns: 10,
+        listTools: false,
+    };
+    const promptWords = [];
+    const csv = (v) => v.split(",").map((s) => s.trim()).filter(Boolean);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        // Value-taking flags must be followed by a value — otherwise the next loop
+        // iteration would silently consume the following flag (or leave the option
+        // unset, which for a spend cap means the rail is quietly disabled).
+        const value = (flag) => {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("--")) {
+                console.error(`Missing value for ${flag}`);
+                process.exit(1);
+            }
+            return v;
+        };
+        switch (a) {
+            case "--read-only":
+                opts.readOnly = true;
+                break;
+            case "--list-tools":
+                opts.listTools = true;
+                break;
+            case "--model":
+                opts.model = value(a);
+                break;
+            case "--network":
+                opts.network = value(a);
+                break;
+            case "--allow":
+                csv(value(a)).forEach((t) => opts.allow.add(t));
+                break;
+            case "--block":
+                csv(value(a)).forEach((t) => opts.block.add(t));
+                break;
+            case "--max-spend-ustx":
+                opts.maxSpendUstx = value(a);
+                break;
+            case "--max-spend-sats":
+                opts.maxSpendSats = value(a);
+                break;
+            case "--max-turns": {
+                const raw = value(a);
+                const n = parseInt(raw, 10);
+                if (!Number.isInteger(n) || n < 1) {
+                    console.error(`--max-turns must be a positive integer (got "${raw}")`);
+                    process.exit(1);
+                }
+                opts.maxTurns = n;
+                break;
+            }
+            default:
+                if (a.startsWith("--")) {
+                    console.error(`Unknown flag: ${a}`);
+                    process.exit(1);
+                }
+                promptWords.push(a);
+        }
+    }
+    opts.prompt = promptWords.join(" ").trim();
+    return opts;
+}
+/** Apply read-only + allow + block to the raw MCP tool list. */
+function selectTools(tools, opts) {
+    return tools.filter((t) => {
+        if (opts.block.has(t.name))
+            return false;
+        if (opts.allow.has(t.name))
+            return true;
+        if (opts.readOnly)
+            return isReadOnly(t.name);
+        return true;
+    });
+}
+async function callOpenRouter(apiKey, model, messages, tools) {
+    const res = await fetch(OPENROUTER_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://github.com/aibtcdev/aibtc-mcp",
+            "X-Title": "aibtc-mcp bridge",
+        },
+        body: JSON.stringify({ model, messages, tools, tool_choice: "auto" }),
+    });
+    if (!res.ok) {
+        throw new Error(`OpenRouter ${res.status}: ${await res.text()}`);
+    }
+    // OpenRouter can return HTTP 200 with an error payload (rate limit, moderation,
+    // provider failure) and no choices — surface it instead of crashing on [0].
+    const data = (await res.json());
+    const message = data.choices?.[0]?.message;
+    if (!message) {
+        const detail = data.error?.message ?? JSON.stringify(data);
+        throw new Error(`OpenRouter returned no message: ${detail}`);
+    }
+    return message;
+}
+export async function runBridge(argv) {
+    const opts = parseArgs(argv);
+    // Spawn this same binary in plain server mode (no extra args -> MCP server).
+    const serverEnv = {
+        ...process.env,
+        NETWORK: opts.network,
+    };
+    if (opts.maxSpendUstx)
+        serverEnv.SPEND_LIMIT_SESSION_USTX = opts.maxSpendUstx;
+    if (opts.maxSpendSats)
+        serverEnv.SPEND_LIMIT_SESSION_SATS = opts.maxSpendSats;
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [process.argv[1]],
+        env: serverEnv,
+    });
+    const client = new Client({ name: "aibtc-openrouter-bridge", version: "1.0.0" });
+    await client.connect(transport);
+    const { tools: allTools } = await client.listTools();
+    const exposed = selectTools(allTools, opts);
+    if (opts.listTools) {
+        console.log(`Exposed ${exposed.length}/${allTools.length} tools` +
+            (opts.readOnly ? " (read-only)" : "") + ":");
+        for (const t of exposed)
+            console.log(`  ${t.name}`);
+        await client.close();
+        return;
+    }
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+        console.error("Set OPENROUTER_API_KEY (or use --list-tools to preview without a model).");
+        await client.close();
+        process.exit(1);
+    }
+    if (!opts.prompt) {
+        console.error('Provide a prompt, e.g. aibtc-mcp-server bridge "what is the STX balance of SP3..."');
+        await client.close();
+        process.exit(1);
+    }
+    const writeCount = exposed.filter((t) => !isReadOnly(t.name)).length;
+    console.error(`Bridge: ${exposed.length} tools -> ${opts.model}` +
+        (opts.readOnly ? " [read-only]" : ` [${writeCount} can write/spend]`) +
+        (opts.maxSpendUstx || opts.maxSpendSats
+            ? ` (cap ${opts.maxSpendUstx ?? "-"} uSTX / ${opts.maxSpendSats ?? "-"} sats)`
+            : ""));
+    const openaiTools = exposed.map(toOpenAITool);
+    const messages = [
+        {
+            role: "system",
+            content: "You are an agent with access to aibtc-mcp tools for Stacks/Bitcoin and " +
+                "x402 actions. Use tools when needed. Be concise.",
+        },
+        { role: "user", content: opts.prompt },
+    ];
+    try {
+        let completed = false;
+        for (let turn = 0; turn < opts.maxTurns; turn++) {
+            const reply = await callOpenRouter(apiKey, opts.model, messages, openaiTools);
+            messages.push(reply);
+            const toolCalls = reply.tool_calls ?? [];
+            if (toolCalls.length === 0) {
+                console.log("\n" + (reply.content ?? ""));
+                completed = true;
+                break;
+            }
+            for (const call of toolCalls) {
+                const name = call.function.name;
+                // Enforce the allowlist at execution time too — never trust the model
+                // to stay inside the exposed set.
+                if (!exposed.some((t) => t.name === name)) {
+                    messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        name,
+                        content: `Tool ${name} is not permitted by the bridge.`,
+                    });
+                    continue;
+                }
+                let args = {};
+                try {
+                    args = JSON.parse(call.function.arguments || "{}");
+                }
+                catch {
+                    /* malformed JSON -> empty args */
+                }
+                console.error(`-> ${name}(${call.function.arguments || "{}"})`);
+                let content;
+                try {
+                    const result = await client.callTool({ name, arguments: args });
+                    content = (result.content ?? [])
+                        .map((c) => (c?.type === "text" ? c.text : JSON.stringify(c)))
+                        .join("\n");
+                }
+                catch (err) {
+                    content = `Tool error: ${err.message}`;
+                }
+                messages.push({ role: "tool", tool_call_id: call.id, name, content });
+            }
+        }
+        // Don't let the cap swallow the session silently — the model was still
+        // calling tools when we ran out of turns.
+        if (!completed) {
+            console.error(`Bridge: reached --max-turns limit (${opts.maxTurns}) without a final response. ` +
+                "Re-run with a higher --max-turns to let it finish.");
+        }
+    }
+    finally {
+        await client.close();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js

@@ -229,6 +229,16 @@ if (process.argv[2] === "yield-hunter") {
         process.exit(1);
     });
 }
+// Check for bridge command (OpenRouter <-> MCP)
+else if (process.argv[2] === "bridge") {
+    import("./bridge/index.js")
+        .then(({ runBridge }) => runBridge(process.argv.slice(3)))
+        .then(() => process.exit(0))
+        .catch((error) => {
+        console.error("❌ Bridge error:", redactSensitive(String(error)));
+        process.exit(1);
+    });
+}
 // Check for --install flag
 else if (process.argv.includes("--install") || process.argv.includes("install")) {
     runInstall()

package/dist/services/spend-limiter.d.ts

@@ -0,0 +1,45 @@
+export type SpendUnit = "ustx" | "sats";
+export declare class SpendLimitError extends Error {
+    readonly unit: SpendUnit;
+    readonly attempted: number;
+    readonly remaining: number;
+    readonly scope: "session" | "day";
+    constructor(message: string, unit: SpendUnit, attempted: number, remaining: number, scope: "session" | "day");
+}
+declare class SpendLimiter {
+    private static instance;
+    private stateFile;
+    private session;
+    private writeLock;
+    static getInstance(): SpendLimiter;
+    /** Test seam: redirect the state file. */
+    setStateFile(file: string): void;
+    private readState;
+    private writeState;
+    private getSession;
+    /** Reset the in-memory session ledger for a wallet (call on unlock/lock/switch). */
+    resetSession(addr: string): void;
+    /**
+     * Throw SpendLimitError if `amount` would push the session OR day total over
+     * its cap. Does NOT record — call recordSpend after a successful broadcast.
+     */
+    check(unit: SpendUnit, amount: bigint, addr: string): Promise<void>;
+    /** Record a completed spend against both the session and day ledgers. */
+    record(unit: SpendUnit, amount: bigint, addr: string): Promise<void>;
+    /** Remaining session/day budget for status reporting. */
+    status(addr: string): Promise<{
+        enabled: boolean;
+        ustx: {
+            sessionRemaining: number;
+            dailyRemaining: number;
+        };
+        sats: {
+            sessionRemaining: number;
+            dailyRemaining: number;
+        };
+    }>;
+    private message;
+}
+export declare function getSpendLimiter(): SpendLimiter;
+export {};
+//# sourceMappingURL=spend-limiter.d.ts.map

package/dist/services/spend-limiter.js

@@ -0,0 +1,218 @@
+/**
+ * Default-on cumulative spending limit for the wallet.
+ *
+ * The MCP server lets an LLM move real funds with no human click-through, so a
+ * single poisoned instruction (or a malicious x402 endpoint) could otherwise
+ * drain the wallet. This module is the safety rail: every outbound spend path
+ * (native STX transfer, BTC L1 transfer, x402/L402 auto-payments, Lightning
+ * pays) routes through it, and the limiter blocks once cumulative outflow would
+ * exceed a per-session OR per-day cap.
+ *
+ * Two independent ledgers are tracked — micro-STX (`ustx`) and satoshis
+ * (`sats`); there is no cross-asset USD normalization. Daily totals are
+ * persisted to ~/.aibtc/spend-state.json (keyed by wallet address + UTC day) so
+ * the cap survives process restarts; session totals live in memory and reset on
+ * wallet unlock/lock/switch.
+ *
+ * Exceeding the cap is the intended human-in-the-loop checkpoint: it blocks and
+ * surfaces the remaining budget + the env var to raise. An LLM cannot set env
+ * vars mid-session, so it cannot raise its own ceiling.
+ *
+ * Disable entirely with SPEND_LIMIT_ENABLED=false. Override caps with
+ * SPEND_LIMIT_DAILY_USTX / _SESSION_USTX / _DAILY_SATS / _SESSION_SATS.
+ */
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+const STORAGE_DIR = path.join(os.homedir(), ".aibtc");
+const DEFAULT_STATE_FILE = path.join(STORAGE_DIR, "spend-state.json");
+/**
+ * Parse a positive-integer env override, falling back (with a warning) on any
+ * invalid value — never silently disable a cap. Mirrors parseSatsCap in
+ * x402.service.ts.
+ */
+function parseLimit(envName, fallback) {
+    const raw = process.env[envName];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        console.error(`[spend-limit] Invalid ${envName}="${raw}", falling back to ${fallback}`);
+        return fallback;
+    }
+    return Math.floor(parsed);
+}
+function isEnabled() {
+    return process.env.SPEND_LIMIT_ENABLED !== "false";
+}
+// Conservative defaults (~$30/day at the time of writing): tight enough to stop
+// a drain, generous for the micro-payment use case (registry endpoints cost
+// <=0.02 STX / 100 sats). Raise per wallet via env.
+const DEFAULTS = {
+    dailyUstx: 10_000_000, // 10 STX
+    sessionUstx: 10_000_000, // 10 STX
+    dailySats: 50_000, // ~$30 BTC
+    sessionSats: 50_000,
+};
+function capsFor(unit) {
+    if (unit === "ustx") {
+        return {
+            daily: parseLimit("SPEND_LIMIT_DAILY_USTX", DEFAULTS.dailyUstx),
+            session: parseLimit("SPEND_LIMIT_SESSION_USTX", DEFAULTS.sessionUstx),
+        };
+    }
+    return {
+        daily: parseLimit("SPEND_LIMIT_DAILY_SATS", DEFAULTS.dailySats),
+        session: parseLimit("SPEND_LIMIT_SESSION_SATS", DEFAULTS.sessionSats),
+    };
+}
+/** UTC day bucket, e.g. "2026-06-11". */
+function todayKey() {
+    return new Date().toISOString().slice(0, 10);
+}
+function unitLabel(unit) {
+    return unit === "ustx" ? "uSTX" : "sats";
+}
+export class SpendLimitError extends Error {
+    unit;
+    attempted;
+    remaining;
+    scope;
+    constructor(message, unit, attempted, remaining, scope) {
+        super(message);
+        this.unit = unit;
+        this.attempted = attempted;
+        this.remaining = remaining;
+        this.scope = scope;
+        this.name = "SpendLimitError";
+    }
+}
+class SpendLimiter {
+    static instance;
+    stateFile = DEFAULT_STATE_FILE;
+    // In-memory per-session totals, keyed by wallet address.
+    session = new Map();
+    writeLock = Promise.resolve();
+    static getInstance() {
+        if (!SpendLimiter.instance)
+            SpendLimiter.instance = new SpendLimiter();
+        return SpendLimiter.instance;
+    }
+    /** Test seam: redirect the state file. */
+    setStateFile(file) {
+        this.stateFile = file;
+    }
+    async readState() {
+        try {
+            const content = await fs.readFile(this.stateFile, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeState(state) {
+        const dir = path.dirname(this.stateFile);
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const tmp = `${this.stateFile}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+        await fs.rename(tmp, this.stateFile);
+    }
+    getSession(addr) {
+        let s = this.session.get(addr);
+        if (!s) {
+            s = { ustx: 0, sats: 0 };
+            this.session.set(addr, s);
+        }
+        return s;
+    }
+    /** Reset the in-memory session ledger for a wallet (call on unlock/lock/switch). */
+    resetSession(addr) {
+        this.session.delete(addr);
+    }
+    /**
+     * Throw SpendLimitError if `amount` would push the session OR day total over
+     * its cap. Does NOT record — call recordSpend after a successful broadcast.
+     */
+    async check(unit, amount, addr) {
+        if (!isEnabled())
+            return;
+        if (amount <= 0n)
+            return;
+        const amt = Number(amount);
+        const { daily, session } = capsFor(unit);
+        const sessionSpent = this.getSession(addr)[unit];
+        if (sessionSpent + amt > session) {
+            const remaining = Math.max(0, session - sessionSpent);
+            throw new SpendLimitError(this.message(unit, amt, remaining, "session", session), unit, amt, remaining, "session");
+        }
+        const state = await this.readState();
+        const daySpent = state[addr]?.[todayKey()]?.[unit] ?? 0;
+        if (daySpent + amt > daily) {
+            const remaining = Math.max(0, daily - daySpent);
+            throw new SpendLimitError(this.message(unit, amt, remaining, "day", daily), unit, amt, remaining, "day");
+        }
+    }
+    /** Record a completed spend against both the session and day ledgers. */
+    async record(unit, amount, addr) {
+        if (!isEnabled())
+            return;
+        if (amount <= 0n)
+            return;
+        const amt = Number(amount);
+        this.getSession(addr)[unit] += amt;
+        // Serialize read-modify-write to avoid lost updates under concurrency.
+        this.writeLock = this.writeLock.then(async () => {
+            const state = await this.readState();
+            const today = todayKey();
+            // Prune stale days so the file does not grow unbounded.
+            for (const a of Object.keys(state)) {
+                for (const day of Object.keys(state[a])) {
+                    if (day !== today)
+                        delete state[a][day];
+                }
+                if (Object.keys(state[a]).length === 0)
+                    delete state[a];
+            }
+            if (!state[addr])
+                state[addr] = {};
+            if (!state[addr][today])
+                state[addr][today] = { ustx: 0, sats: 0 };
+            state[addr][today][unit] += amt;
+            await this.writeState(state);
+        });
+        await this.writeLock;
+    }
+    /** Remaining session/day budget for status reporting. */
+    async status(addr) {
+        const state = await this.readState();
+        const mk = (unit) => {
+            const { daily, session } = capsFor(unit);
+            const sessionSpent = this.session.get(addr)?.[unit] ?? 0;
+            const daySpent = state[addr]?.[todayKey()]?.[unit] ?? 0;
+            return {
+                sessionRemaining: Math.max(0, session - sessionSpent),
+                dailyRemaining: Math.max(0, daily - daySpent),
+            };
+        };
+        return { enabled: isEnabled(), ustx: mk("ustx"), sats: mk("sats") };
+    }
+    message(unit, attempted, remaining, scope, cap) {
+        const envVar = unit === "ustx"
+            ? scope === "day"
+                ? "SPEND_LIMIT_DAILY_USTX"
+                : "SPEND_LIMIT_SESSION_USTX"
+            : scope === "day"
+                ? "SPEND_LIMIT_DAILY_SATS"
+                : "SPEND_LIMIT_SESSION_SATS";
+        const label = unitLabel(unit);
+        return (`Spending limit reached: this ${attempted} ${label} transfer would exceed the ` +
+            `per-${scope} cap of ${cap} ${label} (${remaining} ${label} remaining). ` +
+            `This is a safety rail against draining the wallet. To allow a larger spend, ` +
+            `raise ${envVar} (or set SPEND_LIMIT_ENABLED=false to disable), then retry.`);
+    }
+}
+export function getSpendLimiter() {
+    return SpendLimiter.getInstance();
+}
+//# sourceMappingURL=spend-limiter.js.map

package/dist/services/wallet-manager.js

@@ -5,6 +5,7 @@ import { encrypt, decrypt, generateWalletId, initializeStorage, readWalletIndex,
 import { WalletError, WalletNotFoundError, InvalidPasswordError, InvalidMnemonicError, } from "../utils/errors.js";
 import { NETWORK } from "../config/networks.js";
 import { resetPendingNonce } from "../transactions/builder.js";
+import { getSpendLimiter } from "./spend-limiter.js";
 import { deriveBitcoinAddress, deriveBitcoinKeyPair, deriveTaprootAddress, deriveTaprootKeyPair, deriveNostrKeyPair } from "../utils/bitcoin.js";
 /**
  * Wallet manager singleton - handles wallet creation, encryption, and session management
@@ -170,6 +171,8 @@ class WalletManager {
         await writeAppConfig(config);
         // Reset pending nonce counter so the new session re-syncs with the chain
         await resetPendingNonce(account.address);
+        // Fresh unlock starts a fresh per-session spend budget.
+        getSpendLimiter().resetSession(account.address);
         return account;
     }
     /**
@@ -180,6 +183,8 @@ class WalletManager {
         // Reset pending nonce counter before clearing session
         if (this.session?.account) {
             await resetPendingNonce(this.session.account.address);
+            // Clear the per-session spend budget so the next unlock starts fresh.
+            getSpendLimiter().resetSession(this.session.account.address);
         }
         // Zero out sensitive key buffers before dropping references
         if (this.session?.account) {

package/dist/services/x402.service.js

@@ -5,6 +5,7 @@ import { generateWallet, getStxAddress } from "@stacks/wallet-sdk";
 import { NETWORK, API_URL, getStacksNetwork } from "../config/networks.js";
 import { getNetworkFromStacksChainId } from "../config/caip.js";
 import { getWalletManager } from "./wallet-manager.js";
+import { getSpendLimiter } from "./spend-limiter.js";
 import { formatStx, formatSbtc } from "../utils/formatting.js";
 import { getSbtcService } from "./sbtc.service.js";
 import { getHiroApi } from "./hiro-api.js";
@@ -365,6 +366,13 @@ export async function createApiClient(baseUrl, options) {
                 `of ${L402_MAX_SATS_PER_INVOICE} sats (L402_MAX_SATS_PER_INVOICE). ` +
                 `Refusing to pay.`));
         }
+        // Cumulative spending limit (sats ledger) — bounds a drain-by-loop of
+        // sub-cap L402 invoices. Keyed by the wallet's Stacks address so all sats
+        // spends (BTC L1, sBTC, L402) share one ledger.
+        const l402Addr = getWalletManager().getActiveAccount()?.address;
+        if (l402Addr) {
+            await getSpendLimiter().check("sats", BigInt(amountSats), l402Addr);
+        }
         // Pay the Lightning invoice.
         let payment;
         try {
@@ -373,6 +381,9 @@ export async function createApiClient(baseUrl, options) {
         catch (payErr) {
             return Promise.reject(new Error(`L402 payment failed: ${payErr instanceof Error ? payErr.message : String(payErr)}`));
         }
+        if (l402Addr) {
+            await getSpendLimiter().record("sats", BigInt(amountSats), l402Addr);
+        }
         cacheL402Auth(method, canonicalUrlKey, challenge.macaroon, payment.preimage);
         const originalRequest = error.config;
         originalRequest.headers = originalRequest.headers || {};
@@ -486,6 +497,10 @@ export async function createApiClient(baseUrl, options) {
                 return Promise.reject(new Error(`Network mismatch: endpoint requires ${paymentNetwork} but wallet is configured for ${acct.network}. ` +
                     `Switch to a ${paymentNetwork} wallet or use a ${acct.network} endpoint.`));
             }
+            // Cumulative spending limit: the per-payment cap above bounds a single
+            // 402, but a malicious endpoint can loop sub-cap payments. This blocks
+            // once the session/day total would be exceeded.
+            await getSpendLimiter().check(isSbtc ? "sats" : "ustx", amount, acct.address);
             // Invoke pre-payment callback (e.g. balance check) before signing/broadcasting.
             // If the callback throws, the payment is aborted and the error propagates to the caller.
             if (options?.onBeforePayment) {
@@ -561,6 +576,9 @@ export async function createApiClient(baseUrl, options) {
                 action: "payment_submitted",
                 compatShimUsed: false,
             });
+            // Record the spend against the cumulative ledger now that the signed
+            // payment tx is submitted to the facilitator.
+            await getSpendLimiter().record(isSbtc ? "sats" : "ustx", amount, acct.address);
             // Retry the original request with the payment header
             const originalRequest = error.config;
             originalRequest.headers = originalRequest.headers || {};

package/dist/tools/bitcoin.tools.js

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { NETWORK } from "../config/networks.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { MempoolApi, getMempoolAddressUrl, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
@@ -251,6 +252,9 @@ export function registerBitcoinTools(server) {
             if (!account) {
                 throw new Error("Wallet is not unlocked. Use wallet_unlock first to enable transactions.");
             }
+            // Safety rail: block before signing if this would exceed the wallet's
+            // cumulative spending limit (per-session or per-day).
+            await getSpendLimiter().check("sats", BigInt(amount), account.address);
             if (!account.btcAddress || !account.btcPrivateKey || !account.btcPublicKey) {
                 throw new Error("Bitcoin keys not available. Please unlock your wallet again.");
             }
@@ -308,6 +312,7 @@ export function registerBitcoinTools(server) {
             }, account.btcPrivateKey);
             // Broadcast the transaction
             const txid = await api.broadcastTransaction(txResult.txHex);
+            await getSpendLimiter().record("sats", BigInt(amount), account.address);
             const response = {
                 success: true,
                 txid,

package/dist/tools/news.tools.js

@@ -463,10 +463,11 @@ Fields:
     server.registerTool("news_file_signal", {
         description: `File a signal on a beat at aibtc.news.
 
-Requires an unlocked wallet with a P2WPKH (bc1q) BTC address and sBTC balance
-for the x402 payment. The tool handles the full payment flow:
-1. POST with BIP-322 auth → receive 402 payment challenge
-2. Build sponsored sBTC transfer (relay pays gas)
+Filing is free — no payment required. Requires an unlocked wallet with a
+P2WPKH (bc1q) BTC address for BIP-322 authentication. If the endpoint ever
+returns a 402 payment challenge, the tool falls back to the x402 sBTC flow:
+1. POST with BIP-322 auth → signal filed (or receive 402 payment challenge)
+2. On 402: build sponsored sBTC transfer (relay pays gas)
 3. Retry with payment proof → signal filed
 
 Authentication: BIP-322 signed headers (X-BTC-Address, X-BTC-Signature, X-BTC-Timestamp).

package/dist/transactions/builder.js

@@ -3,6 +3,7 @@ import { hexToBytes } from "@stacks/common";
 import { getStacksNetwork, getApiBaseUrl } from "../config/networks.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { resolveDefaultFee } from "../utils/fee.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { getTrackedNonce, recordNonceUsed, resetTrackedNonce, reconcileWithChain, } from "../services/nonce-tracker.js";
 // ---------------------------------------------------------------------------
 // Pending nonce tracking (unified via SharedNonceTracker, issue #413)
@@ -82,6 +83,9 @@ export function advancePendingNonce(address, nonce, txid = "") {
  * @param fee Optional fee in micro-STX. If omitted, a medium-priority clamped fee is resolved.
  */
 export async function transferStx(account, recipient, amount, memo, fee) {
+    // Safety rail: block before signing if this would exceed the wallet's
+    // cumulative spending limit (per-session or per-day).
+    await getSpendLimiter().check("ustx", amount, account.address);
     const networkName = getStacksNetwork(account.network);
     const nonce = await getNextNonce(account.address, account.network);
     // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
@@ -103,6 +107,7 @@ export async function transferStx(account, recipient, amount, memo, fee) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
     advancePendingNonce(account.address, nonce, broadcastResponse.txid);
+    await getSpendLimiter().record("ustx", amount, account.address);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",
@@ -14,6 +14,7 @@
     "dev": "tsx src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prepare": "git config core.hooksPath >/dev/null 2>&1 || git config core.hooksPath .githooks 2>/dev/null || true",
     "prepublishOnly": "npm run build"
   },
   "files": [

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.59.0 # x-release-please-version
+  version: 1.60.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---