@aibtc/mcp-server 1.58.0 → 1.60.0

package/README.md

@@ -69,6 +69,38 @@ npx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/
 
 Each installer merges into the existing config — it won't clobber other servers or settings. Restart the client afterward.
 
+### OpenRouter (any model)
+
+The clients above are MCP hosts — they connect to this server for you. To drive the tools with an [OpenRouter](https://openrouter.ai) model instead, the server ships a built-in bridge: it spawns itself in server mode, exposes the tools to the model as function tools, and runs the tool-call loop. This is the client-side pattern from [OpenRouter's MCP cookbook](https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers), packaged into the binary.
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3...?"
+```
+
+Safety flags (this server moves real funds, so the bridge defaults to nothing extra and lets you constrain it):
+
+| Flag | Effect |
+|------|--------|
+| `--read-only` | Expose only read-only tools (no transfer/swap/deploy/etc.) |
+| `--allow a,b` | Force-allow specific tool names (added to the set) |
+| `--block a,b` | Force-remove specific tool names (wins over `--allow`) |
+| `--max-spend-ustx <n>` / `--max-spend-sats <n>` | Cap spend via the server's spend-limit rail (enforced before signing) |
+| `--list-tools` | Print the exposed tool set and exit (no API key needed) |
+| `--model <id>` | OpenRouter model (default `anthropic/claude-3.5-haiku`) |
+| `--network <net>` | `mainnet` or `testnet` (default `mainnet`) |
+| `--max-turns <n>` | Tool-call loop cap (default 10) |
+
+```bash
+# Preview what a read-only session would expose, no key needed:
+npx @aibtc/mcp-server@latest bridge --read-only --list-tools
+
+# Read-only chat, plus one explicitly allowed write tool:
+npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
+```
+
+The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
+
 ### Testnet Mode
 
 Add `--testnet` to any install command:
@@ -512,9 +544,14 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 | `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |
 | `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |
 | `HIRO_API_KEY` | (Optional) Hiro API key for higher rate limits | - |
+| `SPEND_LIMIT_ENABLED` | Set `false` to disable the wallet spending limit | `true` |
+| `SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX` | STX spend cap per day / per unlock (micro-STX) | `10000000` (10 STX) |
+| `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` | BTC spend cap per day / per unlock (sats) | `50000` |
 
 **Note on `NETWORK`:** The `--install` command writes `NETWORK=mainnet` by default (pass `--testnet` to use testnet). If you omit `NETWORK` from your config entirely, the runtime fallback is `testnet`. Most users should set this explicitly.
 
+**Note on spending limits:** A default-on safety rail meters every outbound spend (`transfer_stx`, `transfer_btc`, x402/L402 auto-payments) against a cumulative per-session and per-day cap, so a single bad instruction or a malicious endpoint can't drain the wallet. A spend over the cap is blocked and reports the remaining budget. Raise the caps via the env vars above, or disable with `SPEND_LIMIT_ENABLED=false`. See [SECURITY.md](SECURITY.md#limit-blast-radius).
+
 **Note:** `CLIENT_MNEMONIC` is optional. The recommended approach is to let Claude create its own wallet. `HIRO_API_KEY` is optional but recommended for production use — without it, you may hit Hiro's public rate limits (429 responses). Get a key at [platform.hiro.so](https://platform.hiro.so).
 
 ## Architecture
@@ -538,8 +575,12 @@ You ←→ Claude ←→ aibtc-mcp-server
 - Mnemonics shown only once at creation
 - Auto-lock after 15 minutes (configurable)
 - Transactions signed locally before broadcast
+- **Spending limit (default-on):** outbound spends are capped per session and per day so a single bad instruction can't drain the wallet — see [Configuration](#configuration)
+- **Secret-scanning pre-commit hook:** contributors get a hook (auto-installed via `npm install`) that blocks committing a seed phrase or private key
 - For mainnet: Fund with small amounts first
 
+See [SECURITY.md](SECURITY.md) for the full wallet-key protection model and key-leak recovery steps.
+
 ## Advanced: Pre-configured Mnemonic
 
 For automated setups where Claude needs immediate wallet access, add the `CLIENT_MNEMONIC` environment variable to your MCP server config (in `~/.claude.json` for Claude Code, or `claude_desktop_config.json` for Claude Desktop):

package/dist/bridge/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenRouter <-> MCP bridge (`aibtc-mcp-server bridge`).
+ *
+ * Lets any OpenRouter model call this server's tools. This is the canonical
+ * integration described in OpenRouter's own cookbook
+ * (https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers): the CLIENT
+ * connects to the MCP server and routes LLM calls through OpenRouter — there is
+ * no OpenRouter-side MCP hosting. This is a Node port of that pattern with two
+ * upgrades: it handles every tool_call (not just the first) and loops to
+ * completion (not a single round).
+ *
+ * Flow:
+ *   1. Spawn this same binary in server mode over stdio, connect, list tools.
+ *   2. Apply safety filters, then convert each MCP tool -> OpenAI function tool.
+ *   3. POST conversation + tools to OpenRouter /chat/completions.
+ *   4. On tool_calls, execute via MCP and feed results back as role:"tool".
+ *   5. Loop until the model answers in plain text (capped by --max-turns).
+ *
+ * Safety flags:
+ *   --read-only            expose only read-only tools (heuristic allowlist)
+ *   --allow a,b,c          force-allow these tool names (added to the set)
+ *   --block a,b,c          force-remove these tool names (applied last, wins)
+ *   --max-spend-ustx <n>   forward to the server's SPEND_LIMIT_SESSION_USTX rail
+ *   --max-spend-sats <n>   forward to the server's SPEND_LIMIT_SESSION_SATS rail
+ *   --list-tools           print the exposed tool set and exit (no API key needed)
+ *   --model <id>           OpenRouter model (default anthropic/claude-3.5-haiku)
+ *   --network <net>        mainnet|testnet for the spawned server (default mainnet)
+ *   --max-turns <n>        tool-call loop cap (default 10)
+ */
+export declare function runBridge(argv: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.js

@@ -0,0 +1,285 @@
+/**
+ * OpenRouter <-> MCP bridge (`aibtc-mcp-server bridge`).
+ *
+ * Lets any OpenRouter model call this server's tools. This is the canonical
+ * integration described in OpenRouter's own cookbook
+ * (https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers): the CLIENT
+ * connects to the MCP server and routes LLM calls through OpenRouter — there is
+ * no OpenRouter-side MCP hosting. This is a Node port of that pattern with two
+ * upgrades: it handles every tool_call (not just the first) and loops to
+ * completion (not a single round).
+ *
+ * Flow:
+ *   1. Spawn this same binary in server mode over stdio, connect, list tools.
+ *   2. Apply safety filters, then convert each MCP tool -> OpenAI function tool.
+ *   3. POST conversation + tools to OpenRouter /chat/completions.
+ *   4. On tool_calls, execute via MCP and feed results back as role:"tool".
+ *   5. Loop until the model answers in plain text (capped by --max-turns).
+ *
+ * Safety flags:
+ *   --read-only            expose only read-only tools (heuristic allowlist)
+ *   --allow a,b,c          force-allow these tool names (added to the set)
+ *   --block a,b,c          force-remove these tool names (applied last, wins)
+ *   --max-spend-ustx <n>   forward to the server's SPEND_LIMIT_SESSION_USTX rail
+ *   --max-spend-sats <n>   forward to the server's SPEND_LIMIT_SESSION_SATS rail
+ *   --list-tools           print the exposed tool set and exit (no API key needed)
+ *   --model <id>           OpenRouter model (default anthropic/claude-3.5-haiku)
+ *   --network <net>        mainnet|testnet for the spawned server (default mainnet)
+ *   --max-turns <n>        tool-call loop cap (default 10)
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
+const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
+/**
+ * Read-only heuristic. A tool counts as read-only only if it matches a known
+ * read pattern AND contains no mutating verb — deliberately conservative so a
+ * spend/write tool is never auto-included. Use --allow/--block for precision.
+ */
+const READ_PATTERNS = [
+    /^get_/, /^list_/, /^check_/, /^lookup_/, /^reverse_/, /^probe_/, /^read_/,
+    /_status$/, /_info$/, /_quote$/, /_quote_/, /_models$/, /_guide$/, /_list$/,
+    /_balance$/, /_fees$/, /_utxos$/, /_history$/, /_holdings$/, /_overview$/,
+    /_summary$/, /_health$/, /_price$/, /_prices$/, /_state$/, /_positions$/,
+    /_breakdown$/, /_dashboard_/, /_stats$/, /_metadata$/, /_owner$/, /_holders$/,
+    /_search$/, /_feed$/, /_profile$/, /_pubkey$/, /_availability$/, /_count$/,
+];
+const WRITE_VERB = /(transfer|send|swap|deploy|broadcast|buy|sell|pay|supply|withdraw|borrow|repay|create|delete|register|claim|deposit|stack|boost|unwind|invite|set_|sign|submit|enroll|opt_|file_|preorder|mint|inscribe|approve|revoke|connect|disconnect|rotate|export|import|unlock|lock|start|stop|join|settle|redeem|fund|accept|cancel|counter|append|give|add_|deactivate|record|compile|configure|heal|fill_gap|recover|rebalance|hunter|enable)/;
+function isReadOnly(name) {
+    if (WRITE_VERB.test(name))
+        return false;
+    return READ_PATTERNS.some((p) => p.test(name));
+}
+/** MCP tool -> OpenRouter (OpenAI) function-tool schema (verbatim JSON Schema). */
+function toOpenAITool(tool) {
+    // Clone so we never mutate the tool descriptor handed back by the MCP SDK.
+    const raw = tool.inputSchema ?? {};
+    const schema = { type: "object", properties: {}, ...raw };
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description ?? "",
+            parameters: schema,
+        },
+    };
+}
+function parseArgs(argv) {
+    const opts = {
+        prompt: "",
+        model: process.env.OPENROUTER_MODEL || DEFAULT_MODEL,
+        network: process.env.NETWORK || "mainnet",
+        readOnly: false,
+        allow: new Set(),
+        block: new Set(),
+        maxTurns: 10,
+        listTools: false,
+    };
+    const promptWords = [];
+    const csv = (v) => v.split(",").map((s) => s.trim()).filter(Boolean);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        // Value-taking flags must be followed by a value — otherwise the next loop
+        // iteration would silently consume the following flag (or leave the option
+        // unset, which for a spend cap means the rail is quietly disabled).
+        const value = (flag) => {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("--")) {
+                console.error(`Missing value for ${flag}`);
+                process.exit(1);
+            }
+            return v;
+        };
+        switch (a) {
+            case "--read-only":
+                opts.readOnly = true;
+                break;
+            case "--list-tools":
+                opts.listTools = true;
+                break;
+            case "--model":
+                opts.model = value(a);
+                break;
+            case "--network":
+                opts.network = value(a);
+                break;
+            case "--allow":
+                csv(value(a)).forEach((t) => opts.allow.add(t));
+                break;
+            case "--block":
+                csv(value(a)).forEach((t) => opts.block.add(t));
+                break;
+            case "--max-spend-ustx":
+                opts.maxSpendUstx = value(a);
+                break;
+            case "--max-spend-sats":
+                opts.maxSpendSats = value(a);
+                break;
+            case "--max-turns": {
+                const raw = value(a);
+                const n = parseInt(raw, 10);
+                if (!Number.isInteger(n) || n < 1) {
+                    console.error(`--max-turns must be a positive integer (got "${raw}")`);
+                    process.exit(1);
+                }
+                opts.maxTurns = n;
+                break;
+            }
+            default:
+                if (a.startsWith("--")) {
+                    console.error(`Unknown flag: ${a}`);
+                    process.exit(1);
+                }
+                promptWords.push(a);
+        }
+    }
+    opts.prompt = promptWords.join(" ").trim();
+    return opts;
+}
+/** Apply read-only + allow + block to the raw MCP tool list. */
+function selectTools(tools, opts) {
+    return tools.filter((t) => {
+        if (opts.block.has(t.name))
+            return false;
+        if (opts.allow.has(t.name))
+            return true;
+        if (opts.readOnly)
+            return isReadOnly(t.name);
+        return true;
+    });
+}
+async function callOpenRouter(apiKey, model, messages, tools) {
+    const res = await fetch(OPENROUTER_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://github.com/aibtcdev/aibtc-mcp",
+            "X-Title": "aibtc-mcp bridge",
+        },
+        body: JSON.stringify({ model, messages, tools, tool_choice: "auto" }),
+    });
+    if (!res.ok) {
+        throw new Error(`OpenRouter ${res.status}: ${await res.text()}`);
+    }
+    // OpenRouter can return HTTP 200 with an error payload (rate limit, moderation,
+    // provider failure) and no choices — surface it instead of crashing on [0].
+    const data = (await res.json());
+    const message = data.choices?.[0]?.message;
+    if (!message) {
+        const detail = data.error?.message ?? JSON.stringify(data);
+        throw new Error(`OpenRouter returned no message: ${detail}`);
+    }
+    return message;
+}
+export async function runBridge(argv) {
+    const opts = parseArgs(argv);
+    // Spawn this same binary in plain server mode (no extra args -> MCP server).
+    const serverEnv = {
+        ...process.env,
+        NETWORK: opts.network,
+    };
+    if (opts.maxSpendUstx)
+        serverEnv.SPEND_LIMIT_SESSION_USTX = opts.maxSpendUstx;
+    if (opts.maxSpendSats)
+        serverEnv.SPEND_LIMIT_SESSION_SATS = opts.maxSpendSats;
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [process.argv[1]],
+        env: serverEnv,
+    });
+    const client = new Client({ name: "aibtc-openrouter-bridge", version: "1.0.0" });
+    await client.connect(transport);
+    const { tools: allTools } = await client.listTools();
+    const exposed = selectTools(allTools, opts);
+    if (opts.listTools) {
+        console.log(`Exposed ${exposed.length}/${allTools.length} tools` +
+            (opts.readOnly ? " (read-only)" : "") + ":");
+        for (const t of exposed)
+            console.log(`  ${t.name}`);
+        await client.close();
+        return;
+    }
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+        console.error("Set OPENROUTER_API_KEY (or use --list-tools to preview without a model).");
+        await client.close();
+        process.exit(1);
+    }
+    if (!opts.prompt) {
+        console.error('Provide a prompt, e.g. aibtc-mcp-server bridge "what is the STX balance of SP3..."');
+        await client.close();
+        process.exit(1);
+    }
+    const writeCount = exposed.filter((t) => !isReadOnly(t.name)).length;
+    console.error(`Bridge: ${exposed.length} tools -> ${opts.model}` +
+        (opts.readOnly ? " [read-only]" : ` [${writeCount} can write/spend]`) +
+        (opts.maxSpendUstx || opts.maxSpendSats
+            ? ` (cap ${opts.maxSpendUstx ?? "-"} uSTX / ${opts.maxSpendSats ?? "-"} sats)`
+            : ""));
+    const openaiTools = exposed.map(toOpenAITool);
+    const messages = [
+        {
+            role: "system",
+            content: "You are an agent with access to aibtc-mcp tools for Stacks/Bitcoin and " +
+                "x402 actions. Use tools when needed. Be concise.",
+        },
+        { role: "user", content: opts.prompt },
+    ];
+    try {
+        let completed = false;
+        for (let turn = 0; turn < opts.maxTurns; turn++) {
+            const reply = await callOpenRouter(apiKey, opts.model, messages, openaiTools);
+            messages.push(reply);
+            const toolCalls = reply.tool_calls ?? [];
+            if (toolCalls.length === 0) {
+                console.log("\n" + (reply.content ?? ""));
+                completed = true;
+                break;
+            }
+            for (const call of toolCalls) {
+                const name = call.function.name;
+                // Enforce the allowlist at execution time too — never trust the model
+                // to stay inside the exposed set.
+                if (!exposed.some((t) => t.name === name)) {
+                    messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        name,
+                        content: `Tool ${name} is not permitted by the bridge.`,
+                    });
+                    continue;
+                }
+                let args = {};
+                try {
+                    args = JSON.parse(call.function.arguments || "{}");
+                }
+                catch {
+                    /* malformed JSON -> empty args */
+                }
+                console.error(`-> ${name}(${call.function.arguments || "{}"})`);
+                let content;
+                try {
+                    const result = await client.callTool({ name, arguments: args });
+                    content = (result.content ?? [])
+                        .map((c) => (c?.type === "text" ? c.text : JSON.stringify(c)))
+                        .join("\n");
+                }
+                catch (err) {
+                    content = `Tool error: ${err.message}`;
+                }
+                messages.push({ role: "tool", tool_call_id: call.id, name, content });
+            }
+        }
+        // Don't let the cap swallow the session silently — the model was still
+        // calling tools when we ran out of turns.
+        if (!completed) {
+            console.error(`Bridge: reached --max-turns limit (${opts.maxTurns}) without a final response. ` +
+                "Re-run with a higher --max-turns to let it finish.");
+        }
+    }
+    finally {
+        await client.close();
+    }
+}
+//# sourceMappingURL=index.js.map

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 = [
@@ -216,6 +229,16 @@ if (process.argv[2] === "yield-hunter") {
         process.exit(1);
     });
 }
+// Check for bridge command (OpenRouter <-> MCP)
+else if (process.argv[2] === "bridge") {
+    import("./bridge/index.js")
+        .then(({ runBridge }) => runBridge(process.argv.slice(3)))
+        .then(() => process.exit(0))
+        .catch((error) => {
+        console.error("❌ Bridge error:", redactSensitive(String(error)));
+        process.exit(1);
+    });
+}
 // Check for --install flag
 else if (process.argv.includes("--install") || process.argv.includes("install")) {
     runInstall()

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