@aibtc/mcp-server 1.73.0 → 1.74.0

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

@@ -1,29 +1,23 @@
 import { McpServer } from "@modelcontextprotocol/server";
 /**
- * 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
- * realistic transfer fee (the sender pays its own gas).
+ * Pre-flight balance check for an sBTC inbox payment.
+ * Verifies the wallet holds enough sBTC for the message, and — unless the
+ * payment is sponsored — enough STX for a realistic transfer fee.
  */
-export declare function checkDirectInboxBalance(address: string, amount: string): Promise<void>;
+export declare function checkDirectInboxBalance(address: string, amount: string, sponsored?: boolean): Promise<void>;
 /**
- * Direct (non-sponsored) x402 inbox messaging.
+ * x402 inbox messaging via the `x402-stacks` client interceptor
+ * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * inbox endpoint settles it through its x402 facilitator.
  *
- * Unlike `send_inbox_message` — which builds a *sponsored* sBTC transfer
- * (`sponsored: true`, `fee: 0n`) so the aibtc relay co-signs and pays the STX
- * gas — this tool uses the standard `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). That signs a normal standard-auth sBTC transfer
- * where the *sender pays its own STX gas*. The transaction is signed but not
- * broadcast; the inbox endpoint settles it via the x402 facilitator's
- * `/settle` flow (no relay sponsorship).
+ * The inbox decides who pays gas. When its 402 advertises `extra.feePayer`,
+ * x402-stacks (>=2.1.0) signs a sponsored sBTC transfer with fee 0 and the
+ * facilitator co-signs and pays the STX gas. Without it, the SDK signs a
+ * standard transfer and the sender pays its own gas.
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
- * branches on `tx.auth.authType`. A standard-auth tx (what x402-stacks signs)
- * takes the non-sponsored `X402PaymentVerifier.settle()` path — the relay never
- * adds a sponsor signature or pays gas.
- *
- * Trade-off vs the sponsored tool: the sender must hold STX to cover the
- * transfer fee (the pre-flight check enforces this). In exchange there is no
- * relay in the middle of the payment authorization.
+ * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
+ * relay `/settle` broadcasts as-is).
  */
 export declare function registerInboxX402Tools(server: McpServer): void;
 //# sourceMappingURL=inbox-x402.tools.d.ts.map

package/dist/tools/inbox-x402.tools.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import axios, { AxiosError } from "axios";
 import { wrapAxiosWithPayment, decodePaymentRequired, decodePaymentResponse, X402_HEADERS, } from "x402-stacks";
 import { getAccount, NETWORK } from "../services/x402.service.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { getSbtcService } from "../services/sbtc.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { getExplorerTxUrl } from "../config/networks.js";
@@ -18,13 +19,13 @@ 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
- * realistic transfer fee (the sender pays its own gas).
+ * Pre-flight balance check for an sBTC inbox payment.
+ * Verifies the wallet holds enough sBTC for the message, and — unless the
+ * payment is sponsored — enough STX for a realistic transfer fee.
  */
