@aibtc/mcp-server 1.58.0 → 1.60.0

package/dist/services/nft.service.js

@@ -1,5 +1,5 @@
 import { uintCV, principalCV } from "@stacks/transactions";
-import { getHiroApi } from "./hiro-api.js";
+import { getHiroApi, HiroApiError } from "./hiro-api.js";
 import { parseContractId } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 import { createNftSendPostCondition } from "../transactions/post-conditions.js";
@@ -51,8 +51,13 @@ export class NftService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            // 4xx means the contract doesn't implement get-owner (or rejects the
+            // call) — that is "no owner". Network/server failures must surface.
+            if (error instanceof HiroApiError && error.status < 500) {
+                return null;
+            }
+            throw error;
         }
     }
     /**
@@ -75,8 +80,12 @@ export class NftService {
                 }
             }
         }
-        catch {
-            // Function may not exist or may fail
+        catch (error) {
+            // 4xx means the contract doesn't implement get-last-token-id —
+            // supply is simply unknown. Network/server failures must surface.
+            if (!(error instanceof HiroApiError && error.status < 500)) {
+                throw error;
+            }
         }
         return {
             contractId,

package/dist/services/pillar-api.service.d.ts

@@ -1,3 +1,11 @@
+/**
+ * HTTP error from the Pillar API, carrying the status code so callers can
+ * treat 4xx ("no such wallet / no position") differently from infra failures.
+ */
+export declare class PillarApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 declare class PillarApiService {
     private baseUrl;
     private apiKey;

package/dist/services/pillar-api.service.js

@@ -1,4 +1,16 @@
 import { PILLAR_API_URL, PILLAR_API_KEY } from "../config/pillar.js";
+/**
+ * HTTP error from the Pillar API, carrying the status code so callers can
+ * treat 4xx ("no such wallet / no position") differently from infra failures.
+ */
+export class PillarApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "PillarApiError";
+    }
+}
 class PillarApiService {
     baseUrl;
     apiKey;
@@ -32,7 +44,7 @@ class PillarApiService {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`Pillar API error (${response.status}): ${errorText}`);
+            throw new PillarApiError(`Pillar API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }

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

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

package/dist/services/spend-limiter.js

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

package/dist/services/wallet-manager.js

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

package/dist/services/x402.service.js

@@ -1,16 +1,18 @@
 import axios from "axios";
-import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, PostConditionMode, } from "@stacks/transactions";
+import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, Pc, PostConditionMode, } from "@stacks/transactions";
 import { decodePaymentRequired, encodePaymentPayload, generatePaymentId, buildPaymentIdentifierExtension, X402_HEADERS, } from "../utils/x402-protocol.js";
 import { generateWallet, getStxAddress } from "@stacks/wallet-sdk";
 import { NETWORK, API_URL, getStacksNetwork } from "../config/networks.js";
 import { getNetworkFromStacksChainId } from "../config/caip.js";
 import { getWalletManager } from "./wallet-manager.js";
+import { getSpendLimiter } from "./spend-limiter.js";
 import { formatStx, formatSbtc } from "../utils/formatting.js";
 import { getSbtcService } from "./sbtc.service.js";
 import { getHiroApi } from "./hiro-api.js";
 import { createHash } from "crypto";
 import { InsufficientBalanceError } from "../utils/errors.js";
 import { getContracts, parseContractId } from "../config/contracts.js";
+import { resolveDefaultFee } from "../utils/fee.js";
 import { classifyCanonicalPaymentStatus, formatCanonicalPaymentStatus, resolveCanonicalPaymentStatus, } from "../utils/x402-payment-state.js";
 import { extractPaymentIdFromPaymentSignature } from "../utils/x402-recovery.js";
 import { emitCanonicalPaymentDecisionLogs, emitCanonicalPaymentPollLogs, emitPaymentLog, } from "../utils/x402-payment-logging.js";
@@ -42,6 +44,16 @@ function parseSatsCap(envName, fallback) {
     return parsed;
 }
 const L402_MAX_SATS_PER_INVOICE = parseSatsCap("L402_MAX_SATS_PER_INVOICE", DEFAULT_L402_MAX_SATS);
+/**
+ * Per-payment caps for the Stacks x402 interceptor, mirroring the L402 cap
+ * above: a malicious endpoint can demand an arbitrary amount in its 402
+ * response and an autoApprove'd call would pay it, bounded only by wallet
+ * balance. Known registry endpoints cost at most 0.02 STX / 100 sats, so the
+ * defaults leave generous headroom. Overridable via env vars.
+ */
+const X402_MAX_USTX_PER_PAYMENT = parseSatsCap("X402_MAX_USTX_PER_PAYMENT", 1_000_000 // 1 STX
+);
+const X402_MAX_SATS_PER_PAYMENT = parseSatsCap("X402_MAX_SATS_PER_PAYMENT", 10_000);
 // Track payment attempts per client instance (auto-cleanup via WeakMap)
 const paymentAttempts = new WeakMap();
 // Track 429 retry counts per client instance
@@ -354,6 +366,13 @@ export async function createApiClient(baseUrl, options) {
                 `of ${L402_MAX_SATS_PER_INVOICE} sats (L402_MAX_SATS_PER_INVOICE). ` +
                 `Refusing to pay.`));
         }
+        // Cumulative spending limit (sats ledger) — bounds a drain-by-loop of
+        // sub-cap L402 invoices. Keyed by the wallet's Stacks address so all sats
+        // spends (BTC L1, sBTC, L402) share one ledger.
+        const l402Addr = getWalletManager().getActiveAccount()?.address;
+        if (l402Addr) {
+            await getSpendLimiter().check("sats", BigInt(amountSats), l402Addr);
+        }
         // Pay the Lightning invoice.
         let payment;
         try {
@@ -362,6 +381,9 @@ export async function createApiClient(baseUrl, options) {
         catch (payErr) {
             return Promise.reject(new Error(`L402 payment failed: ${payErr instanceof Error ? payErr.message : String(payErr)}`));
         }
+        if (l402Addr) {
+            await getSpendLimiter().record("sats", BigInt(amountSats), l402Addr);
+        }
         cacheL402Auth(method, canonicalUrlKey, challenge.macaroon, payment.preimage);
         const originalRequest = error.config;
         originalRequest.headers = originalRequest.headers || {};
@@ -457,6 +479,16 @@ export async function createApiClient(baseUrl, options) {
                 const networks = paymentRequired.accepts.map((a) => a.network).join(", ");
                 return Promise.reject(new Error(`No compatible Stacks payment option found. Available networks: ${networks}`));
             }
+            const tokenType = detectTokenType(selectedOption.asset);
+            const amount = BigInt(selectedOption.amount);
+            const isSbtc = tokenType === "sBTC";
+            const cap = isSbtc ? X402_MAX_SATS_PER_PAYMENT : X402_MAX_USTX_PER_PAYMENT;
+            const unit = isSbtc ? "sats" : "uSTX";
+            if (amount > BigInt(Math.floor(cap))) {
+                return Promise.reject(new Error(`x402 payment of ${amount} ${unit} exceeds the per-payment cap of ${cap} ${unit}. ` +
+                    `If this cost is expected, raise the cap via the ` +
+                    `${isSbtc ? "X402_MAX_SATS_PER_PAYMENT" : "X402_MAX_USTX_PER_PAYMENT"} env var.`));
+            }
             // Lazy-load account on first 402 — free endpoints never reach here
             const acct = await ensureAccount();
             // Verify the payment network matches our configured network
@@ -465,6 +497,10 @@ export async function createApiClient(baseUrl, options) {
                 return Promise.reject(new Error(`Network mismatch: endpoint requires ${paymentNetwork} but wallet is configured for ${acct.network}. ` +
                     `Switch to a ${paymentNetwork} wallet or use a ${acct.network} endpoint.`));
             }
+            // Cumulative spending limit: the per-payment cap above bounds a single
+            // 402, but a malicious endpoint can loop sub-cap payments. This blocks
+            // once the session/day total would be exceeded.
+            await getSpendLimiter().check(isSbtc ? "sats" : "ustx", amount, acct.address);
             // Invoke pre-payment callback (e.g. balance check) before signing/broadcasting.
             // If the callback throws, the payment is aborted and the error propagates to the caller.
             if (options?.onBeforePayment) {
@@ -476,9 +512,11 @@ export async function createApiClient(baseUrl, options) {
                     account: acct,
                 });
             }
-            // Build a sponsored signed transaction (relay pays gas; fee: 0n)
-            const tokenType = detectTokenType(selectedOption.asset);
-            const amount = BigInt(selectedOption.amount);
+            // Build a non-sponsored signed transaction: the sender pays its own
+            // STX gas (fee + nonce auto-estimated by @stacks), and the x402
+            // facilitator simply verifies and broadcasts it. No relay sponsorship
+            // — this is the same tx shape the x402-stacks lib produces, and the
+            // balance check in onBeforePayment already accounts for the gas.
             const networkName = getStacksNetwork(acct.network);
             let transaction;
             if (tokenType === "sBTC") {
@@ -496,9 +534,18 @@ export async function createApiClient(baseUrl, options) {
                     ],
                     senderKey: acct.privateKey,
                     network: networkName,
-                    postConditionMode: PostConditionMode.Allow,
-                    sponsored: true,
-                    fee: 0n,
+                    // The payment amount is known at build time, so pin it: a
+                    // compromised token contract must not be able to pull more.
+                    postConditionMode: PostConditionMode.Deny,
+                    postConditions: [
+                        Pc.principal(acct.address)
+                            .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"),
                 });
             }
             else {
@@ -508,8 +555,7 @@ export async function createApiClient(baseUrl, options) {
                     senderKey: acct.privateKey,
                     network: networkName,
                     memo: "",
-                    sponsored: true,
-                    fee: 0n,
+                    fee: await resolveDefaultFee(acct.network, "token_transfer"),
                 });
             }
             const txHex = "0x" + transaction.serialize();
@@ -530,6 +576,9 @@ export async function createApiClient(baseUrl, options) {
                 action: "payment_submitted",
                 compatShimUsed: false,
             });
+            // Record the spend against the cumulative ledger now that the signed
+            // payment tx is submitted to the facilitator.
+            await getSpendLimiter().record(isSbtc ? "sats" : "ustx", amount, acct.address);
             // Retry the original request with the payment header
             const originalRequest = error.config;
             originalRequest.headers = originalRequest.headers || {};
@@ -716,8 +765,9 @@ export async function checkSufficientBalance(account, amount, asset, sponsored =
             const hiroApiForSbtc = getHiroApi(account.network);
             const stxInfoForSbtc = await hiroApiForSbtc.getStxBalance(account.address);
             const stxBalanceForSbtc = BigInt(stxInfoForSbtc.balance);
-            const sbtcFees = await hiroApiForSbtc.getMempoolFees();
-            const estimatedSbtcFee = BigInt(sbtcFees.contract_call.high_priority);
+            // 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");
             if (stxBalanceForSbtc < estimatedSbtcFee) {
                 const stxShortfall = estimatedSbtcFee - stxBalanceForSbtc;
                 throw new InsufficientBalanceError(`Insufficient STX balance to cover sBTC transfer fee: need ${formatStx(estimatedSbtcFee.toString())} estimated fee, ` +
@@ -733,8 +783,8 @@ export async function checkSufficientBalance(account, amount, asset, sponsored =
     const balance = BigInt(balanceInfo.balance);
     let totalRequired = requiredAmount;
     if (!sponsored) {
-        const mempoolFees = await hiroApi.getMempoolFees();
-        const estimatedFee = BigInt(mempoolFees.contract_call.high_priority);
+        // Same clamped fee the interceptor sets on the STX transfer.
+        const estimatedFee = await resolveDefaultFee(account.network, "token_transfer");
         totalRequired = requiredAmount + estimatedFee;
     }
     if (balance >= totalRequired)

package/dist/tools/bitcoin.tools.js

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { NETWORK } from "../config/networks.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { MempoolApi, getMempoolAddressUrl, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
@@ -33,6 +34,19 @@ async function getBtcAddress(providedAddress) {
     throw new Error("No Bitcoin address provided and wallet is not unlocked. " +
         "Either provide an address or unlock your wallet first.");
 }
+/**
+ * Reject recipient addresses that belong to the other Bitcoin network before
+ * any UTXO fetching. The tx builder (@scure/btc-signer) rejects these too, but
+ * late and with a cryptic bech32/version-byte error.
+ */
+function validateRecipientNetwork(address) {
+    const prefixes = NETWORK === "mainnet" ? ["bc1", "1", "3"] : ["tb1", "m", "n", "2"];
+    if (!prefixes.some((p) => address.startsWith(p))) {
+        throw new Error(`Recipient "${address}" is not a ${NETWORK} address. ` +
+            `Expected a prefix of ${prefixes.join(", ")} — check that the address ` +
+            `matches the configured NETWORK.`);
+    }
+}
 /**
  * Format satoshis as BTC string
  */
@@ -231,12 +245,16 @@ export function registerBitcoinTools(server) {
         },
     }, async ({ recipient, amount, feeRate, includeOrdinals }) => {
         try {
+            validateRecipientNetwork(recipient);
             // Get wallet account (requires unlocked wallet)
             const walletManager = getWalletManager();
             const account = walletManager.getActiveAccount();
             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.");
             }
@@ -294,6 +312,7 @@ export function registerBitcoinTools(server) {
             }, account.btcPrivateKey);
             // Broadcast the transaction
             const txid = await api.broadcastTransaction(txResult.txHex);
+            await getSpendLimiter().record("sats", BigInt(amount), account.address);
             const response = {
                 success: true,
                 txid,

package/dist/tools/endpoint.tools.js

@@ -276,7 +276,9 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
             const api = await createApiClient(parsed.baseUrl, {
                 toolName: "execute_x402_endpoint",
                 onBeforePayment: async (requirements) => {
-                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, true);
+                    // Non-sponsored: sender pays its own gas, so validate STX for the
+                    // fee too (sponsored=false is the default, passed explicitly here).
+                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, false);
                 },
             });
             const response = await api.request({ method, url: parsed.requestPath, params, data });

package/dist/tools/inbox.tools.js

@@ -40,21 +40,18 @@ async function getNextNonce(address) {
     const hiroApi = getHiroApi(NETWORK);
     const accountInfo = await hiroApi.getAccountInfo(address);
     const confirmedNonce = accountInfo.nonce;
+    // The mempool scan is what makes the nonce safe against pending txs —
+    // silently skipping it on failure risks a nonce collision, so let it fail.
     let highestMempoolNonce = -1;
-    try {
-        const mempool = await hiroApi.getMempoolTransactions({
-            sender_address: address,
-            limit: 50,
-        });
-        for (const tx of mempool.results) {
-            if (tx.nonce > highestMempoolNonce) {
-                highestMempoolNonce = tx.nonce;
-            }
+    const mempool = await hiroApi.getMempoolTransactions({
+        sender_address: address,
+        limit: 50,
+    });
+    for (const tx of mempool.results) {
+        if (tx.nonce > highestMempoolNonce) {
+            highestMempoolNonce = tx.nonce;
         }
     }
-    catch {
-        // Non-fatal: fall back to confirmed nonce only
-    }
     const chainNext = Math.max(confirmedNonce, highestMempoolNonce + 1);
     // 3. Reconcile tracker with chain state
     await reconcileWithChain(address, chainNext);