@aibtc/mcp-server 1.74.0 → 1.76.0

package/dist/tools/yield-dashboard.tools.js

@@ -13,7 +13,7 @@
  * Mirrors the yield-dashboard skill (aibtcdev/skills/yield-dashboard/).
  */
 import { z } from "zod";
-import { contractPrincipalCV, standardPrincipalCV, uintCV, hexToCV, cvToValue, } from "@stacks/transactions";
+import { contractPrincipalCV, standardPrincipalCV, uintCV, hexToCV, ClarityType, } from "@stacks/transactions";
 import { NETWORK } from "../services/x402.service.js";
 import { getWalletAddress } from "../services/x402.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
@@ -40,30 +40,30 @@ const ALEX_TOKEN_X_NAME = "token-wstx-v2";
 const ALEX_TOKEN_Y_ADDRESS = "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK";
 const ALEX_TOKEN_Y_NAME = "token-abtc";
 const ALEX_FACTOR = 100_000_000;
-// Bitflow public API
-const BITFLOW_API = "https://app.bitflow.finance/api";
 // Mainnet Hiro API base URL (direct — not network-switched, this skill is mainnet-only)
 const MAINNET_HIRO_API = "https://api.hiro.so";
 // ============================================================================
 // Helpers
 // ============================================================================
