@aibtc/mcp-server 1.72.0 → 1.73.0

package/README.md

@@ -118,7 +118,7 @@ npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet
 
 ### Tool Profiles
 
-Every tool definition is loaded into the model's context, so `--install` writes `AIBTC_TOOLS=core`: a lean core of 25 tools: wallet (including `wallet_rotate_password`), balances, STX/BTC/sBTC transfers, x402 (`list_x402_endpoints`, `probe_x402_endpoint`, `execute_x402_endpoint`) and earning (`earning_opportunities`, `bounty_list/get/submit`, `identity_register`).
+Every tool definition is loaded into the model's context, so `--install` writes `AIBTC_TOOLS=core`: a lean core of 24 tools: wallet (including `wallet_rotate_password`; `wallet_export` is in the `wallet` group so the mnemonic isn't one call away), balances, STX/BTC/sBTC transfers, x402 (`list_x402_endpoints`, `probe_x402_endpoint`, `execute_x402_endpoint`) and earning (`earning_opportunities`, `bounty_list/get/submit`, `identity_register`).
 
 Add groups with `AIBTC_TOOLS=core,defi,ordinals` in the server's `env` (the core is always included), or load everything with `AIBTC_TOOLS=all` / `--profile full`. If `AIBTC_TOOLS` is not set at all, every tool is loaded, so configs written by earlier versions keep all their tools:
 
@@ -584,12 +584,13 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 | `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_USTX` / `SPEND_LIMIT_SESSION_USTX` | STX spend cap per day / per unlock (micro-STX) | `50000000` (50 STX) |
 | `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` | BTC spend cap per day / per unlock (sats) | `50000` |
+| `AIBTC_ALLOW_BLIND_SIGN` | Allow `schnorr_sign_digest` to sign raw digests (a signed sighash spends outside the spending limit) | off |
 
 **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 also `mainnet`.
 
-**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 on spending limits:** A default-on safety rail meters every STX, sBTC and BTC spend (transfers, contract calls, sponsored transactions, x402/L402 auto-payments, Bitcoin broadcasts, `psbt_sign`) 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 before it is signed or broadcast, and the agent is told to ask you. Raise the caps via the env vars above, or disable with `SPEND_LIMIT_ENABLED=false`. The limit runs inside the server: it does not contain an agent with shell access to your machine, so keep spend tools out of your client's auto-approve list. 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).
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import "dotenv/config";
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import "dotenv/config";
 import fs from "fs/promises";
 import path from "path";
 import os from "os";

package/dist/services/bitflow.service.d.ts

@@ -1,6 +1,6 @@
 import { type QuoteResult, type SelectedSwapRoute, KeeperType } from "@bitflowlabs/core-sdk";
 import { type Network } from "../config/index.js";
