@aibtc/mcp-server 1.58.0 → 1.59.0

package/dist/index.js

@@ -36,13 +36,24 @@ function getClaudeDesktopConfigPath() {
     }
 }
 async function readJsonConfig(filePath) {
+    let content;
+    try {
+        content = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {}; // No config yet - fresh install
+        }
+        throw error;
+    }
     try {
-        const content = await fs.readFile(filePath, "utf8");
         return JSON.parse(content);
     }
     catch {
-        // File doesn't exist or isn't valid JSON, start fresh
-        return {};
+        // Never silently replace an unparseable config: it may hold the user's
+        // other MCP servers, and "merging" into {} would discard them on write.
+        throw new Error(`Existing config at ${filePath} is not valid JSON. ` +
+            `Fix or remove it, then re-run the install.`);
     }
 }
 async function writeJsonConfig(filePath, config) {
@@ -99,8 +110,10 @@ async function writeCodexToml(configPath, network) {
     try {
         existing = await fs.readFile(configPath, "utf8");
     }
-    catch {
-        existing = "";
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error; // Unreadable existing config must not be clobbered
+        }
     }
     const preserved = stripCodexSection(existing).replace(/\s+$/, "");
     const block = [

package/dist/services/credentials.js

@@ -39,6 +39,7 @@ async function encrypt(data, password) {
     const iv = crypto.randomBytes(12);
     const key = await deriveKey(password, salt);
     const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    key.fill(0); // cipher holds its own copy
     const encrypted = Buffer.concat([cipher.update(data, "utf8"), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return {
@@ -53,6 +54,7 @@ async function encrypt(data, password) {
 async function decrypt(encrypted, password) {
     const key = await deriveKey(password, Buffer.from(encrypted.salt, "base64"));
     const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(encrypted.iv, "base64"));
+    key.fill(0); // decipher holds its own copy
     decipher.setAuthTag(Buffer.from(encrypted.authTag, "base64"));
     const decrypted = Buffer.concat([
         decipher.update(Buffer.from(encrypted.ciphertext, "base64")),
@@ -67,12 +69,15 @@ function emptyStore() {
 async function save() {
     if (!_store || !_password)
         throw new Error("Store not unlocked");
-    await fs.mkdir(getStoreDir(), { recursive: true });
+    await fs.mkdir(getStoreDir(), { recursive: true, mode: 0o700 });
     const file = {
         version: VERSION,
         encrypted: await encrypt(JSON.stringify(_store), _password),
     };
-    await fs.writeFile(getStoreFile(), JSON.stringify(file, null, 2));
+    // Owner-only perms + atomic rename, same pattern as the wallet keystores
+    const tempFile = getStoreFile() + ".tmp";
+    await fs.writeFile(tempFile, JSON.stringify(file, null, 2), { mode: 0o600 });
+    await fs.rename(tempFile, getStoreFile());
 }
 async function load(password) {
     const raw = await fs.readFile(getStoreFile(), "utf-8");

package/dist/services/defi.service.js

@@ -1,6 +1,6 @@
 import { uintCV, contractPrincipalCV, cvToJSON, hexToCV, PostConditionMode, Pc, principalCV, noneCV, someCV, listCV, bufferCV, } from "@stacks/transactions";
 import { AlexSDK, Currency } from "alex-sdk";
-import { getHiroApi } from "./hiro-api.js";
+import { getHiroApi, isNotFoundError } from "./hiro-api.js";
 import { getAlexContracts, getZestContracts, parseContractId, ZEST_ASSETS, ZEST_V2_MARKET, ZEST_V2_MARKET_VAULT, } from "../config/index.js";
 import { callContract } from "../transactions/builder.js";
 // ============================================================================
@@ -129,8 +129,10 @@ export class AlexDexService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -360,8 +362,10 @@ export class ZestProtocolService {
                 healthFactor: position["health-factor"]?.value,
             };
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -377,8 +381,10 @@ export class ZestProtocolService {
             }
             return cvToJSON(hexToCV(result.result));
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     /**
@@ -411,8 +417,12 @@ export class ZestProtocolService {
                 }
             }
         }
-        catch {
-            // Fall back to shares as lower bound estimate
+        catch (error) {
+            // Only fall back to the shares lower-bound estimate when the vault
+            // function is missing — network/server failures must surface, or the
+            // post-conditions built from this value would be silently wrong.
+            if (!isNotFoundError(error))
+                throw error;
         }
         return shares;
     }
@@ -431,8 +441,10 @@ export class ZestProtocolService {
                 }
             }
         }
-        catch {
-            // Fall back to amount as upper bound
+        catch (error) {
+            // Same rationale as getUnderlyingFromShares: estimate only on 404.
+            if (!isNotFoundError(error))
+                throw error;
         }
         return amount;
     }

package/dist/services/hiro-api.d.ts

@@ -7,6 +7,16 @@ export declare class HiroApiRateLimitError extends Error {
     readonly retryAfterSeconds: number;
     constructor(message: string, retryAfterSeconds: number);
 }
+/**
+ * HTTP error from the Hiro / BNS V2 APIs, carrying the status code so
+ * callers can treat 404 as "not found" without swallowing other failures.
+ */
+export declare class HiroApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** True when the error is an expected "resource does not exist" response. */
+export declare function isNotFoundError(error: unknown): boolean;
 export interface AccountInfo {
     balance: string;
     locked: string;

package/dist/services/hiro-api.js

@@ -16,6 +16,22 @@ export class HiroApiRateLimitError extends Error {
         this.name = "HiroApiRateLimitError";
     }
 }
+/**
+ * HTTP error from the Hiro / BNS V2 APIs, carrying the status code so
+ * callers can treat 404 as "not found" without swallowing other failures.
+ */
+export class HiroApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "HiroApiError";
+    }
+}
+/** True when the error is an expected "resource does not exist" response. */
+export function isNotFoundError(error) {
+    return error instanceof HiroApiError && error.status === 404;
+}
 // ============================================================================
 // Hiro API Service
 // ============================================================================
@@ -51,7 +67,7 @@ export class HiroApiService {
                 throw new HiroApiRateLimitError(`Hiro API rate limit exceeded. Retry after ${retryAfterSeconds}s`, retryAfterSeconds);
             }
             const errorText = await response.text();
-            throw new Error(`Hiro API error (${response.status}): ${errorText}`);
+            throw new HiroApiError(`Hiro API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }
@@ -123,8 +139,10 @@ export class HiroApiService {
         try {
             return await this.fetch(`/metadata/v1/ft/${contractId}`);
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     async getTokenHolders(contractId, options) {
@@ -329,8 +347,10 @@ export class HiroApiService {
             const info = await this.getBnsNameInfo(name);
             return info.address;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
     // ==========================================================================
@@ -385,7 +405,7 @@ export class BnsV2ApiService {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`BNS V2 API error (${response.status}): ${errorText}`);
+            throw new HiroApiError(`BNS V2 API error (${response.status}): ${errorText}`, response.status);
         }
         return response.json();
     }
@@ -431,8 +451,10 @@ export class BnsV2ApiService {
             }
             return null;
         }
-        catch {
-            return null;
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
         }
     }
 }

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

@@ -1,5 +1,5 @@
 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";
@@ -11,6 +11,7 @@ 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 +43,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
@@ -457,6 +468,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
@@ -476,9 +497,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 +519,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 +540,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();
@@ -716,8 +747,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 +765,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

@@ -33,6 +33,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,6 +244,7 @@ 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();

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

package/dist/tools/news.tools.js

@@ -56,21 +56,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
-    }
     const chainNext = Math.max(confirmedNonce, highestMempoolNonce + 1);
     await reconcileWithChain(address, chainNext);
     return Math.max(chainNext, localNext ?? 0);

package/dist/tools/pillar-direct.tools.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import crypto from "crypto";
 import { tupleCV, stringAsciiCV, uintCV, principalCV, noneCV, trueCV, falseCV, } from "@stacks/transactions";
 import { getSigningKeyService, generateAuthId, } from "../services/signing-key.service.js";
-import { getPillarApi } from "../services/pillar-api.service.js";
+import { getPillarApi, PillarApiError } from "../services/pillar-api.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { NETWORK } from "../config/networks.js";
 import { PILLAR_API_KEY } from "../config/pillar.js";
@@ -497,8 +497,12 @@ export function registerPillarDirectTools(server) {
                 const walletInfo = await api.get(`/api/smart-wallet/${walletName}`);
                 walletStatus = walletInfo.data?.status || null;
             }
-            catch {
-                // Wallet not found in backend
+            catch (error) {
+                // 404 = wallet not registered in backend. Anything else (network,
+                // 5xx) must surface, or an initialized wallet gets misreported.
+                if (!(error instanceof PillarApiError && error.status === 404)) {
+                    throw error;
+                }
             }
             if (!walletStatus || walletStatus === "pending_init") {
                 return createJsonResponse({
@@ -554,8 +558,11 @@ export function registerPillarDirectTools(server) {
                 });
                 position = unwindQuote.data;
             }
-            catch {
-                // unwind-quote may fail for fresh wallets with no position
+            catch (error) {
+                // 4xx = fresh wallet with no position. Infra failures must surface.
+                if (!(error instanceof PillarApiError && error.status < 500)) {
+                    throw error;
+                }
             }
             return createJsonResponse({
                 success: true,
@@ -1146,21 +1153,16 @@ export function registerPillarDirectTools(server) {
                 const frac = (micro % BigInt(1_000_000)).toString().padStart(6, "0");
                 return `${whole}.${frac} STX`;
             };
-            // Fetch PoX cycle info
-            let poxInfo = null;
-            try {
-                const pox = await hiro.getPoxInfo();
-                poxInfo = {
-                    currentCycleId: pox.current_cycle.id,
-                    nextCycleId: pox.next_cycle.id,
-                    blocksUntilNextCycle: pox.next_cycle.blocks_until_reward_phase,
-                    minAmountUstx: pox.min_amount_ustx,
-                    isPoxActive: pox.current_cycle.is_pox_active,
-                };
-            }
-            catch {
-                // PoX info fetch failed, continue without it
-            }
+            // Fetch PoX cycle info — a global endpoint with no "not found" case,
+            // so any failure is infrastructure and should surface.
+            const pox = await hiro.getPoxInfo();
+            const poxInfo = {
+                currentCycleId: pox.current_cycle.id,
+                nextCycleId: pox.next_cycle.id,
+                blocksUntilNextCycle: pox.next_cycle.blocks_until_reward_phase,
+                minAmountUstx: pox.min_amount_ustx,
+                isPoxActive: pox.current_cycle.is_pox_active,
+            };
             // Check enrollment status via backend
             const api = getPillarApi();
             const contractParts = session.smartWallet.split(".");
@@ -1175,8 +1177,13 @@ export function registerPillarDirectTools(server) {
                     };
                 }
             }
-            catch {
-                // Backend lookup failed, continue without enrollment info
+            catch (error) {
+                // 404 = wallet not registered, so not enrolled. Other failures
+                // must surface — defaulting to enrolled:false on a backend outage
+                // misreports an enrolled wallet and could prompt re-enrollment.
+                if (!(error instanceof PillarApiError && error.status === 404)) {
+                    throw error;
+                }
             }
             const isStacking = lockedMicro > BigInt(0);
             return createJsonResponse({

package/dist/tools/sbtc.tools.js

@@ -283,16 +283,9 @@ Signers later process the request and send BTC on L1.`,
         description: "Get information about how to deposit BTC to receive sBTC.",
     }, async () => {
         try {
-            // Try to get wallet account (don't throw if not unlocked)
+            // getActiveAccount returns null when locked - generic instructions then
             const walletManager = getWalletManager();
-            let account;
-            try {
-                account = walletManager.getActiveAccount();
-            }
-            catch {
-                // Wallet not unlocked - return generic instructions
-                account = null;
-            }
+            const account = walletManager.getActiveAccount();
             // If wallet is unlocked and has Taproot keys, generate real deposit address
             if (account?.taprootPublicKey) {
                 const depositService = getSbtcDepositService(NETWORK);