-function decodeTupleField(result, field) {
-    try {
-        const hex = result.startsWith("0x") ? result.slice(2) : result;
-        const cv = hexToCV(hex);
-        const decoded = cvToValue(cv, true);
-        const val = decoded[field];
-        if (val === undefined || val === null)
-            return null;
-        if (typeof val === "bigint")
-            return val;
-        if (typeof val === "number")
-            return BigInt(val);
-        return null;
+/**
+ * Decode a read-only result that is `(ok (tuple ...))` or a bare tuple and
+ * return its fields as ClarityValues.
+ */
+function decodeTuple(result) {
+    let cv = hexToCV(result.startsWith("0x") ? result.slice(2) : result);
+    if (cv.type === ClarityType.ResponseOk)
+        cv = cv.value;
+    if (cv.type !== ClarityType.Tuple) {
+        throw new Error(`Expected a tuple result, got ${cv.type}`);
     }
-    catch {
-        return null;
+    return cv.value;
+}
+function uintField(fields, name) {
+    const cv = fields[name];
+    if (!cv || cv.type !== ClarityType.UInt) {
+        throw new Error(`Missing uint field "${name}"`);
     }
+    return BigInt(cv.value);
 }
 function formatBtc(sats) {
     return (sats / 1e8).toFixed(8);
@@ -80,7 +80,7 @@ async function readZestPosition(walletAddress) {
         asset: "sBTC",
         valueSats: 0,
         valueUnit: "sats",
-        apyPct: 0,
+        apyPct: null,
         riskScore: 20,
         details: {},
     };
@@ -88,43 +88,28 @@ async function readZestPosition(walletAddress) {
         const hiro = getHiroApi("mainnet");
         const sbtcPrincipal = contractPrincipalCV(SBTC_TOKEN_ADDRESS, SBTC_TOKEN_NAME);
         const res = await hiro.callReadOnlyFunction(ZEST_CONTRACT_ID, "get-reserve-state", [sbtcPrincipal], ZEST_POOL_CONTRACT);
-        if (res.okay && res.result) {
-            const liquidityRate = decodeTupleField(res.result, "current-liquidity-rate");
-            if (liquidityRate !== null && liquidityRate > 0n) {
-                // Ray units: 1e27 = 100%
-                pos.apyPct = Number(liquidityRate) / 1e25;
-            }
-            const borrowsStable = decodeTupleField(res.result, "total-borrows-stable") ?? 0n;
-            const borrowsVariable = decodeTupleField(res.result, "total-borrows-variable") ?? 0n;
-            pos.details.totalBorrows = (borrowsStable + borrowsVariable).toString();
-            // Try to get user a-token balance
-            try {
-                const hex = res.result.startsWith("0x") ? res.result.slice(2) : res.result;
-                const cv = hexToCV(hex);
-                const decoded = cvToValue(cv, true);
-                const aTokenAddr = decoded["a-token-address"];
-                if (aTokenAddr && typeof aTokenAddr === "string" && aTokenAddr.includes(".")) {
-                    const [aTokContract, aTokName] = aTokenAddr.split(".");
-                    const balRes = await hiro.callReadOnlyFunction(`${aTokContract}.${aTokName}`, "ft-get-balance", [standardPrincipalCV(walletAddress)], aTokContract);
-                    if (balRes.okay && balRes.result) {
-                        const balHex = balRes.result.startsWith("0x")
-                            ? balRes.result.slice(2)
-                            : balRes.result;
-                        const balCv = hexToCV(balHex);
-                        const balance = cvToValue(balCv, true);
-                        pos.valueSats =
-                            typeof balance === "bigint"
-                                ? Number(balance)
-                                : typeof balance === "number"
-                                    ? balance
-                                    : 0;
-                    }
-                }
-            }
-            catch {
-                // Position read failed — APY still valid
-            }
+        if (!res.okay || !res.result) {
+            throw new Error(`get-reserve-state failed: ${res.cause ?? "no result"}`);
+        }
+        const reserve = decodeTuple(res.result);
+        // Zest v1 rates are 8-decimal fixed point (one-8 = 1e8 = 100%)
+        pos.apyPct = Number(uintField(reserve, "current-liquidity-rate")) / 1e6;
+        pos.details.totalBorrows = (uintField(reserve, "total-borrows-stable") +
+            uintField(reserve, "total-borrows-variable")).toString();
+        const aToken = reserve["a-token-address"];
+        if (aToken?.type !== ClarityType.PrincipalContract) {
+            throw new Error("get-reserve-state returned no a-token contract");
         }
+        const [aTokContract] = aToken.value.split(".");
+        const balRes = await hiro.callReadOnlyFunction(aToken.value, "get-balance", [standardPrincipalCV(walletAddress)], aTokContract);
+        if (!balRes.okay || !balRes.result) {
+            throw new Error(`${aToken.value} get-balance failed: ${balRes.cause ?? "no result"}`);
+        }
+        const balCv = hexToCV(balRes.result.slice(2));
+        if (balCv.type !== ClarityType.ResponseOk || balCv.value.type !== ClarityType.UInt) {
+            throw new Error(`${aToken.value} get-balance returned an unexpected value`);
+        }
+        pos.valueSats = Number(balCv.value.value);
     }
     catch (e) {
         pos.details.error = String(e);
@@ -137,7 +122,7 @@ async function readAlexPosition(_walletAddress) {
         asset: "aBTC/STX LP",
         valueSats: 0,
         valueUnit: "sats",
-        apyPct: 0,
+        apyPct: null,
         riskScore: 50,
         details: {},
     };
@@ -149,15 +134,14 @@ async function readAlexPosition(_walletAddress) {
             uintCV(ALEX_FACTOR),
         ], ALEX_CONTRACT);
         if (res.okay && res.result) {
-            const balX = decodeTupleField(res.result, "balance-x") ?? 0n;
-            const balY = decodeTupleField(res.result, "balance-y") ?? 0n;
-            const totalSupply = decodeTupleField(res.result, "total-supply") ?? 0n;
+            const pool = decodeTuple(res.result);
+            const balX = uintField(pool, "balance-x");
+            const balY = uintField(pool, "balance-y");
+            const totalSupply = uintField(pool, "total-supply");
             pos.details.poolBalanceX = balX.toString();
             pos.details.poolBalanceY = balY.toString();
             pos.details.poolTotalSupply = totalSupply.toString();
-            // ALEX typical LP APY estimate from fee revenue
-            pos.apyPct = 3.5;
-            pos.details.apySource = "static estimate, not live";
+            pos.details.apySource = "unavailable: no live APY source for ALEX AMM v2";
             pos.details.note =
                 "ALEX AMM v2 does not expose user LP positions via read-only calls. " +
                     `Pool total supply: ${totalSupply.toString()} units. ` +
@@ -176,39 +160,13 @@ async function readBitflowPosition(_walletAddress) {
         asset: "sBTC",
         valueSats: 0,
         valueUnit: "sats",
-        apyPct: 0,
+        apyPct: null,
         riskScore: 35,
         details: {},
     };
-    try {
-        const res = await fetch(`${BITFLOW_API}/pools`, {
-            headers: { Accept: "application/json" },
-        });
-        if (res.ok) {
-            const pools = (await res.json());
-            const sbtcPool = pools.find((p) => (p.token0 && p.token0.toLowerCase().includes("sbtc")) ||
-                (p.token1 && p.token1.toLowerCase().includes("sbtc")));
-            if (sbtcPool) {
-                pos.apyPct = sbtcPool.apy ?? 2.8;
-                pos.details.tvl = sbtcPool.tvl;
-                pos.details.pool = sbtcPool;
-            }
-            else {
-                pos.apyPct = 2.8;
-                pos.details.apySource = "fallback estimate";
-            }
-        }
-        else {
-            pos.apyPct = 2.8;
-            pos.details.apySource = "fallback estimate (API unavailable)";
-        }
-    }
-    catch (e) {
-        pos.apyPct = 2.8;
-        pos.details.error = String(e);
-        pos.details.apySource = "fallback estimate (API unavailable)";
-    }
-    // Bitflow LP position reading requires on-chain query (not yet implemented)
+    // Bitflow's public pools API (app.bitflow.finance/api/pools) is gone and the
+    // SDK gateway exposes no APY/TVL, so there is no live rate to report.
+    pos.details.apySource = "unavailable: Bitflow publishes no pool APY endpoint";
     return pos;
 }
 async function readStackingPosition(walletAddress) {
@@ -217,7 +175,7 @@ async function readStackingPosition(walletAddress) {
         asset: "STX",
         valueSats: 0,
         valueUnit: "microSTX",
-        apyPct: 0,
+        apyPct: null,
         riskScore: 10,
         details: {},
     };
@@ -225,8 +183,7 @@ async function readStackingPosition(walletAddress) {
         const info = await getStackingService("mainnet").getStakerInfo(walletAddress);
         if (info) {
             pos.valueSats = Number(info.amountUstx);
-            pos.apyPct = 8.0;
-            pos.details.apySource = "static estimate, not live";
+            pos.details.apySource = "unavailable: pox-5 rewards are sBTC paid per signer manager";
             pos.details.stakerInfo = {
                 signerManager: info.signerManager,
                 firstRewardCycle: info.firstRewardCycle,
@@ -278,7 +235,8 @@ per-protocol breakdown.
 Read-only. Mainnet-only. Requires an unlocked wallet for address context.
 
 Note: ALEX LP and Bitflow LP position values are 0 — these protocols do not
-expose user LP positions via read-only calls. APY figures are still returned.`,
+expose user LP positions via read-only calls. Only Zest has a live APY; ALEX,
+Bitflow and Stacking report apyPct: null.`,
         inputSchema: z.object({}),
     }, async () => {
         try {
@@ -302,17 +260,24 @@ expose user LP positions via read-only calls. APY figures are still returned.`,
             const stxPositions = positions.filter((p) => p.valueUnit === "microSTX");
             const totalValueSats = satsPositions.reduce((sum, p) => sum + p.valueSats, 0);
             const totalValueMicroStx = stxPositions.reduce((sum, p) => sum + p.valueSats, 0);
-            const weightedApyPct = totalValueSats > 0
-                ? satsPositions.reduce((sum, p) => sum + p.apyPct * (p.valueSats / totalValueSats), 0)
-                : 0;
+            // Weighted only over value whose APY is known; value without a live APY
+            // is reported separately rather than counted at 0% or an estimate.
+            const ratedPositions = satsPositions.filter((p) => p.apyPct !== null);
+            const ratedValueSats = ratedPositions.reduce((sum, p) => sum + p.valueSats, 0);
+            const weightedApyPct = ratedValueSats > 0
+                ? ratedPositions.reduce((sum, p) => sum + p.apyPct * (p.valueSats / ratedValueSats), 0)
+                : null;
             return createJsonResponse({
                 walletAddress,
                 totalValueSats,
                 totalValueBtc: formatBtc(totalValueSats),
                 totalValueMicroStx,
                 totalValueStx: totalValueMicroStx / 1_000_000,
-                weightedApyPct: Math.round(weightedApyPct * 100) / 100,
-                note: "totalValueSats excludes STX stacking (different unit). See totalValueStx separately.",
+                weightedApyPct: weightedApyPct === null ? null : Math.round(weightedApyPct * 100) / 100,
+                unratedValueSats: totalValueSats - ratedValueSats,
+                note: "totalValueSats excludes STX stacking (different unit). See totalValueStx separately. " +
+                    "weightedApyPct covers only positions with a live APY; unratedValueSats is excluded. " +
+                    "apyPct is null where no live source exists.",
                 protocols: {
                     zest: {
                         valueSats: zest.valueSats,
@@ -353,7 +318,8 @@ Read-only. Mainnet-only. Requires an unlocked wallet for address context.
 
 Known limitations:
 - ALEX LP and Bitflow LP: valueSats shows 0 (protocol does not expose user
-  LP balances via read-only calls). APY is still returned.
+  LP balances via read-only calls).
+- apyPct is null for ALEX, Bitflow and Stacking (no live source).
 - Stacking: denominated in microSTX, not sats.`,
         inputSchema: z.object({}),
     }, async () => {
@@ -401,9 +367,9 @@ Bitflow (sBTC LP), and STX Stacking. No wallet required — pure market data.
 
 Data sources:
 - Zest Protocol: on-chain reserve state (current-liquidity-rate, Ray units)
-- ALEX DEX: static 3.5% estimate (pool data available but per-user APY not live)
-- Bitflow: public API at app.bitflow.finance/api/pools (fallback: 2.8% estimate)
-- STX Stacking: static 8.0% estimate
+- ALEX DEX: null — no live APY source
+- Bitflow: null — no public pool APY endpoint
+- STX Stacking: null — pox-5 rewards are sBTC, paid per signer manager
 
 Mainnet data only (contract addresses are mainnet-specific).`,
         inputSchema: z.object({}),
@@ -441,7 +407,7 @@ Mainnet data only (contract addresses are mainnet-specific).`,
                     {
                         protocol: "STX Stacking",
                         asset: "STX",
-                        apyPct: 8.0,
+                        apyPct: null,
                         riskScore: 10,
                     },
                 ],
@@ -518,7 +484,7 @@ Read-only. Mainnet-only. Requires an unlocked wallet for address context.`,
                 suggestions.push("Current allocation is close to optimal for your risk tolerance.");
             }
             const zestApy = positions[0].apyPct;
-            if (zestApy > 6) {
+            if (zestApy !== null && zestApy > 6) {
                 suggestions.push(`Zest APY is elevated at ${zestApy.toFixed(1)}% — good time to increase lending allocation`);
             }
             if (riskLevel !== "high") {

package/dist/transactions/builder.js

@@ -98,29 +98,40 @@ export function withFee(spends, fee) {
 export async function transferStx(account, recipient, amount, memo, fee) {
     // 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);
+    // Safety rail: book the amount plus fee against the wallet's cumulative
+    // spending limit (per-session and per-day) before signing; refused if over.
+    const limiter = getSpendLimiter();
+    const reservation = await limiter.reserve([{ unit: "ustx", amount: amount + resolvedFee }], account.address);
     const networkName = getStacksNetwork(account.network);
-    const nonce = await getNextNonce(account.address, account.network);
-    const transaction = await makeSTXTokenTransfer({
-        recipient,
-        amount,
-        senderKey: account.privateKey,
-        network: networkName,
-        memo: memo || "",
-        nonce,
-        fee: resolvedFee,
-    });
+    let transaction;
+    let nonce;
+    try {
+        nonce = await getNextNonce(account.address, account.network);
+        transaction = await makeSTXTokenTransfer({
+            recipient,
+            amount,
+            senderKey: account.privateKey,
+            network: networkName,
+            memo: memo || "",
+            nonce,
+            fee: resolvedFee,
+        });
+    }
+    catch (error) {
+        await limiter.release(reservation);
+        throw error;
+    }
+    // A throw here (timeout, reset) leaves it unknown whether the node took the
+    // transaction, so the booking stands. Only an explicit rejection gives it back.
     const broadcastResponse = await broadcastTransaction({
         transaction,
         network: networkName,
     });
     if ("error" in broadcastResponse) {
+        await limiter.release(reservation);
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
     advancePendingNonce(account.address, nonce, broadcastResponse.txid);
-    await getSpendLimiter().record("ustx", amount + resolvedFee, account.address);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -138,35 +149,41 @@ export async function callContract(account, options) {
     // already bound, in native units, how much of each asset may leave this
     // 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 limiter = getSpendLimiter();
+    const reservation = await limiter.reserve(withFee(spends, resolvedFee), account.address);
     const networkName = getStacksNetwork(account.network);
-    const nonce = await getNextNonce(account.address, account.network);
-    const transaction = await makeContractCall({
-        contractAddress: options.contractAddress,
-        contractName: options.contractName,
-        functionName: options.functionName,
-        functionArgs: options.functionArgs,
-        senderKey: account.privateKey,
-        network: networkName,
-        nonce,
-        postConditionMode: options.postConditionMode || PostConditionMode.Deny,
-        postConditions,
-        fee: resolvedFee,
-    });
+    let transaction;
+    let nonce;
+    try {
+        nonce = await getNextNonce(account.address, account.network);
+        transaction = await makeContractCall({
+            contractAddress: options.contractAddress,
+            contractName: options.contractName,
+            functionName: options.functionName,
+            functionArgs: options.functionArgs,
+            senderKey: account.privateKey,
+            network: networkName,
+            nonce,
+            postConditionMode: options.postConditionMode || PostConditionMode.Deny,
+            postConditions,
+            fee: resolvedFee,
+        });
+    }
+    catch (error) {
+        await limiter.release(reservation);
+        throw error;
+    }
+    // A throw here (timeout, reset) leaves it unknown whether the node took the
+    // transaction, so the booking stands. Only an explicit rejection gives it back.
     const broadcastResponse = await broadcastTransaction({
         transaction,
         network: networkName,
     });
     if ("error" in broadcastResponse) {
+        await limiter.release(reservation);
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
     advancePendingNonce(account.address, nonce, broadcastResponse.txid);
-    for (const spend of meteredSpends) {
-        await getSpendLimiter().record(spend.unit, spend.amount, account.address);
-    }
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),

package/dist/transactions/sponsor-builder.js

@@ -77,14 +77,25 @@ function resolveSponsorApiKey(account) {
  * Shared logic for all three sponsored helpers (contract call, STX transfer,
  * contract deploy). Each caller builds its own transaction and provides a
  * fallback function for direct submission when the relay is unavailable.
+ * `onNotSent` runs when the transaction provably never left: no API key, or
+ * the relay refused it (before any fallback).
  */
-async function submitSponsoredTransaction(account, transaction, network, directFallback) {
-    const apiKey = resolveSponsorApiKey(account);
+async function submitSponsoredTransaction(account, transaction, network, directFallback, onNotSent = async () => { }) {
+    let apiKey;
+    try {
+        apiKey = resolveSponsorApiKey(account);
+    }
+    catch (error) {
+        await onNotSent();
+        throw error;
+    }
     const senderNonce = Number(transaction.auth.spendingCondition.nonce);
     const serializedTx = transaction.serialize();
     const response = await submitToSponsorRelay(serializedTx, network, apiKey);
     if (!response.success) {
         const { shouldFallback, reason } = await evaluateFallback(response, network);
+        // The relay refused the transaction, so it was not broadcast.
+        await onNotSent();
         if (shouldFallback) {
             console.warn(`[sponsor] Relay unavailable or nonce error (${reason}), falling back to direct submission (sender pays fee)`);
             const result = await directFallback();
@@ -101,54 +112,62 @@ async function submitSponsoredTransaction(account, transaction, network, directF
  */
 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.
+    // still leave. Booked before signing.
     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 limiter = getSpendLimiter();
+    const reservation = await limiter.reserve(spends, account.address);
+    let transaction;
+    try {
+        transaction = await makeContractCall({
+            contractAddress: options.contractAddress,
+            contractName: options.contractName,
+            functionName: options.functionName,
+            functionArgs: options.functionArgs,
+            senderKey: account.privateKey,
+            network: getStacksNetwork(network),
+            postConditionMode: options.postConditionMode || PostConditionMode.Deny,
+            postConditions,
+            sponsored: true,
+            fee: 0n,
+        });
     }
-    const transaction = await makeContractCall({
-        contractAddress: options.contractAddress,
-        contractName: options.contractName,
-        functionName: options.functionName,
-        functionArgs: options.functionArgs,
-        senderKey: account.privateKey,
-        network: getStacksNetwork(network),
-        postConditionMode: options.postConditionMode || PostConditionMode.Deny,
-        postConditions,
-        sponsored: true,
-        fee: 0n,
-    });
-    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);
-        }
+    catch (error) {
+        await limiter.release(reservation);
+        throw error;
     }
-    return result;
+    // Released only when the relay refuses the transaction (before the direct
+    // fallback, which books its own spend). A relay call that throws, or a
+    // failure after the relay accepted it, leaves the booking in place.
+    return submitSponsoredTransaction(account, transaction, network, () => callContract(account, options), () => limiter.release(reservation));
 }
 /**
  * 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,
-        senderKey: account.privateKey,
-        network: getStacksNetwork(network),
-        memo: memo || "",
-        sponsored: true,
-        fee: 0n,
-    });
-    const result = await submitSponsoredTransaction(account, transaction, network, () => transferStx(account, recipient, amount, memo));
-    if (!result.fallback) {
-        await getSpendLimiter().record("ustx", amount, account.address);
+    // Booked before signing.
+    const limiter = getSpendLimiter();
+    const reservation = await limiter.reserve([{ unit: "ustx", amount }], account.address);
+    let transaction;
+    try {
+        transaction = await makeSTXTokenTransfer({
+            recipient,
+            amount,
+            senderKey: account.privateKey,
+            network: getStacksNetwork(network),
+            memo: memo || "",
+            sponsored: true,
+            fee: 0n,
+        });
+    }
+    catch (error) {
+        await limiter.release(reservation);
+        throw error;
     }
-    return result;
+    // Released only when the relay refuses the transaction (before the direct
+    // fallback, which books its own spend). A relay call that throws, or a
+    // failure after the relay accepted it, leaves the booking in place.
+    return submitSponsoredTransaction(account, transaction, network, () => transferStx(account, recipient, amount, memo), () => limiter.release(reservation));
 }
 /**
  * Build and submit a sponsored contract deploy via the relay.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.74.0",
+  "version": "1.76.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",

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.74.0 # x-release-please-version
+  version: 1.76.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -206,8 +206,9 @@ Always probe before executing paid endpoints. Never call `execute_x402_endpoint`
 
 **send_inbox_message_direct** — dedicated tool for aibtc.com inbox messages:
 - Parameters: `recipientBtcAddress` (bc1...), `recipientStxAddress` (SP...), `content` (max 500 chars)
-- Direct (non-sponsored) payment: signs a standard sBTC transfer and settles through the x402 facilitator — no relay in the middle
-- Sender pays BOTH the sBTC message cost AND its own STX gas; requires an unlocked wallet holding sBTC and STX (mainnet only)
+- Gasless: the inbox advertises a fee payer, so the tool signs a sponsored sBTC transfer (fee 0) and the relay pays the STX gas
+- Requires an unlocked wallet holding the sBTC message cost (100 sats) — no STX needed (mainnet only)
+- One pending payment per sender: wait for the previous message's payment to confirm before sending the next
 - Implements the full x402 v2 payment flow with a balance pre-check
 - Note: the older sponsored `send_inbox_message` tool is deprecated and no longer sends — use this tool instead
 

package/skill/references/x402-inbox.md

@@ -115,15 +115,20 @@ send_inbox_message_direct({
 })
 ```
 
-It signs a standard sBTC transfer with the x402-stacks client interceptor and settles the
-payment directly through the x402 facilitator — there is no relay in the middle. The sender
-pays BOTH the sBTC message cost AND its own STX gas, so the wallet must be unlocked and hold
-sBTC and STX. Mainnet only. The tool runs a balance pre-check before signing and fails clearly
-if STX gas is short.
-
-> **Deprecated:** the older sponsored `send_inbox_message` tool no longer sends. It returns a
-> message directing callers to `send_inbox_message_direct`. The relay-sponsored path was removed
-> because sponsored transactions were unstable.
+Inbox sends are **gasless**. The inbox's 402 advertises `extra.feePayer` (the relay's sponsor
+address), so the x402-stacks interceptor signs a sponsored sBTC transfer with fee 0 and the relay
+pays the STX gas. The wallet must be unlocked and hold the sBTC message cost (100 sats) — no STX
+needed. Mainnet only. The tool runs a balance pre-check before signing. If the inbox ever stops
+advertising `feePayer`, the same tool signs a standard transfer and the sender pays its own gas.
+
+Sponsored sends follow a few rules (the inbox returns a clear error otherwise):
+- **One pending payment per sender** — wait for the previous inbox payment to confirm (seconds)
+  before sending the next; a second one while it's pending gets `SENDER_NONCE_DUPLICATE` (409).
+- **Up to 10 sponsored payments per sender per minute** (`RATE_LIMITED`, 429).
+- **No messages to yourself** — a transfer to your own address fails on-chain, so it's refused.
+
+> **Deprecated:** the older `send_inbox_message` tool no longer sends. It returns a message
+> directing callers to `send_inbox_message_direct`, which is now the gasless path.
 
 ## More Information