-import type { Account, TransferResult } from "../transactions/builder.js";
+import { type Account, type TransferResult } from "../transactions/builder.js";
 export interface BitflowTicker {
     ticker_id: string;
     base_currency: string;

package/dist/services/bitflow.service.js

@@ -1,8 +1,8 @@
 import axios from "axios";
 import { BitflowSDK, KeeperType, } from "@bitflowlabs/core-sdk";
-import { makeContractCall, broadcastTransaction, PostConditionMode, hexToCV, cvToJSON, } from "@stacks/transactions";
-import { STACKS_MAINNET, STACKS_TESTNET } from "@stacks/network";
+import { PostConditionMode, hexToCV, cvToJSON, } from "@stacks/transactions";
 import { getBitflowConfig, BITFLOW_PUBLIC_API, } from "../config/index.js";
+import { callContract } from "../transactions/builder.js";
 // ============================================================================
 // Bitflow Service
 // ============================================================================
@@ -305,29 +305,17 @@ export class BitflowService {
             tokenYDecimals: quoteResult.bestRoute.tokenYDecimals,
         };
         const swapParams = await sdk.getSwapParams(swapExecutionData, account.address, slippageTolerance);
-        const network = this.network === "mainnet" ? STACKS_MAINNET : STACKS_TESTNET;
-        const transaction = await makeContractCall({
+        // Through the shared builder so the swap's post conditions are metered by
+        // the spending limit like every other contract call.
+        return callContract(account, {
             contractAddress: swapParams.contractAddress,
             contractName: swapParams.contractName,
             functionName: swapParams.functionName,
             functionArgs: swapParams.functionArgs,
             postConditions: swapParams.postConditions,
-            senderKey: account.privateKey,
-            network,
             postConditionMode: PostConditionMode.Deny,
             ...(fee !== undefined && { fee }),
         });
-        const broadcastResult = await broadcastTransaction({
-            transaction,
-            network,
-        });
-        if ("error" in broadcastResult) {
-            throw new Error(`Broadcast failed: ${broadcastResult.error} - ${broadcastResult.reason}`);
-        }
-        return {
-            txid: broadcastResult.txid,
-            rawTx: transaction.serialize(),
-        };
     }
     // ==========================================================================
     // Keeper Functions (public endpoints)

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

@@ -0,0 +1,39 @@
+/**
+ * Spending-limit metering for Bitcoin L1 transactions.
+ *
+ * Every tool that signs a spend from this wallet's Bitcoin keys meters the
+ * sats that actually leave it: the value of the inputs it owns minus the
+ * outputs that come back to its own SegWit / Taproot addresses. That counts
+ * the payment, the fee and anything else the transaction sends away, whatever
+ * builder produced it.
+ */
+import * as btc from "@scure/btc-signer";
+import type { MempoolApi } from "./mempool-api.js";
+import type { Network } from "../config/networks.js";
+/** The wallet a Bitcoin spend is billed to. */
+export interface BtcSpender {
+    /** Stacks address: the spend limiter's ledger key, shared with STX/sBTC spends. */
+    address: string;
+    btcAddress?: string;
+    taprootAddress?: string;
+}
+/**
+ * Sats a signed raw transaction takes out of the wallet. Input values come
+ * from the previous transactions (mempool or chain), so this holds for any
+ * builder and for inputs the wallet does not own.
+ */
+export declare function btcTxOutflowSats(api: MempoolApi, txHex: string, spender: BtcSpender, network: Network): Promise<bigint>;
+/**
+ * Sats the inputs this wallet just signed in a PSBT take out of it. Metered
+ * at signing, because a signed PSBT can be broadcast by anyone. Every signed
+ * input must carry its prevout amount (witnessUtxo); one without it cannot be
+ * metered, so signing is refused.
+ */
+export declare function psbtOutflowSats(tx: btc.Transaction, signedInputs: number[], spender: BtcSpender, network: Network): bigint;
+/**
+ * Broadcast a signed transaction that spends from this wallet, metered by the
+ * spending limit: refused before broadcast when it would exceed the cap,
+ * recorded once broadcast.
+ */
+export declare function meteredBtcBroadcast(api: MempoolApi, txHex: string, spender: BtcSpender, network: Network): Promise<string>;
+//# sourceMappingURL=btc-spend.d.ts.map

package/dist/services/btc-spend.js

@@ -0,0 +1,99 @@
+/**
+ * Spending-limit metering for Bitcoin L1 transactions.
+ *
+ * Every tool that signs a spend from this wallet's Bitcoin keys meters the
+ * sats that actually leave it: the value of the inputs it owns minus the
+ * outputs that come back to its own SegWit / Taproot addresses. That counts
+ * the payment, the fee and anything else the transaction sends away, whatever
+ * builder produced it.
+ */
+import * as btc from "@scure/btc-signer";
+import { hex } from "@scure/base";
+import { getBtcNetwork } from "../transactions/bitcoin-builder.js";
+import { getSpendLimiter } from "./spend-limiter.js";
+function ownAddresses(spender) {
+    return [spender.btcAddress, spender.taprootAddress].filter((a) => !!a);
+}
+function ownScripts(spender, network) {
+    const decoder = btc.Address(getBtcNetwork(network));
+    return ownAddresses(spender).map((a) => hex.encode(btc.OutScript.encode(decoder.decode(a))));
+}
+/** Sats paid back to the wallet by the transaction's outputs. */
+function ownOutputSats(tx, spender, network) {
+    const own = new Set(ownScripts(spender, network));
+    let total = 0n;
+    for (let i = 0; i < tx.outputsLength; i++) {
+        const out = tx.getOutput(i);
+        if (out.script && out.amount !== undefined && own.has(hex.encode(out.script))) {
+            total += out.amount;
+        }
+    }
+    return total;
+}
+/**
+ * Sats a signed raw transaction takes out of the wallet. Input values come
+ * from the previous transactions (mempool or chain), so this holds for any
+ * builder and for inputs the wallet does not own.
+ */
+export async function btcTxOutflowSats(api, txHex, spender, network) {
+    const tx = btc.Transaction.fromRaw(hex.decode(txHex), {
+        allowUnknownOutputs: true,
+        allowUnknownInputs: true,
+    });
+    const own = new Set(ownAddresses(spender));
+    const prevTxs = new Map();
+    let ownIn = 0n;
+    for (let i = 0; i < tx.inputsLength; i++) {
+        const input = tx.getInput(i);
+        if (!input.txid || input.index === undefined) {
+            throw new Error(`Cannot meter Bitcoin spend: input ${i} has no outpoint.`);
+        }
+        const txid = hex.encode(input.txid);
+        let prev = prevTxs.get(txid);
+        if (!prev) {
+            prev = await api.getTx(txid);
+            prevTxs.set(txid, prev);
+        }
+        const prevOut = prev.vout[input.index];
+        if (!prevOut) {
+            throw new Error(`Cannot meter Bitcoin spend: ${txid}:${input.index} does not exist.`);
+        }
+        if (prevOut.scriptpubkey_address && own.has(prevOut.scriptpubkey_address)) {
+            ownIn += BigInt(prevOut.value);
+        }
+    }
+    const outflow = ownIn - ownOutputSats(tx, spender, network);
+    return outflow > 0n ? outflow : 0n;
+}
+/**
+ * Sats the inputs this wallet just signed in a PSBT take out of it. Metered
+ * at signing, because a signed PSBT can be broadcast by anyone. Every signed
+ * input must carry its prevout amount (witnessUtxo); one without it cannot be
+ * metered, so signing is refused.
+ */
+export function psbtOutflowSats(tx, signedInputs, spender, network) {
+    let ownIn = 0n;
+    for (const idx of signedInputs) {
+        const amount = tx.getInput(idx).witnessUtxo?.amount;
+        if (amount === undefined) {
+            throw new Error(`Cannot meter input ${idx}: it has no witnessUtxo amount, so the spending limit ` +
+                "cannot tell what it spends. Refusing to sign.");
+        }
+        ownIn += amount;
+    }
+    const outflow = ownIn - ownOutputSats(tx, spender, network);
+    return outflow > 0n ? outflow : 0n;
+}
+/**
+ * Broadcast a signed transaction that spends from this wallet, metered by the
+ * spending limit: refused before broadcast when it would exceed the cap,
+ * recorded once broadcast.
+ */
+export async function meteredBtcBroadcast(api, txHex, spender, network) {
+    const amount = await btcTxOutflowSats(api, txHex, spender, network);
+    await getSpendLimiter().check("sats", amount, spender.address);
+    const txid = await api.broadcastTransaction(txHex);
+    await getSpendLimiter().record("sats", amount, spender.address);
+    return txid;
+}
+//# sourceMappingURL=btc-spend.js.map

package/dist/services/sbtc-deposit.service.d.ts

@@ -36,6 +36,7 @@
  *
  * // Step 4: Broadcast and notify
  * const { txid, notification } = await service.broadcastAndNotify(
+ *   { address: stacksAddress, btcAddress: bitcoinAddress }, // billed by the spending limit
  *   signedTxHex,
  *   depositResult.depositScript,
  *   depositResult.reclaimScript,
@@ -60,6 +61,7 @@
  * ```
  */
 import type { Network } from "../config/networks.js";
+import { type BtcSpender } from "./btc-spend.js";
 /**
  * Result from generating a deposit address
  */
@@ -193,13 +195,14 @@ export declare class SbtcDepositService {
      * 1. Broadcasts the signed Bitcoin transaction to the mempool
      * 2. Notifies the Emily API about the deposit (required for sBTC minting)
      *
+     * @param spender - Wallet the deposit is billed to by the spending limit
      * @param signedTxHex - Signed transaction hex string
      * @param depositScript - Deposit script hex (from buildDepositTransaction)
      * @param reclaimScript - Reclaim script hex (from buildDepositTransaction)
      * @param vout - Output index containing the deposit (default: 0)
      * @returns Transaction ID and notification response
      */
-    broadcastAndNotify(signedTxHex: string, depositScript: string, reclaimScript: string, vout?: number): Promise<{
+    broadcastAndNotify(spender: BtcSpender, signedTxHex: string, depositScript: string, reclaimScript: string, vout?: number): Promise<{
         txid: string;
         notification: unknown;
     }>;

package/dist/services/sbtc-deposit.service.js

@@ -36,6 +36,7 @@
  *
  * // Step 4: Broadcast and notify
  * const { txid, notification } = await service.broadcastAndNotify(
+ *   { address: stacksAddress, btcAddress: bitcoinAddress }, // billed by the spending limit
  *   signedTxHex,
  *   depositResult.depositScript,
  *   depositResult.reclaimScript,
@@ -63,6 +64,7 @@ import { SbtcApiClientMainnet, SbtcApiClientTestnet, MAINNET, TESTNET, buildSbtc
 import { getContracts, parseContractId } from "../config/contracts.js";
 import { MempoolApi } from "./mempool-api.js";
 import { UnisatIndexer } from "./unisat-indexer.js";
+import { meteredBtcBroadcast } from "./btc-spend.js";
 /**
  * sBTC Deposit Service
  */
@@ -257,15 +259,16 @@ export class SbtcDepositService {
      * 1. Broadcasts the signed Bitcoin transaction to the mempool
      * 2. Notifies the Emily API about the deposit (required for sBTC minting)
      *
+     * @param spender - Wallet the deposit is billed to by the spending limit
      * @param signedTxHex - Signed transaction hex string
      * @param depositScript - Deposit script hex (from buildDepositTransaction)
      * @param reclaimScript - Reclaim script hex (from buildDepositTransaction)
      * @param vout - Output index containing the deposit (default: 0)
      * @returns Transaction ID and notification response
      */
-    async broadcastAndNotify(signedTxHex, depositScript, reclaimScript, vout) {
-        // Broadcast transaction to Bitcoin network
-        const txid = await this.mempoolApi.broadcastTransaction(signedTxHex);
+    async broadcastAndNotify(spender, signedTxHex, depositScript, reclaimScript, vout) {
+        // Broadcast transaction to Bitcoin network, metered by the spending limit
+        const txid = await meteredBtcBroadcast(this.mempoolApi, signedTxHex, spender, this.network);
         // Notify Emily API about the deposit
         const notification = await this.apiClient.notifySbtc({
             depositScript,
@@ -354,7 +357,7 @@ export class SbtcDepositService {
         // Step 2: Sign transaction via callback
         const signedTxHex = await signTransaction(depositResult.txHex);
         // Step 3: Broadcast and notify
-        return await this.broadcastAndNotify(signedTxHex, depositResult.depositScript, depositResult.reclaimScript, depositResult.vout);
+        return await this.broadcastAndNotify({ address: stacksAddress, btcAddress: bitcoinAddress }, signedTxHex, depositResult.depositScript, depositResult.reclaimScript, depositResult.vout);
     }
 }
 /**

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

@@ -16,13 +16,14 @@
  * 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.
+ * surfaces the remaining budget. Raising the cap is the user's call, made in
+ * the MCP client config; the message tells the agent to ask, never how to
+ * switch the rail off.
  *
  * Disable entirely with SPEND_LIMIT_ENABLED=false. Override caps with
  * SPEND_LIMIT_DAILY_USTX / _SESSION_USTX / _DAILY_SATS / _SESSION_SATS.
  */
-import type { PostCondition } from "@stacks/transactions";
+import { PostConditionMode, type PostCondition } from "@stacks/transactions";
 export type SpendUnit = "ustx" | "sats";
 /**
  * Read spend ceilings out of a contract call's post conditions.
@@ -52,6 +53,37 @@ export declare function totalBoundedSpends(postConditions: PostCondition[] | und
     unit: SpendUnit;
     amount: bigint;
 }>;
+/**
+ * Ceilings a contract call in post-condition mode Allow declares for the
+ * caller's own STX and sBTC. Allow lets the contract move assets that no post
+ * condition names, so the caller's outflow is only bounded if the call itself
+ * says so: callContract turns these into chain-enforced `lte` post conditions
+ * on the caller and meters them.
+ */
+export interface CallerSpendCaps {
+    ustx: bigint;
+    sats: bigint;
+}
+/**
+ * Work out what a contract call may spend, and the post conditions that make
+ * the chain enforce it. Throws when the call's caller-owned STX/sBTC outflow
+ * has no upper bound, because the rail could not meter it:
+ * - Deny mode with a `gt`/`gte` condition on the caller's STX or sBTC (a floor
+ *   that permits any larger amount);
+ * - Allow mode without `callerSpendCaps`.
+ */
+export declare function planContractCallSpends(options: {
+    postConditionMode?: PostConditionMode;
+    postConditions?: PostCondition[];
+    callerSpendCaps?: CallerSpendCaps;
+    sbtcContract: `${string}.${string}`;
+}, accountAddress: string): {
+    postConditions: PostCondition[];
+    spends: Array<{
+        unit: SpendUnit;
+        amount: bigint;
+    }>;
+};
 export declare class SpendLimitError extends Error {
     readonly unit: SpendUnit;
     readonly attempted: number;

package/dist/services/spend-limiter.js

@@ -1,3 +1,29 @@
+/**
+ * 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, and contract calls carrying a bounded caller-owned post condition)
+ * 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. Raising the cap is the user's call, made in
+ * the MCP client config; the message tells the agent to ask, never how to
+ * switch the rail off.
+ *
+ * Disable entirely with SPEND_LIMIT_ENABLED=false. Override caps with
+ * SPEND_LIMIT_DAILY_USTX / _SESSION_USTX / _DAILY_SATS / _SESSION_SATS.
+ */
+import { Pc, PostConditionMode } from "@stacks/transactions";
 import { promises as fs } from "fs";
 import os from "os";
 import path from "path";
@@ -59,6 +85,41 @@ export function totalBoundedSpends(postConditions, accountAddress) {
     }
     return [...totals].map(([unit, amount]) => ({ unit, amount }));
 }
+/**
+ * Work out what a contract call may spend, and the post conditions that make
+ * the chain enforce it. Throws when the call's caller-owned STX/sBTC outflow
+ * has no upper bound, because the rail could not meter it:
+ * - Deny mode with a `gt`/`gte` condition on the caller's STX or sBTC (a floor
+ *   that permits any larger amount);
+ * - Allow mode without `callerSpendCaps`.
+ */
+export function planContractCallSpends(options, accountAddress) {
+    const postConditions = [...(options.postConditions ?? [])];
+    for (const condition of postConditions) {
+        const pc = condition;
+        if (pc.address !== accountAddress)
+            continue;
+        if (pc.condition !== "gt" && pc.condition !== "gte")
+            continue;
+        const metered = pc.type === "stx-postcondition" ||
+            (pc.type === "ft-postcondition" && pc.asset !== undefined && SBTC_ASSETS.has(pc.asset));
+        if (metered) {
+            throw new Error(`A "${pc.condition}" post condition on this wallet's own ${pc.type === "stx-postcondition" ? "STX" : "sBTC"} ` +
+                "sets no upper bound, so the spending limit cannot meter it. Use eq, lt or lte.");
+        }
+    }
+    const allow = options.postConditionMode === PostConditionMode.Allow;
+    if (allow) {
+        if (!options.callerSpendCaps) {
+            throw new Error("Post condition mode Allow lets the contract move any asset this wallet holds, " +
+                "so the call must declare the most STX and sBTC it may spend (callerSpendCaps).");
+        }
+        const { ustx, sats } = options.callerSpendCaps;
+        const caller = Pc.principal(accountAddress);
+        postConditions.push(caller.willSendLte(ustx).ustx(), caller.willSendLte(sats).ft(options.sbtcContract, "sbtc-token"));
+    }
+    return { postConditions, spends: totalBoundedSpends(postConditions, accountAddress) };
+}
 const STORAGE_DIR = path.join(os.homedir(), ".aibtc");
 const DEFAULT_STATE_FILE = path.join(STORAGE_DIR, "spend-state.json");
 /**
@@ -80,13 +141,12 @@ function parseLimit(envName, fallback) {
 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.
+// Defaults: tight enough to stop a drain, generous for the micro-payment use
+// case (x402 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
+    dailyUstx: 50_000_000, // 50 STX
+    sessionUstx: 50_000_000, // 50 STX
+    dailySats: 50_000,
     sessionSats: 50_000,
 };
 function capsFor(unit) {
@@ -264,10 +324,11 @@ class SpendLimiter {
                 ? "SPEND_LIMIT_DAILY_SATS"
                 : "SPEND_LIMIT_SESSION_SATS";
         const label = unitLabel(unit);
-        return (`Spending limit reached: this ${attempted} ${label} transfer would exceed the ` +
+        return (`Spending limit reached: this ${attempted} ${label} spend 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.`);
+            `This is a safety rail against draining the wallet. Do not try to work around it: ` +
+            `ask the user whether to proceed. Only the user can raise the cap, by setting ` +
+            `${envVar} in this MCP server's config and restarting it.`);
     }
 }
 export function getSpendLimiter() {

package/dist/tools/bitcoin.tools.js

@@ -14,10 +14,10 @@ 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";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 /**
  * Get the Bitcoin address to use for queries.
  * Prefers the provided address, falls back to wallet's btcAddress.
@@ -252,9 +252,6 @@ 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.");
             }
@@ -311,8 +308,7 @@ export function registerBitcoinTools(server) {
                 network: NETWORK,
             }, account.btcPrivateKey);
             // Broadcast the transaction
-            const txid = await api.broadcastTransaction(txResult.txHex);
-            await getSpendLimiter().record("sats", BigInt(amount), account.address);
+            const txid = await meteredBtcBroadcast(api, txResult.txHex, account, NETWORK);
             const response = {
                 success: true,
                 txid,

package/dist/tools/child-inscription.tools.js

@@ -18,6 +18,7 @@ import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { signBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { buildChildCommitTransaction, buildChildRevealTransaction, deriveChildRevealScript, lookupParentInscription, } from "../transactions/child-inscription-builder.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 export function registerChildInscriptionTools(server) {
     // Estimate child inscription fee
     server.registerTool("estimate_child_inscription_fee", {
@@ -168,7 +169,7 @@ export function registerChildInscriptionTools(server) {
                 network: NETWORK,
             });
             const commitSigned = signBtcTransaction(commitResult.tx, account.btcPrivateKey);
-            const commitTxid = await mempoolApi.broadcastTransaction(commitSigned.txHex);
+            const commitTxid = await meteredBtcBroadcast(mempoolApi, commitSigned.txHex, account, NETWORK);
             const commitExplorerUrl = getMempoolTxUrl(commitTxid, NETWORK);
             return createJsonResponse({
                 status: "commit_broadcast",
@@ -306,7 +307,7 @@ export function registerChildInscriptionTools(server) {
             revealResult.tx.sign(account.taprootPrivateKey);
             revealResult.tx.finalize();
             const revealTxHex = revealResult.tx.hex;
-            const revealTxid = await mempoolApi.broadcastTransaction(revealTxHex);
+            const revealTxid = await meteredBtcBroadcast(mempoolApi, revealTxHex, account, NETWORK);
             const inscriptionId = `${revealTxid}i0`;
             const revealExplorerUrl = getMempoolTxUrl(revealTxid, NETWORK);
             const commitExplorerUrl = getMempoolTxUrl(commitTxid, NETWORK);

package/dist/tools/contract.tools.js

@@ -92,7 +92,9 @@ For typed arguments, use objects like {type: 'uint', value: 100} or {type: 'prin
 Post conditions constrain what assets the transaction can move. Each condition is an object:
 - STX: {type: 'stx', principal: 'SP...', conditionCode: 'eq'|'gt'|'gte'|'lt'|'lte', amount: '1000000'}
 - FT: {type: 'ft', principal: 'SP...', asset: 'SP...contract', assetName: 'token-name', conditionCode: 'eq', amount: '1000'}
-- NFT: {type: 'nft', principal: 'SP...', asset: 'SP...contract', assetName: 'nft-name', tokenId: '1', notSend?: boolean}`,
+- NFT: {type: 'nft', principal: 'SP...', asset: 'SP...contract', assetName: 'nft-name', tokenId: '1', notSend?: boolean}
+
+Spending limit: STX and sBTC leaving this wallet are metered against the wallet's spending cap. In 'deny' mode that is read from eq/lt/lte post conditions on this wallet ('gt'/'gte' on this wallet's own STX or sBTC are refused: they set no upper bound). In 'allow' mode, set maxStxSpend / maxSbtcSpend: they are added as on-chain post conditions on this wallet and metered.`,
         inputSchema: z.object({
             contractAddress: z.string().describe("The contract deployer's address (e.g., SP2...)"),
             contractName: z.string().describe("The contract name (e.g., 'my-token')"),
@@ -104,7 +106,17 @@ Post conditions constrain what assets the transaction can move. Each condition i
             postConditionMode: z
                 .enum(["allow", "deny"])
                 .default("deny")
-                .describe("'deny' (default): Blocks unexpected transfers. 'allow': Permits any transfers."),
+                .describe("'deny' (default): Blocks unexpected transfers. 'allow': Permits transfers not covered by a post condition, except this wallet's STX/sBTC, which maxStxSpend/maxSbtcSpend bound."),
+            maxStxSpend: z
+                .string()
+                .regex(/^\d+$/)
+                .default("0")
+                .describe("'allow' mode only: most micro-STX this call may take from this wallet (on-chain post condition, metered). Default 0."),
+            maxSbtcSpend: z
+                .string()
+                .regex(/^\d+$/)
+                .default("0")
+                .describe("'allow' mode only: most sBTC sats this call may take from this wallet (on-chain post condition, metered). Default 0."),
             postConditions: z
                 .array(z.unknown())
                 .optional()
@@ -115,7 +127,7 @@ Post conditions constrain what assets the transaction can move. Each condition i
                 .describe("Optional fee: 'low' | 'medium' | 'high' preset or micro-STX amount. Clamped to 50,000 uSTX max for contract calls. If omitted, medium-priority fee is auto-resolved. Ignored when sponsored=true."),
             sponsored: sponsoredSchema,
         }),
-    }, async ({ contractAddress, contractName, functionName, functionArgs, postConditionMode, postConditions, fee, sponsored }) => {
+    }, async ({ contractAddress, contractName, functionName, functionArgs, postConditionMode, maxStxSpend, maxSbtcSpend, postConditions, fee, sponsored }) => {
         try {
             const account = await getAccount();
             const clarityArgs = functionArgs.map(parseArgToClarityValue);
@@ -130,6 +142,9 @@ Post conditions constrain what assets the transaction can move. Each condition i
                 functionArgs: clarityArgs,
                 postConditionMode: postConditionMode === "allow" ? PostConditionMode.Allow : PostConditionMode.Deny,
                 ...(parsedPostConditions && { postConditions: parsedPostConditions }),
+                ...(postConditionMode === "allow" && {
+                    callerSpendCaps: { ustx: BigInt(maxStxSpend), sats: BigInt(maxSbtcSpend) },
+                }),
             };
             let result;
             if (sponsored) {

package/dist/tools/dual-stacking.tools.js

@@ -311,6 +311,8 @@ Note: Dual Stacking is only available on mainnet.`,
                 functionName: "enroll",
                 functionArgs: [rewardArg],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (enrolling qualifies by holding sBTC; nothing is transferred).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -350,6 +352,7 @@ Note: Dual Stacking is only available on mainnet.`,
                 functionName: "opt-out",
                 functionArgs: [],
                 postConditionMode: PostConditionMode.Allow,
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,

package/dist/tools/jingswap.tools.js

@@ -301,6 +301,8 @@ export function registerJingswapTools(server) {
                 functionName: m.cancelFn,
                 functionArgs: [],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (refund).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
                 postConditions: [],
             });
             return createJsonResponse({
@@ -334,6 +336,8 @@ export function registerJingswapTools(server) {
                 functionName: "cancel-sbtc-deposit",
                 functionArgs: [],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (refund).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
                 postConditions: [],
             });
             return createJsonResponse({
@@ -417,6 +421,8 @@ export function registerJingswapTools(server) {
                 functionName: "settle",
                 functionArgs: [],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (distributes to depositors).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
                 postConditions: [],
             });
             return createJsonResponse({
@@ -479,6 +485,8 @@ export function registerJingswapTools(server) {
                     contractPrincipalCV(PYTH_CONTRACTS.wormhole.address, PYTH_CONTRACTS.wormhole.name),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (the Pyth update fee is ~2 uSTX; 0.001 STX bounds it).
+                callerSpendCaps: { ustx: 1000n, sats: 0n },
                 postConditions: [],
             });
             return createJsonResponse({
@@ -519,6 +527,8 @@ export function registerJingswapTools(server) {
                 functionName: "cancel-cycle",
                 functionArgs: [],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (refunds depositors).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
                 postConditions: [],
             });
             return createJsonResponse({

package/dist/tools/legion.tools.js

@@ -34,6 +34,7 @@ import { buildCommitTransaction, buildRevealTransaction, deriveRevealScript, } f
 import { buildChildCommitTransaction, buildChildRevealTransaction, deriveChildRevealScript, lookupParentInscription, } from "../transactions/child-inscription-builder.js";
 import { signBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { createErrorResponse, createJsonResponse } from "../utils/index.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 // Writes always target the live era. A retired contract still answers reads,
 // but proposing or voting into one would govern a deployment nothing watches.
 const [GOV_ADDRESS, GOV_NAME] = LIVE_ERA.gov.split(".");
@@ -1213,7 +1214,7 @@ export function registerLegionTools(server) {
                     `confirmMainnetSpend: true to proceed, or dryRun: true for the full breakdown.`));
             }
             const commitSigned = signBtcTransaction(commitResult.tx, account.btcPrivateKey);
-            const commitTxid = await mempoolApi.broadcastTransaction(commitSigned.txHex);
+            const commitTxid = await meteredBtcBroadcast(mempoolApi, commitSigned.txHex, account, NETWORK);
             return createJsonResponse({
                 status: "commit_broadcast",
                 bitcoinNetwork: NETWORK,
@@ -1342,7 +1343,7 @@ export function registerLegionTools(server) {
                 revealResult.tx.sign(account.btcPrivateKey);
                 revealResult.tx.sign(account.taprootPrivateKey);
                 revealResult.tx.finalize();
-                revealTxid = await mempoolApi.broadcastTransaction(revealResult.tx.hex);
+                revealTxid = await meteredBtcBroadcast(mempoolApi, revealResult.tx.hex, account, NETWORK);
             }
             else {
                 const revealScript = deriveRevealScript({
@@ -1362,7 +1363,7 @@ export function registerLegionTools(server) {
                     network: NETWORK,
                 });
                 const revealSigned = signBtcTransaction(revealResult.tx, account.btcPrivateKey);
-                revealTxid = await mempoolApi.broadcastTransaction(revealSigned.txHex);
+                revealTxid = await meteredBtcBroadcast(mempoolApi, revealSigned.txHex, account, NETWORK);
             }
             const inscriptionId = `${revealTxid}i0`;
             const link = `${ORDINALS_INSCRIPTION_BASE}${inscriptionId}`;

package/dist/tools/lightning.tools.js

@@ -16,6 +16,7 @@ import { MempoolApi, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
 import { NETWORK } from "../config/networks.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 export function registerLightningTools(server) {
     // --- Wallet lifecycle -----------------------------------------------------
     server.registerTool("lightning_create", {
@@ -207,7 +208,7 @@ export function registerLightningTools(server) {
                 senderAddress: account.btcAddress,
                 network: NETWORK,
             }, account.btcPrivateKey);
-            const txid = await api.broadcastTransaction(txResult.txHex);
+            const txid = await meteredBtcBroadcast(api, txResult.txHex, account, NETWORK);
             const response = {
                 success: true,
                 btcTxid: txid,

package/dist/tools/ordinals.tools.js

@@ -20,6 +20,7 @@ import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { buildCommitTransaction, buildRevealTransaction, deriveRevealScript, } from "../transactions/inscription-builder.js";
 import { signBtcTransaction } from "../transactions/bitcoin-builder.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 /**
  * Format inscription data for display
  */
