@aibtc/mcp-server 1.72.1 → 1.73.1

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/inbox-x402.tools.js

@@ -18,7 +18,7 @@ const INBOX_BASE = "https://aibtc.com/api/inbox";
  * We budget against `medium_priority`, capped at this ceiling, so the pre-flight
  * reflects what the transaction will actually cost.
  */
-const MAX_REALISTIC_FEE_USTX = 50000n; // 0.05 STX — generous headroom
+const MAX_REALISTIC_FEE_USTX = 3000n; // 0.003 STX — the sbtc_transfer fee ceiling
 /**
  * Pre-flight balance check for a non-sponsored sBTC inbox payment.
  * Verifies the wallet holds enough sBTC for the message AND enough STX for a

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.