-export async function checkDirectInboxBalance(address, amount) {
+export async function checkDirectInboxBalance(address, amount, sponsored = false) {
     const sbtcService = getSbtcService(NETWORK);
     const sbtcBalance = BigInt((await sbtcService.getBalance(address)).balance);
     const required = BigInt(amount);
@@ -33,6 +34,9 @@ export async function checkDirectInboxBalance(address, amount) {
         throw new InsufficientBalanceError(`Insufficient sBTC balance: need ${formatSbtc(amount)}, have ${formatSbtc(sbtcBalance.toString())} (shortfall: ${formatSbtc(shortfall.toString())}). ` +
             `Deposit more sBTC via the bridge at https://bridge.stx.eco or use a different wallet.`, "sBTC", sbtcBalance.toString(), amount, shortfall.toString());
     }
+    // Sponsored: the facilitator pays the gas, so no STX is needed.
+    if (sponsored)
+        return;
     const hiro = getHiroApi(NETWORK);
     const stxBalance = BigInt((await hiro.getStxBalance(address)).balance);
     const fees = await hiro.getMempoolFees();
@@ -53,33 +57,28 @@ export async function checkDirectInboxBalance(address, amount) {
     }
 }
 /**
- * Direct (non-sponsored) x402 inbox messaging.
+ * x402 inbox messaging via the `x402-stacks` client interceptor
+ * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * inbox endpoint settles it through its x402 facilitator.
  *
- * Unlike `send_inbox_message` — which builds a *sponsored* sBTC transfer
- * (`sponsored: true`, `fee: 0n`) so the aibtc relay co-signs and pays the STX
- * gas — this tool uses the standard `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). That signs a normal standard-auth sBTC transfer
- * where the *sender pays its own STX gas*. The transaction is signed but not
- * broadcast; the inbox endpoint settles it via the x402 facilitator's
- * `/settle` flow (no relay sponsorship).
+ * The inbox decides who pays gas. When its 402 advertises `extra.feePayer`,
+ * x402-stacks (>=2.1.0) signs a sponsored sBTC transfer with fee 0 and the
+ * facilitator co-signs and pays the STX gas. Without it, the SDK signs a
+ * standard transfer and the sender pays its own gas.
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
- * branches on `tx.auth.authType`. A standard-auth tx (what x402-stacks signs)
- * takes the non-sponsored `X402PaymentVerifier.settle()` path — the relay never
- * adds a sponsor signature or pays gas.
- *
- * Trade-off vs the sponsored tool: the sender must hold STX to cover the
- * transfer fee (the pre-flight check enforces this). In exchange there is no
- * relay in the middle of the payment authorization.
+ * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
+ * relay `/settle` broadcasts as-is).
  */
 export function registerInboxX402Tools(server) {
     server.registerTool("send_inbox_message_direct", {
         description: "Send a paid x402 message to another agent's inbox on aibtc.com. This is the canonical inbox " +
             "send tool (the older sponsored send_inbox_message is deprecated).\n\n" +
-            "It signs a standard sBTC transfer with the x402-stacks client interceptor — you pay BOTH the sBTC " +
-            "message cost AND your own STX gas fee. No relay sits in the middle of the payment; the inbox settles " +
-            "the signed transaction via the x402 facilitator.\n\n" +
-            "Requires an unlocked wallet holding sBTC (message cost) and STX (gas). Mainnet only.",
+            "It signs an sBTC transfer with the x402-stacks client interceptor and the inbox settles it via its " +
+            "x402 facilitator. When the inbox offers sponsorship (402 `extra.feePayer`), the transfer is gasless — " +
+            "you pay only the sBTC message cost. Otherwise you also pay your own STX gas fee.\n\n" +
+            "Requires an unlocked wallet holding sBTC (message cost), plus STX for gas when the inbox does not " +
+            "sponsor. Mainnet only.",
         inputSchema: z.object({
             recipientBtcAddress: z
                 .string()
@@ -135,13 +134,19 @@ export function registerInboxX402Tools(server) {
                 throw new Error("402 response missing or empty payment-required header");
             }
             const accept = paymentRequired.accepts[0];
-            // Step 2: Pre-flight balance check — sBTC for the message AND a
-            // realistic STX gas budget (sender pays its own fee).
-            await checkDirectInboxBalance(account.address, accept.amount);
+            // The SDK signs a sponsored (fee 0) transfer exactly when the
+            // requirement names a fee payer — mirror its check.
+            const sponsored = typeof accept.extra?.feePayer === "string";
+            // Step 2: Pre-flight balance check — sBTC for the message, plus a
+            // realistic STX gas budget when the sender pays its own fee.
+            await checkDirectInboxBalance(account.address, accept.amount, sponsored);
+            // The message cost is a signed sBTC spend: meter it before signing.
+            const spendLimiter = getSpendLimiter();
+            await spendLimiter.check("sats", BigInt(accept.amount), account.address);
             // Step 3: Build a payment-enabled axios client. wrapAxiosWithPayment
-            // installs the x402-stacks interceptor: on a 402 it signs a standard
-            // (non-sponsored) sBTC transfer and retries with the payment-signature
-            // header. The sender's wallet pays the gas.
+            // installs the x402-stacks interceptor: on a 402 it signs the sBTC
+            // transfer (sponsored or standard, per `extra.feePayer`) and retries
+            // with the payment-signature header.
             const stacksAccount = {
                 address: account.address,
                 privateKey: account.privateKey,
@@ -152,13 +157,16 @@ export function registerInboxX402Tools(server) {
             const response = await api.post(inboxUrl, body, {
                 headers: { "Content-Type": "application/json" },
             });
+            await spendLimiter.record("sats", BigInt(accept.amount), account.address);
             // Step 5: Decode the settlement (txid + payer) from the response header.
             const settlement = decodePaymentResponse(response.headers[X402_HEADERS.PAYMENT_RESPONSE]);
             const txid = settlement?.transaction;
             const payer = settlement?.payer;
             return createJsonResponse({
                 success: true,
-                message: "Message delivered (direct non-sponsored x402)",
+                message: sponsored
+                    ? "Message delivered (x402, gas sponsored)"
+                    : "Message delivered (x402, sender paid gas)",
                 recipient: {
                     btcAddress: recipientBtcAddress,
                     stxAddress: recipientStxAddress,
@@ -166,14 +174,16 @@ export function registerInboxX402Tools(server) {
                 contentLength: content.length,
                 inbox: response.data,
                 payment: {
-                    mode: "direct-x402-nonsponsored",
+                    mode: sponsored ? "x402-sponsored" : "direct-x402-nonsponsored",
                     amount: accept.amount + " sats sBTC",
                     ...(payer && { payer }),
                     ...(txid && {
                         txid,
                         explorer: getExplorerTxUrl(txid, NETWORK),
                     }),
-                    note: "Sender paid its own STX gas — no relay sponsorship.",
+                    note: sponsored
+                        ? `STX gas paid by the inbox facilitator (${accept.extra?.feePayer}).`
+                        : "Sender paid its own STX gas — no relay sponsorship.",
                 },
             });
         }

package/dist/utils/fee.d.ts

@@ -6,6 +6,44 @@
  * fee estimates from the Stacks mempool.
  */
 import type { Network } from "../config/networks.js";
+/**
+ * Fee floor and ceiling clamps by transaction type (in micro-STX).
+ * Prevents absurd fees during mempool spikes while allowing reasonable variation.
+ *
+ * Ceilings are set conservatively:
+ *   token_transfer: 3,000 uSTX (0.003 STX) — simple transfer
+ *   contract_call:  50,000 uSTX (0.05 STX)  — complex contract call
+ *   smart_contract: 50,000 uSTX (0.05 STX)  — deployment
+ * These match the x402-sponsor-relay reference implementation.
+ *
+ * sbtc_transfer is a plain sBTC `transfer` call. It is priced from Hiro's
+ * contract_call tier, whose medium estimate is skewed by heavy calls and sat
+ * at 2.5 STX, so every x402 sBTC payment paid the 0.05 STX ceiling. Mainnet
+ * sBTC transfers confirm at 500-3,000 uSTX.
+ */
+declare const FEE_CLAMPS: {
+    readonly token_transfer: {
+        readonly floor: 180n;
+        readonly ceiling: 3000n;
+    };
+    readonly contract_call: {
+        readonly floor: 3000n;
+        readonly ceiling: 50000n;
+    };
+    readonly sbtc_transfer: {
+        readonly floor: 500n;
+        readonly ceiling: 3000n;
+    };
+    readonly smart_contract: {
+        readonly floor: 10000n;
+        readonly ceiling: 50000n;
+    };
+    readonly all: {
+        readonly floor: 180n;
+        readonly ceiling: 50000n;
+    };
+};
+type FeeTxType = keyof typeof FEE_CLAMPS;
 /**
  * Valid fee preset strings.
  * These map to the mempool fee priorities:
@@ -37,7 +75,7 @@ export declare function isFeePreset(value: string): value is FeePreset;
  * // Undefined - returns undefined (auto-estimate)
  * await resolveFee(undefined, "mainnet") // -> undefined
  */
-export declare function resolveFee(fee: string | undefined, network: Network, txType?: "all" | "token_transfer" | "contract_call" | "smart_contract"): Promise<bigint | undefined>;
+export declare function resolveFee(fee: string | undefined, network: Network, txType?: FeeTxType): Promise<bigint | undefined>;
 /**
  * Resolve a default medium-priority fee for a given transaction type.
  *
@@ -52,5 +90,6 @@ export declare function resolveFee(fee: string | undefined, network: Network, tx
  * @param txType - The transaction type for ceiling/floor selection
  * @returns Fee in micro-STX as bigint
  */
-export declare function resolveDefaultFee(network: Network, txType?: "token_transfer" | "contract_call" | "smart_contract"): Promise<bigint>;
+export declare function resolveDefaultFee(network: Network, txType?: Exclude<FeeTxType, "all">): Promise<bigint>;
+export {};
 //# sourceMappingURL=fee.d.ts.map

package/dist/utils/fee.js

@@ -15,13 +15,27 @@ import { getHiroApi } from "../services/hiro-api.js";
  *   contract_call:  50,000 uSTX (0.05 STX)  — complex contract call
  *   smart_contract: 50,000 uSTX (0.05 STX)  — deployment
  * These match the x402-sponsor-relay reference implementation.
+ *
+ * sbtc_transfer is a plain sBTC `transfer` call. It is priced from Hiro's
+ * contract_call tier, whose medium estimate is skewed by heavy calls and sat
+ * at 2.5 STX, so every x402 sBTC payment paid the 0.05 STX ceiling. Mainnet
+ * sBTC transfers confirm at 500-3,000 uSTX.
  */
 const FEE_CLAMPS = {
     token_transfer: { floor: 180n, ceiling: 3000n },
     contract_call: { floor: 3000n, ceiling: 50000n },
+    sbtc_transfer: { floor: 500n, ceiling: 3000n },
     smart_contract: { floor: 10000n, ceiling: 50000n },
     all: { floor: 180n, ceiling: 50000n }, // Widest range for aggregate fees
 };
+/** Hiro mempool fee tier each clamp type is estimated from. */
+const FEE_TIER = {
+    token_transfer: "token_transfer",
+    contract_call: "contract_call",
+    sbtc_transfer: "contract_call",
+    smart_contract: "smart_contract",
+    all: "all",
+};
 /**
  * Check if a string is a valid fee preset.
  */
@@ -77,7 +91,7 @@ export async function resolveFee(fee, network, txType = "all") {
         const hiroApi = getHiroApi(network);
         try {
             const mempoolFees = await hiroApi.getMempoolFees();
-            const feeTier = mempoolFees[txType];
+            const feeTier = mempoolFees[FEE_TIER[txType]];
             const priorityKey = presetToPriorityKey(fee);
             const rawFee = BigInt(Math.ceil(feeTier[priorityKey]));
             const clamps = FEE_CLAMPS[txType];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.73.0",
+  "version": "1.74.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",
@@ -74,7 +74,7 @@
     "sbtc": "^0.3.2",
     "tslib": "^2.8.1",
     "ws": "^8.21.0",
-    "x402-stacks": "^2.0.3",
+    "x402-stacks": "^2.1.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/skill/SKILL.md

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