@@ -209,7 +210,7 @@ export function registerOrdinalsTools(server) {
                 network: NETWORK,
             });
             const commitSigned = signBtcTransaction(commitResult.tx, account.btcPrivateKey);
-            const commitTxid = await mempoolApi.broadcastTransaction(commitSigned.txHex);
+            const commitTxid = await meteredBtcBroadcast(mempoolApi, commitSigned.txHex, account, NETWORK);
             const commitExplorerUrl = getMempoolTxUrl(commitTxid, NETWORK);
             // Return immediately with commit info
             return createJsonResponse({
@@ -343,7 +344,7 @@ export function registerOrdinalsTools(server) {
                 network: NETWORK,
             });
             const revealSigned = signBtcTransaction(revealResult.tx, account.btcPrivateKey);
-            const revealTxid = await mempoolApi.broadcastTransaction(revealSigned.txHex);
+            const revealTxid = await meteredBtcBroadcast(mempoolApi, revealSigned.txHex, account, NETWORK);
             // Inscription ID is reveal txid + output index (always 0 for first inscription)
             const inscriptionId = `${revealTxid}i0`;
             const revealExplorerUrl = getMempoolTxUrl(revealTxid, NETWORK);

package/dist/tools/profiles.d.ts

@@ -9,7 +9,11 @@
  * An unset AIBTC_TOOLS loads every tool: configs written before profiles
  * existed have no AIBTC_TOOLS, and their users keep the tools they had.
  */
-/** Tools exposed by default, whatever groups are enabled. */
+/**
+ * Tools exposed by default, whatever groups are enabled. wallet_export is
+ * deliberately left out: it hands the mnemonic to the agent, which can then
+ * sign outside every spending limit (it stays in the `wallet` group).
+ */
 export declare const CORE_TOOLS: ReadonlySet<string>;
 export declare const TOOL_GROUPS: {
     readonly wallet: "Wallet management extras, encrypted credential store";

package/dist/tools/profiles.js

@@ -9,7 +9,11 @@
  * An unset AIBTC_TOOLS loads every tool: configs written before profiles
  * existed have no AIBTC_TOOLS, and their users keep the tools they had.
  */
-/** Tools exposed by default, whatever groups are enabled. */
+/**
+ * Tools exposed by default, whatever groups are enabled. wallet_export is
+ * deliberately left out: it hands the mnemonic to the agent, which can then
+ * sign outside every spending limit (it stays in the `wallet` group).
+ */
 export const CORE_TOOLS = new Set([
     // Wallet
     "get_wallet_info",
@@ -18,7 +22,6 @@ export const CORE_TOOLS = new Set([
     "wallet_import",
     "wallet_unlock",
     "wallet_lock",
-    "wallet_export",
     "wallet_rotate_password",
     // Balances
     "get_stx_balance",

package/dist/tools/psbt.tools.js

@@ -4,6 +4,8 @@ import { NETWORK } from "../config/networks.js";
 import { DUST_THRESHOLD, P2TR_INPUT_BASE_VBYTES, P2WPKH_INPUT_VBYTES, } from "../config/bitcoin-constants.js";
 import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { psbtOutflowSats } from "../services/btc-spend.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { getBtcNetwork } from "../transactions/bitcoin-builder.js";
 import { createErrorResponse, createJsonResponse } from "../utils/index.js";
 import { estimateBuyPsbtFeeSats, parseOutpoint } from "./psbt.helpers.js";
@@ -284,6 +286,11 @@ export function registerPsbtTools(server) {
                     }
                 }
             }
+            // A signed PSBT can be broadcast by anyone (a marketplace, the
+            // counterparty), so the spend is metered here, before it is handed back.
+            const outflowSats = psbtOutflowSats(tx, signedInputs, account, NETWORK);
+            await getSpendLimiter().check("sats", outflowSats, account.address);
+            await getSpendLimiter().record("sats", outflowSats, account.address);
             return createJsonResponse({
                 success: signedInputs.length > 0,
                 network: NETWORK,

package/dist/tools/runes.tools.js

@@ -28,6 +28,7 @@ import { getWalletManager } from "../services/wallet-manager.js";
 import { MempoolApi, getMempoolAddressUrl, getMempoolTxUrl } from "../services/mempool-api.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
 import { buildRuneTransfer, signRuneTransfer } from "../transactions/rune-transfer-builder.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -444,7 +445,7 @@ export function registerRunesTools(server) {
                 network: NETWORK,
             });
             const signed = signRuneTransfer(transferResult.tx, account.taprootPrivateKey, account.btcPrivateKey, transferResult.taprootInputIndices, transferResult.feeInputIndices);
-            const txid = await mempoolApi.broadcastTransaction(signed.txHex);
+            const txid = await meteredBtcBroadcast(mempoolApi, signed.txHex, account, NETWORK);
             return createJsonResponse({
                 success: true,
                 txid,

package/dist/tools/sbtc.tools.js

@@ -413,7 +413,7 @@ Set includeOrdinals=true to allow spending ordinal UTXOs (advanced users only).`
             reclaimPublicKey, resolvedFeeRate, maxSignerFee, reclaimLockTime, account.btcPrivateKey, // Sign with P2WPKH key (inputs are from user's address)
             includeOrdinals);
             // Step 2: Broadcast signed transaction and notify Emily API
-            const result = await depositService.broadcastAndNotify(depositResult.txHex, depositResult.depositScript, depositResult.reclaimScript, depositResult.vout);
+            const result = await depositService.broadcastAndNotify(account, depositResult.txHex, depositResult.depositScript, depositResult.reclaimScript, depositResult.vout);
             const btcAmount = (amount / 100_000_000).toFixed(8);
             return createJsonResponse({
                 success: true,

package/dist/tools/signing.tools.js

@@ -1187,6 +1187,8 @@ export function registerSigningTools(server) {
             "Use for Taproot script-path spending, multisig coordination, or any case where " +
             "you need a BIP-340 Schnorr signature over a pre-computed hash (e.g., BIP-341 sighash). " +
             "WARNING: This signs raw digests that cannot be human-verified — use confirmBlindSign=true after reviewing the digest. " +
+            "A signed sighash can authorize a Bitcoin spend the spending limit never sees, so the user must also enable it " +
+            "with AIBTC_ALLOW_BLIND_SIGN=true in this server's config. " +
             "Returns a 64-byte signature and the x-only public key. Requires an unlocked wallet.",
         inputSchema: z.object({
             digest: z
@@ -1221,6 +1223,14 @@ export function registerSigningTools(server) {
                         "with the same parameters plus confirmBlindSign: true to proceed with signing.",
                 });
             }
+            // A signature over a BIP-341 sighash authorizes a spend that never
+            // passes a metered broadcast, so the agent cannot enable this itself:
+            // the user opts in in the server config.
+            if (process.env.AIBTC_ALLOW_BLIND_SIGN !== "true") {
+                throw new Error("Blind digest signing is disabled: a signed sighash can spend from this wallet outside " +
+                    "the spending limit. Ask the user to set AIBTC_ALLOW_BLIND_SIGN=true in this MCP " +
+                    "server's config and restart it if they want to allow it.");
+            }
             const account = requireUnlockedWallet();
             if (!account.taprootPrivateKey || !account.taprootPublicKey) {
                 throw new Error("Taproot keys not available. Ensure the wallet has Taproot key derivation.");

package/dist/tools/souldinals.tools.js

@@ -20,6 +20,7 @@ import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { signBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { buildChildCommitTransaction, buildChildRevealTransaction, deriveChildRevealScript, lookupParentInscription, } from "../transactions/child-inscription-builder.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -263,7 +264,7 @@ export function registerSouldinalsTools(server) {
                 network: NETWORK,
             });
             const commitSigned = signBtcTransaction(commitResult.tx, account.btcPrivateKey);
-            const commitTxid = await mempoolApi.broadcastTransaction(commitSigned.txHex);
+            const commitTxid = await meteredBtcBroadcast(mempoolApi, commitSigned.txHex, account, NETWORK);
             const commitExplorerUrl = getMempoolTxUrl(commitTxid, NETWORK);
             return createJsonResponse({
                 status: "commit_broadcast",
@@ -382,7 +383,7 @@ export function registerSouldinalsTools(server) {
             revealResult.tx.sign(account.taprootPrivateKey);
             revealResult.tx.finalize();
             const revealTxHex = revealResult.tx.hex;
-            const revealTxid = await mempoolApi.broadcastTransaction(revealTxHex);
+            const revealTxid = await meteredBtcBroadcast(mempoolApi, revealTxHex, account, NETWORK);
             const inscriptionId = `${revealTxid}i0`;
             const revealExplorerUrl = getMempoolTxUrl(revealTxid, NETWORK);
             const commitExplorerUrl = getMempoolTxUrl(commitTxid, NETWORK);

package/dist/tools/stacking-lottery.tools.js

@@ -247,6 +247,8 @@ Note: Stackspot is only available on mainnet.`,
                 functionName: "join-pot",
                 functionArgs: [uintCV(amountBigInt)],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (the pot entry).
+                callerSpendCaps: { ustx: amountBigInt, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -301,6 +303,8 @@ Note: Stackspot is only available on mainnet.`,
                     contractPrincipalCV(parsed.deployer, parsed.contractName),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (stacks the pot's own STX).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -356,6 +360,8 @@ Note: Stackspot is only available on mainnet.`,
                 // are not known client-side until the contract executes, so strict
                 // post-conditions cannot be set without an additional read-only query.
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (pays out to participants).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -409,6 +415,8 @@ Note: Stackspot is only available on mainnet.`,
                 // to contributors on cancel. The amount is not known client-side without
                 // an additional read-only query, so strict post-conditions are deferred.
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (returns STX to participants).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,

package/dist/tools/stacks-market.tools.js

@@ -336,6 +336,8 @@ Requires an unlocked wallet. Only available on mainnet.`,
                     uintCV(BigInt(max_cost_ustx)),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (max_cost_ustx is the most the market may take).
+                callerSpendCaps: { ustx: BigInt(max_cost_ustx), sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -396,6 +398,8 @@ Requires an unlocked wallet. Only available on mainnet.`,
                     uintCV(BigInt(max_cost_ustx)),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (max_cost_ustx is the most the market may take).
+                callerSpendCaps: { ustx: BigInt(max_cost_ustx), sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -452,6 +456,8 @@ Requires an unlocked wallet. Only available on mainnet.`,
                     uintCV(BigInt(min_proceeds_ustx)),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (pays out to the seller).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -508,6 +514,8 @@ Requires an unlocked wallet. Only available on mainnet.`,
                     uintCV(BigInt(min_proceeds_ustx)),
                 ],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (pays out to the seller).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,
@@ -553,6 +561,8 @@ Requires an unlocked wallet. Only available on mainnet.`,
                 functionName: "redeem",
                 functionArgs: [uintCV(BigInt(market_id))],
                 postConditionMode: PostConditionMode.Allow,
+                // Caller spend caps (pays out winnings).
+                callerSpendCaps: { ustx: 0n, sats: 0n },
             });
             return createJsonResponse({
                 success: true,

package/dist/tools/styx.tools.js

@@ -25,6 +25,7 @@ import { getWalletManager } from "../services/wallet-manager.js";
 import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
 import { getBtcNetwork } from "../transactions/bitcoin-builder.js";
+import { meteredBtcBroadcast } from "../services/btc-spend.js";
 const FEE_PRIORITIES = ["low", "medium", "high"];
 export function registerStyxTools(server) {
     // ---------------------------------------------------------------------------
@@ -250,7 +251,7 @@ export function registerStyxTools(server) {
             tx.finalize();
             // Step 6: Broadcast
             const mempoolApi = new MempoolApi(NETWORK);
-            broadcastTxid = await mempoolApi.broadcastTransaction(tx.hex);
+            broadcastTxid = await meteredBtcBroadcast(mempoolApi, tx.hex, account, NETWORK);
             // Step 7: Update deposit status (retry once on failure)
             let statusUpdateWarning;
             const statusPayload = {

package/dist/transactions/builder.d.ts

@@ -1,5 +1,6 @@
 import { ClarityValue, PostConditionMode, PostCondition } from "@stacks/transactions";
 import { type Network } from "../config/networks.js";
+import { type CallerSpendCaps, type SpendUnit } from "../services/spend-limiter.js";
 import type { WalletAddresses } from "../utils/storage.js";
 /**
  * Reset the pending nonce for an address (called on wallet unlock/lock/switch
@@ -69,6 +70,12 @@ export interface ContractCallOptions {
     functionArgs: ClarityValue[];
     postConditionMode?: PostConditionMode;
     postConditions?: PostCondition[];
+    /**
+     * Required in post condition mode Allow: the most STX (micro-STX) and sBTC
+     * (sats) this call may take from the caller. Enforced on chain as `lte`
+     * post conditions on the caller and metered by the spending limit.
+     */
+    callerSpendCaps?: CallerSpendCaps;
     /** Optional fee in micro-STX. If omitted, fee is auto-estimated. */
     fee?: bigint;
 }
@@ -78,6 +85,16 @@ export interface ContractDeployOptions {
     /** Optional fee in micro-STX. If omitted, fee is auto-estimated. */
     fee?: bigint;
 }
+/** sBTC token contract id for a network, for caller spend post conditions. */
+export declare function sbtcContract(network: Network): `${string}.${string}`;
+/** Add the transaction fee (micro-STX) to the STX ledger of a spend plan. */
+export declare function withFee(spends: Array<{
+    unit: SpendUnit;
+    amount: bigint;
+}>, fee: bigint): Array<{
+    unit: SpendUnit;
+    amount: bigint;
+}>;
 /**
  * Transfer STX tokens to a recipient
  * @param fee Optional fee in micro-STX. If omitted, a medium-priority clamped fee is resolved.

package/dist/transactions/builder.js

@@ -3,7 +3,8 @@ 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, totalBoundedSpends } from "../services/spend-limiter.js";
+import { getSpendLimiter, planContractCallSpends, } from "../services/spend-limiter.js";
+import { getContracts } from "../config/contracts.js";
 import { getTrackedNonce, recordNonceUsed, resetTrackedNonce, reconcileWithChain, } from "../services/nonce-tracker.js";
 // ---------------------------------------------------------------------------
 // Pending nonce tracking (unified via SharedNonceTracker, issue #413)
@@ -78,18 +79,30 @@ export function advancePendingNonce(address, nonce, txid = "") {
         console.error(`[nonce] Failed to record nonce ${nonce} for ${address}:`, err);
     });
 }
+/** sBTC token contract id for a network, for caller spend post conditions. */
+export function sbtcContract(network) {
+    return getContracts(network).SBTC_TOKEN;
+}
+/** Add the transaction fee (micro-STX) to the STX ledger of a spend plan. */
+export function withFee(spends, fee) {
+    const ustx = spends.find((s) => s.unit === "ustx")?.amount ?? 0n;
+    return [
+        ...spends.filter((s) => s.unit !== "ustx"),
+        ...(ustx + fee > 0n ? [{ unit: "ustx", amount: ustx + fee }] : []),
+    ];
+}
 /**
  * Transfer STX tokens to a recipient
  * @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.
     const resolvedFee = fee ?? await resolveDefaultFee(account.network, "token_transfer");
+    // Safety rail: block before signing if the amount plus fee would exceed the
+    // wallet's cumulative spending limit (per-session or per-day).
+    await getSpendLimiter().check("ustx", amount + resolvedFee, account.address);
+    const networkName = getStacksNetwork(account.network);
+    const nonce = await getNextNonce(account.address, account.network);
     const transaction = await makeSTXTokenTransfer({
         recipient,
         amount,
@@ -107,7 +120,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);
+    await getSpendLimiter().record("ustx", amount + resolvedFee, account.address);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -117,20 +130,20 @@ export async function transferStx(account, recipient, amount, memo, fee) {
  * Call a smart contract function
  */
 export async function callContract(account, options) {
+    // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
+    const resolvedFee = options.fee ?? await resolveDefaultFee(account.network, "contract_call");
     // Safety rail. Swaps, lending and pot entries all funnel through here, and
     // their amounts are denominated in whatever token the call moves — there is no
     // ledger to bill 1,000 ALEX against. The post conditions are the way in: they
     // already bound, in native units, how much of each asset may leave this
-    // address. Meter the ones this rail has a ledger for and ignore the rest.
-    // Deliberately before makeContractCall, so an over-cap call never signs.
-    const meteredSpends = totalBoundedSpends(options.postConditions, account.address);
+    // address. Deliberately before makeContractCall, so an over-cap call never signs.
+    const { postConditions, spends } = planContractCallSpends({ ...options, sbtcContract: sbtcContract(account.network) }, account.address);
+    const meteredSpends = withFee(spends, resolvedFee);
     for (const spend of meteredSpends) {
         await getSpendLimiter().check(spend.unit, spend.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.
-    const resolvedFee = options.fee ?? await resolveDefaultFee(account.network, "contract_call");
     const transaction = await makeContractCall({
         contractAddress: options.contractAddress,
         contractName: options.contractName,
@@ -140,7 +153,7 @@ export async function callContract(account, options) {
         network: networkName,
         nonce,
         postConditionMode: options.postConditionMode || PostConditionMode.Deny,
-        postConditions: options.postConditions || [],
+        postConditions,
         fee: resolvedFee,
     });
     const broadcastResponse = await broadcastTransaction({

package/dist/transactions/sponsor-builder.js

@@ -1,7 +1,8 @@
 import { makeSTXTokenTransfer, makeContractCall, makeContractDeploy, PostConditionMode, } from "@stacks/transactions";
 import { getStacksNetwork } from "../config/networks.js";
 import { getSponsorRelayUrl, getSponsorApiKey, isFallbackEnabled } from "../config/sponsor.js";
-import { callContract, transferStx, deployContract } from "./builder.js";
+import { callContract, transferStx, deployContract, sbtcContract } from "./builder.js";
+import { getSpendLimiter, planContractCallSpends } from "../services/spend-limiter.js";
 import { recordNonceUsed } from "../services/nonce-tracker.js";
 import { isRelayHealthy } from "../utils/relay-health.js";
 /**
@@ -99,6 +100,13 @@ async function submitSponsoredTransaction(account, transaction, network, directF
  * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export async function sponsoredContractCall(account, options, network) {
+    // Same rail as callContract: the relay pays the fee, the caller's assets
+    // still leave. Checked before signing; recorded only when the relay takes it,
+    // because the direct fallback (callContract) meters itself.
+    const { postConditions, spends } = planContractCallSpends({ ...options, sbtcContract: sbtcContract(network) }, account.address);
+    for (const spend of spends) {
+        await getSpendLimiter().check(spend.unit, spend.amount, account.address);
+    }
     const transaction = await makeContractCall({
         contractAddress: options.contractAddress,
         contractName: options.contractName,
@@ -107,17 +115,26 @@ export async function sponsoredContractCall(account, options, network) {
         senderKey: account.privateKey,
         network: getStacksNetwork(network),
         postConditionMode: options.postConditionMode || PostConditionMode.Deny,
-        postConditions: options.postConditions || [],
+        postConditions,
         sponsored: true,
         fee: 0n,
     });
-    return submitSponsoredTransaction(account, transaction, network, () => callContract(account, options));
+    const result = await submitSponsoredTransaction(account, transaction, network, () => callContract(account, options));
+    if (!result.fallback) {
+        for (const spend of spends) {
+            await getSpendLimiter().record(spend.unit, spend.amount, account.address);
+        }
+    }
+    return result;
 }
 /**
  * Build and submit a sponsored STX transfer via the relay.
  * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export async function sponsoredStxTransfer(account, recipient, amount, memo, network) {
+    // Checked before signing; recorded only when the relay takes it, because
+    // the direct fallback (transferStx) meters itself.
+    await getSpendLimiter().check("ustx", amount, account.address);
     const transaction = await makeSTXTokenTransfer({
         recipient,
         amount,
@@ -127,7 +144,11 @@ export async function sponsoredStxTransfer(account, recipient, amount, memo, net
         sponsored: true,
         fee: 0n,
     });
-    return submitSponsoredTransaction(account, transaction, network, () => transferStx(account, recipient, amount, memo));
+    const result = await submitSponsoredTransaction(account, transaction, network, () => transferStx(account, recipient, amount, memo));
+    if (!result.fallback) {
+        await getSpendLimiter().record("ustx", amount, account.address);
+    }
+    return result;
 }
 /**
  * Build and submit a sponsored contract deploy via the relay.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.72.0",
+  "version": "1.73.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",
@@ -10,8 +10,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
+    "start": "node --env-file-if-exists=.env dist/index.js",
+    "dev": "tsx --env-file-if-exists=.env 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",
@@ -67,7 +67,6 @@
     "@stacks/wallet-sdk": "^7.2.0",
     "alex-sdk": "^3.2.1",
     "axios": "^1.17.0",
-    "dotenv": "^17.3.1",
     "light-bolt11-decoder": "^3.2.0",
     "micro-ordinals": "^0.3.0",
     "nostr-tools": "^2.23.3",
@@ -81,6 +80,7 @@
   "devDependencies": {
     "@types/node": "^22.19.13",
     "@types/ws": "^8.18.1",
+    "dotenv": "^17.4.2",
     "postcss": "^8.5.18",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

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.72.0 # x-release-please-version
+  version: 1.73.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -121,7 +121,7 @@ Wallets are stored encrypted at `~/.aibtc/`.
 | `btc_sign_message` | Sign plain text with Bitcoin key (BIP-137/BIP-322) | `message`, `addressType` (optional) |
 | `btc_verify_message` | Verify Bitcoin message signature (auto-detects BIP-137/BIP-322) | `message`, `signature`, `address` (optional) |
 | `nostr_sign_event` | Sign a Nostr event (NIP-01) with BIP-340 Schnorr using NIP-06 derived key by default (m/44'/1237'/0'/0/0) | `kind`, `content`, `tags` (optional), `created_at` (optional), `keySource` (`"nostr"` default via NIP-06 path, `"taproot"` for P2TR key, `"segwit"` for P2WPKH key) |
-| `schnorr_sign_digest` | Sign a raw 32-byte digest with Schnorr/BIP-340 | `digest`, `confirmBlindSign`, `auxRand` (optional) |
+| `schnorr_sign_digest` | Sign a raw 32-byte digest with Schnorr/BIP-340 (off unless the user sets `AIBTC_ALLOW_BLIND_SIGN=true`) | `digest`, `confirmBlindSign`, `auxRand` (optional) |
 | `schnorr_verify_digest` | Verify a BIP-340 Schnorr signature over a digest | `digest`, `signature`, `publicKey` |
 
 ## Units and Addresses