@aibtc/mcp-server 1.72.1 → 1.73.1

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/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/sbtc.service.d.ts

@@ -41,7 +41,8 @@ export declare class SbtcService {
     getBalance(address: string): Promise<SbtcBalance>;
     /**
      * Transfer sBTC to a recipient
-     * @param fee Optional fee in micro-STX. If omitted, fee is auto-estimated.
+     * @param fee Optional fee in micro-STX. If omitted, the sbtc_transfer clamp
+     *            is used rather than callContract's contract_call default.
      */
     transfer(account: Account, recipient: string, amount: bigint, memo?: string, fee?: bigint, sponsored?: boolean): Promise<TransferResult>;
     /**

package/dist/services/sbtc.service.js

@@ -4,6 +4,7 @@ import { getContracts, parseContractId } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 import { sponsoredContractCall } from "../transactions/sponsor-builder.js";
 import { createFungiblePostCondition } from "../transactions/post-conditions.js";
+import { resolveDefaultFee } from "../utils/fee.js";
 // ============================================================================
 // sBTC Service
 // ============================================================================
@@ -33,7 +34,8 @@ export class SbtcService {
     }
     /**
      * Transfer sBTC to a recipient
-     * @param fee Optional fee in micro-STX. If omitted, fee is auto-estimated.
+     * @param fee Optional fee in micro-STX. If omitted, the sbtc_transfer clamp
+     *            is used rather than callContract's contract_call default.
      */
     async transfer(account, recipient, amount, memo, fee, sponsored) {
         const sbtcContract = this.contracts.SBTC_TOKEN;
@@ -57,7 +59,10 @@ export class SbtcService {
         if (sponsored) {
             return sponsoredContractCall(account, contractCallOptions, this.network);
         }
-        return callContract(account, contractCallOptions);
+        return callContract(account, {
+            ...contractCallOptions,
+            fee: fee ?? (await resolveDefaultFee(this.network, "sbtc_transfer")),
+        });
     }
     /**
      * Get sBTC deposit instructions

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/services/tokens.service.js

@@ -1,8 +1,9 @@
 import { uintCV, principalCV, noneCV, someCV, bufferCV } from "@stacks/transactions";
 import { getHiroApi } from "./hiro-api.js";
-import { parseContractId, getWellKnownTokens } from "../config/index.js";
+import { parseContractId, getWellKnownTokens, getContracts } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 import { createFungiblePostCondition } from "../transactions/post-conditions.js";
+import { resolveDefaultFee } from "../utils/fee.js";
 // ============================================================================
 // Tokens Service (SIP-010)
 // ============================================================================
@@ -102,7 +103,13 @@ export class TokensService {
             functionName: "transfer",
             functionArgs,
             postConditions: [postCondition],
-            ...(fee !== undefined && { fee }),
+            // A plain sBTC transfer gets the sbtc_transfer clamp, not the
+            // contract_call default that callContract would apply.
+            ...(fee !== undefined
+                ? { fee }
+                : contractId === getContracts(this.network).SBTC_TOKEN && {
+                    fee: await resolveDefaultFee(this.network, "sbtc_transfer"),
+                }),
         });
     }
     /**

package/dist/services/x402.service.js

@@ -705,10 +705,10 @@ export async function createApiClient(baseUrl, options) {
                             .willSendEq(amount)
                             .ft(contracts.SBTC_TOKEN, "sbtc-token"),
                     ],
-                    // Clamped medium fee — do NOT let @stacks auto-estimate, since
-                    // Hiro's contract_call high_priority tier is polluted by outliers
-                    // (observed >2000 STX). resolveDefaultFee caps it at 0.05 STX.
-                    fee: await resolveDefaultFee(acct.network, "contract_call"),
+                    // Clamped fee — do NOT let @stacks auto-estimate, since Hiro's
+                    // contract_call tiers are polluted by outliers (observed >2000
+                    // STX). The sbtc_transfer clamp caps it at 0.003 STX.
+                    fee: await resolveDefaultFee(acct.network, "sbtc_transfer"),
                 });
             }
             else {
@@ -1062,7 +1062,7 @@ export async function checkSufficientBalance(account, amount, asset, sponsored =
             const stxBalanceForSbtc = BigInt(stxInfoForSbtc.balance);
             // Same clamped fee the interceptor actually sets on the sBTC contract
             // call — so this check is exact, not a high-priority over-estimate.
-            const estimatedSbtcFee = await resolveDefaultFee(account.network, "contract_call");
+            const estimatedSbtcFee = await resolveDefaultFee(account.network, "sbtc_transfer");
             if (stxBalanceForSbtc < estimatedSbtcFee) {
                 const stxShortfall = estimatedSbtcFee - stxBalanceForSbtc;
                 throw new InsufficientBalanceError(`Insufficient STX balance to cover sBTC transfer fee: need ${formatStx(estimatedSbtcFee.toString())} estimated fee, ` +

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);