perp-cli 0.14.0 → 0.14.2

package/dist/commands/rebalance.js

@@ -1,7 +1,8 @@
 import { isDryRun, supportsDryRun } from "../cli-flags.js";
 import chalk from "chalk";
 import { formatUsd, makeTable, printJson, jsonOk } from "../utils.js";
-import { fetchAllBalances, computeRebalancePlan, describeBridgeRoute, estimateMoveTime, } from "../rebalance.js";
+import { PerpError } from "../errors.js";
+import { fetchBalancesWithFailures, computeRebalancePlan, describeBridgeRoute, estimateMoveTime, } from "../rebalance.js";
 import { EXCHANGE_TO_CHAIN, assertBridgeNetwork, executeBestBridge } from "../bridge-engine.js";
 import { cliCredentialOptsFrom } from "../config.js";
 export function registerFundsRebalanceCommands(parent, getAdapterForExchange, isJson, getNetwork) {
@@ -31,9 +32,14 @@ export function registerFundsRebalanceCommands(parent, getAdapterForExchange, is
         }
         if (!isJson())
             console.log(chalk.cyan("\n  Fetching balances across exchanges...\n"));
-        const snapshots = await fetchAllBalances(adapters);
+        const { snapshots, failed, notConfigured } = await fetchBalancesWithFailures(adapters);
+        // A venue whose balance read failed is unavailable — listed, never shown as $0 or dropped.
+        unavailable.push(...failed);
+        const partial = unavailable.length > 0;
         if (isJson())
-            return printJson(jsonOk({ snapshots, unavailable }));
+            return printJson(jsonOk({ snapshots, unavailable, partial, notConfigured }));
+        for (const n of notConfigured)
+            console.log(chalk.gray(`  ${n}: not configured (no credentials) — left out`));
         const totalEquity = snapshots.reduce((s, e) => s + e.equity, 0);
         const totalAvailable = snapshots.reduce((s, e) => s + e.available, 0);
         const rows = snapshots.map((s) => {
@@ -53,7 +59,8 @@ export function registerFundsRebalanceCommands(parent, getAdapterForExchange, is
         console.log(chalk.cyan.bold("  Totals"));
         console.log(`  Total Equity:    $${formatUsd(totalEquity)}`);
         console.log(`  Total Available: $${formatUsd(totalAvailable)}`);
-        console.log(`  Exchanges:       ${snapshots.length}\n`);
+        console.log(`  Exchanges:       ${snapshots.length}${partial ? ` of ${exchangeNames.length} (partial)` : ""}\n`);
+        printUnavailable(unavailable);
     });
     // ── rebalance plan ──
     rebalance
@@ -82,13 +89,22 @@ export function registerFundsRebalanceCommands(parent, getAdapterForExchange, is
         }
         if (!isJson())
             console.log(chalk.cyan("\n  Computing rebalance plan...\n"));
-        const snapshots = await fetchAllBalances(adapters);
+        const { snapshots, failed, notConfigured } = await fetchBalancesWithFailures(adapters);
+        unavailable.push(...failed);
+        // partial: the plan covers only the venues that were read — `execute` refuses to run it.
+        const partial = unavailable.length > 0;
         const plan = computeRebalancePlan(snapshots, {
             minMove: parseFloat(opts.minMove),
             reserve: parseFloat(opts.reserve),
         });
         if (isJson())
-            return printJson(jsonOk({ ...plan, unavailable }));
+            return printJson(jsonOk({ ...plan, unavailable, partial, notConfigured }));
+        for (const n of notConfigured)
+            console.log(chalk.gray(`  ${n}: not configured (no credentials) — left out of the plan`));
+        if (partial) {
+            console.log(chalk.yellow(`  ⚠ Partial plan: computed over ${snapshots.length} of ${exchangeNames.length} exchanges.`));
+            printUnavailable(unavailable);
+        }
         // Show current state
         const rows = plan.snapshots.map((s) => {
             const target = plan.targetPerExchange;
@@ -134,19 +150,33 @@ export function registerFundsRebalanceCommands(parent, getAdapterForExchange, is
             assertBridgeNetwork(getNetwork());
         const exchangeNames = opts.exchanges.split(",").map((e) => e.trim());
         const adapters = new Map();
+        const unavailable = [];
         for (const name of exchangeNames) {
             try {
                 adapters.set(name, await getAdapterForExchange(name));
             }
-            catch {
-                // skip
+            catch (e) {
+                unavailable.push({ exchange: name, error: e instanceof Error ? e.message : String(e) });
             }
         }
-        if (adapters.size < 2) {
+        if (adapters.size < 2 && unavailable.length === 0) {
             console.error(chalk.red("\n  Need at least 2 exchanges.\n"));
             return;
         }
-        const snapshots = await fetchAllBalances(adapters);
+        const { snapshots, failed, notConfigured } = await fetchBalancesWithFailures(adapters);
+        unavailable.push(...failed);
+        // A venue without credentials holds nothing the CLI can move: left out (noted), not a failure.
+        if (!isJson())
+            for (const n of notConfigured)
+                console.log(chalk.gray(`  ${n}: not configured (no credentials) — left out`));
+        // Moving funds on a plan computed over fewer venues than requested would mis-size every
+        // move: abort unless every requested venue was read.
+        if (unavailable.length > 0) {
+            throw new PerpError("EXCHANGE_ERROR", `Rebalance aborted: balances of ${unavailable.map(u => u.exchange).join(", ")} could not be read (${unavailable.map(u => `${u.exchange}: ${u.error}`).join("; ")})`, {
+                unavailable,
+                remediation: `Retry when every venue answers, or exclude the unavailable venue(s) explicitly with --exchanges ${exchangeNames.filter(n => !unavailable.some(u => u.exchange === n)).join(",") || "<list>"}`,
+            });
+        }
         const plan = computeRebalancePlan(snapshots, {
             minMove: parseFloat(opts.minMove),
             reserve: parseFloat(opts.reserve),
@@ -238,6 +268,12 @@ export function registerFundsRebalanceCommands(parent, getAdapterForExchange, is
         console.log(chalk.cyan("  Rebalance initiated. Monitor progress with 'perp funds rebalance check'.\n"));
     });
 }
+function printUnavailable(unavailable) {
+    for (const u of unavailable)
+        console.log(chalk.yellow(`  ⚠ ${u.exchange} unavailable (left out): ${u.error}`));
+    if (unavailable.length > 0)
+        console.log();
+}
 /**
  * Execute a withdrawal from a source exchange.
  */

package/dist/commands/settings.js

@@ -1,3 +1,4 @@
+import { QFEX_WITHDRAW_ENABLED } from "../exchanges/venues/qfex.js";
 import { unsupported } from "../exchanges/trading-v2.js";
 import chalk from "chalk";
 import { printJson, jsonOk, withJsonErrors } from "../utils.js";
@@ -116,7 +117,7 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
                 const fee = "feeBps" in e ? `${e.feeBps} bps` : "fee share (you pay the normal fee)";
                 console.log(`    ${v.padEnd(14)} ${id}  ${fee}${BUILDER_FEE_CAPABILITIES[v]?.feeKind === "max" ? " (max)" : ""}`);
             }
-            console.log(chalk.white.bold("\n  Withdraw gate (qfex: API-key withdrawals; hyperliquid: withdraw / transfer to a non-owner address; off unless set):"));
+            console.log(chalk.white.bold(`\n  Withdraw gate (qfex: API-key withdrawals${QFEX_WITHDRAW_ENABLED ? "" : " — currently disabled in perp-cli"}; hyperliquid: withdraw / transfer to a non-owner address; off unless set):`));
             const gates = Object.entries(s.withdraw);
             if (gates.length === 0)
                 console.log(chalk.gray(`    (none — gated withdrawals on ${WITHDRAW_GATE_VENUES.join(", ")} are refused; Hyperliquid to the owner's own address is always allowed)`));

package/dist/commands/trade.js

@@ -1938,7 +1938,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
     // ── Recent Fills ──
     trade
         .command("fills [symbol]")
-        .description("Recent trade fills, optionally filtered by symbol")
+        .description("Recent trade fills, optionally filtered by symbol (Aster: last 7 days, symbols with a position, open order or fill in that window)")
         .option("-l, --limit <n>", "Number of fills", "30")
         .action(async (symbol, opts) => {
         await withJsonErrors(isJson(), async () => {
@@ -2120,6 +2120,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                 }
                 // Fetch funding payments (recent) for display
                 let fundingBySymbol = {};
+                let fundingError = null;
                 try {
                     const payments = await adapter.getFundingPayments(50);
                     for (const fp of payments) {
@@ -2127,8 +2128,9 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                         fundingBySymbol[sym] = (fundingBySymbol[sym] || 0) + parseFloat(fp.payment);
                     }
                 }
-                catch {
-                    // funding payments may not be supported on all exchanges
+                catch (e) {
+                    // Shown under the table: funding columns are then unknown, not 0.
+                    fundingError = e instanceof Error ? e.message : String(e);
                 }
                 console.clear();
                 console.log(chalk.cyan.bold(`\n  PnL Tracker — ${adapter.name} | ${new Date().toLocaleTimeString()}\n`));
@@ -2155,11 +2157,13 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                             `$${formatUsd(p.markPrice)}`,
                             pnlColor(`${pnl >= 0 ? "+" : ""}$${pnl.toFixed(2)}`),
                             pctColor(`${pnlPct >= 0 ? "+" : ""}${pnlPct.toFixed(2)}%`),
-                            funding !== 0 ? `$${funding.toFixed(4)}` : "-",
+                            fundingError !== null ? chalk.yellow("n/a") : funding !== 0 ? `$${funding.toFixed(4)}` : "-",
                         ];
                     });
                     console.log(makeTable(["Symbol", "Side", "Size", "Entry", "Mark", "PnL", "PnL%", "Funding"], rows));
                 }
+                if (fundingError !== null)
+                    console.log(chalk.yellow(`\n  Funding history unavailable (Funding column n/a): ${fundingError}`));
                 console.log(chalk.gray(`\n  Refreshing every ${intervalSec}s... Press Ctrl+C to stop.`));
                 await new Promise(r => setTimeout(r, intervalSec * 1000));
             }

package/dist/commands/wallet.js

@@ -1,4 +1,5 @@
 import { Option } from "commander";
+import { evmOnchainBalances, solanaOnchainBalances, stableTotal } from "../onchain-balances.js";
 import { PerpError } from "../errors.js";
 import chalk from "chalk";
 import bs58 from "bs58";
@@ -98,80 +99,60 @@ export function getWalletKeyByName(name) {
     const store = loadStore();
     return store.wallets[name]?.privateKey ?? null;
 }
+/** SOL + USDC / USDT on Solana (devnet: USDP). */
 async function getSolanaBalances(address, isTestnet) {
-    const { Connection, PublicKey } = await import("@solana/web3.js");
-    const rpcUrl = isTestnet
-        ? "https://api.devnet.solana.com"
-        : "https://api.mainnet-beta.solana.com";
-    const connection = new Connection(rpcUrl);
-    const pubkey = new PublicKey(address);
-    const balances = [];
-    const solLamports = await connection.getBalance(pubkey);
-    const solBalance = solLamports / 1e9;
-    balances.push({ token: "SOL", balance: solBalance.toFixed(6), usdValue: "" });
-    const usdcMint = isTestnet
-        ? "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM"
-        : "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
-    try {
-        const tokenAccounts = await connection.getParsedTokenAccountsByOwner(pubkey, {
-            mint: new PublicKey(usdcMint),
-        });
-        let usdcBalance = 0;
-        for (const { account } of tokenAccounts.value) {
-            const parsed = account.data.parsed?.info;
-            if (parsed)
-                usdcBalance += Number(parsed.tokenAmount?.uiAmount ?? 0);
+    return solanaOnchainBalances(address, isTestnet);
+}
+/** Gas token + USDC / USDT (USDG on Robinhood Chain) on every EVM chain perp-cli uses; `only` limits the chains. */
+async function getEvmBalances(address, isTestnet, only) {
+    return evmOnchainBalances(address, isTestnet, only);
+}
+/** Human table: non-zero balances and failed reads (JSON keeps every row), then the stablecoin total. */
+function balanceTable(balances) {
+    const shown = balances.filter(b => b.error !== null || Number(b.balance) !== 0);
+    const rows = shown.map((b) => [
+        b.chain,
+        chalk.white.bold(b.token),
+        b.balance === null ? chalk.red("read failed") : b.balance,
+        b.usdValue !== null ? `$${formatUsd(b.usdValue)}` : b.priceError !== null ? chalk.gray("price unavailable") : chalk.gray("-"),
+    ]);
+    const total = stableTotal(balances);
+    rows.push([chalk.gray("total"), chalk.white.bold("stablecoins"), "", `$${formatUsd(total.usd)}${total.errors.length > 0 ? chalk.red(" (some reads failed)") : ""}`]);
+    return makeTable(["Chain", "Token", "Balance", "USD Value"], rows);
+}
+async function balanceEntry(label, vm, address, testnet) {
+    const balances = vm === "solana" ? await getSolanaBalances(address, testnet) : await getEvmBalances(address, testnet);
+    const total = stableTotal(balances);
+    return { ...label, chain: vm, address, balances, stableUsd: total.usd, errors: total.errors };
+}
+/** Reads each distinct address once (several venues often share one key), in order. */
+async function balanceEntries(items, testnet) {
+    const seen = new Map();
+    const out = [];
+    for (const it of items) {
+        const key = `${it.vm}:${it.address.toLowerCase()}`;
+        const prev = seen.get(key);
+        if (prev !== undefined) {
+            if (it.label.exchange !== undefined)
+                prev.exchange = prev.exchange === undefined ? it.label.exchange : `${prev.exchange},${it.label.exchange}`;
+            continue;
         }
-        balances.push({
-            token: isTestnet ? "USDP" : "USDC",
-            balance: usdcBalance.toFixed(2),
-            usdValue: `$${formatUsd(usdcBalance)}`,
-        });
-    }
-    catch {
-        balances.push({ token: isTestnet ? "USDP" : "USDC", balance: "0.00", usdValue: "$0.00" });
-    }
-    try {
-        const res = await fetch("https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd");
-        const json = (await res.json());
-        balances[0].usdValue = `$${formatUsd(solBalance * (json.solana?.usd ?? 0))}`;
+        const entry = await balanceEntry(it.label, it.vm, it.address, testnet);
+        seen.set(key, entry);
+        out.push(entry);
     }
-    catch {
-        balances[0].usdValue = "-";
-    }
-    return balances;
+    return out;
 }
-async function getEvmBalances(address, isTestnet) {
-    const { ethers } = await import("ethers");
-    const rpcUrl = isTestnet
-        ? "https://sepolia-rollup.arbitrum.io/rpc"
-        : "https://arb1.arbitrum.io/rpc";
-    const provider = new ethers.JsonRpcProvider(rpcUrl);
-    const balances = [];
-    const ethBal = await provider.getBalance(address);
-    const ethBalance = Number(ethers.formatEther(ethBal));
-    balances.push({ token: "ETH", balance: ethBalance.toFixed(6), usdValue: "" });
-    const usdcAddr = isTestnet
-        ? "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
-        : "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
-    try {
-        const usdc = new ethers.Contract(usdcAddr, ["function balanceOf(address) view returns (uint256)"], provider);
-        const rawBal = await usdc.balanceOf(address);
-        const usdcBalance = Number(ethers.formatUnits(rawBal, 6));
-        balances.push({ token: "USDC", balance: usdcBalance.toFixed(2), usdValue: `$${formatUsd(usdcBalance)}` });
-    }
-    catch {
-        balances.push({ token: "USDC", balance: "0.00", usdValue: "$0.00" });
-    }
-    try {
-        const res = await fetch("https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd");
-        const json = (await res.json());
-        balances[0].usdValue = `$${formatUsd(ethBalance * (json.ethereum?.usd ?? 0))}`;
-    }
-    catch {
-        balances[0].usdValue = "-";
+/** Exactly one JSON document (an array of entries), or one table per entry. */
+function printBalanceEntries(entries, json) {
+    if (json)
+        return printJson(jsonOk(entries));
+    for (const e of entries) {
+        const who = [e.wallet, e.exchange].filter(x => x !== undefined).join(" / ");
+        console.log(chalk.cyan.bold(`\n  ${who} (${e.chain} ${e.address.slice(0, 8)}...)`));
+        console.log(balanceTable(e.balances));
     }
-    return balances;
+    console.log();
 }
 // ── Derive address from private key ──────────────────────────
 async function deriveSolanaAddress(key) {
@@ -816,7 +797,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
     // ── balance (by wallet name) ──
     wallet
         .command("balance [name]")
-        .description("Check on-chain balance for a saved wallet (or active wallet)")
+        .description("On-chain balances for a saved wallet (or the active one): gas token + USDC / USDT on Arbitrum, Ethereum, Base, BNB Chain, Robinhood Chain (USDG) and Solana")
         .option("--testnet", "Use testnet", false)
         .action(async (name, opts) => {
         const store = loadStore();
@@ -867,44 +848,25 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             if (activeEntries.length === 0) {
                 const settings = loadSettings();
                 if (settings.owsActiveWallet) {
+                    // Only loading the OWS vault may fall through to the env path; balance reads report
+                    // their own per-token errors and any other failure propagates.
+                    let owsAccounts = null;
                     try {
                         const { loadOws } = await import("../signer/ows-loader.js");
-                        const ows = loadOws();
-                        const owsWallet = ows.getWallet(settings.owsActiveWallet);
-                        const owsResults = [];
-                        for (const acct of owsWallet.accounts) {
-                            const isEvm = acct.chainId.startsWith("eip155:");
-                            const isSol = acct.chainId.startsWith("solana:");
-                            if (!isEvm && !isSol)
-                                continue;
-                            const address = acct.address;
-                            const balances = isSol
-                                ? await getSolanaBalances(address, opts.testnet)
-                                : await getEvmBalances(address, opts.testnet);
-                            if (isJson()) {
-                                owsResults.push({
-                                    wallet: settings.owsActiveWallet,
-                                    chain: isSol ? "solana" : "evm",
-                                    address,
-                                    balances,
-                                });
-                            }
-                            else {
-                                console.log(chalk.cyan.bold(`\n  ${settings.owsActiveWallet} (${isSol ? "solana" : "evm"} ${address.slice(0, 8)}...)`));
-                                const rows = balances.map((b) => [
-                                    chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-                                ]);
-                                console.log(makeTable(["Token", "Balance", "USD Value"], rows));
-                            }
-                        }
-                        if (isJson())
-                            printJson(jsonOk(owsResults));
-                        else
-                            console.log();
-                        return;
+                        owsAccounts = loadOws().getWallet(settings.owsActiveWallet).accounts;
                     }
                     catch {
-                        // OWS module unavailable or vault missing — fall through to env path
+                        owsAccounts = null; // OWS module unavailable or vault missing — use the env path below
+                    }
+                    if (owsAccounts !== null) {
+                        const results = [];
+                        for (const acct of owsAccounts) {
+                            const vm = acct.chainId.startsWith("solana:") ? "solana" : acct.chainId.startsWith("eip155:") ? "evm" : null;
+                            if (vm === null)
+                                continue;
+                            results.push(await balanceEntry({ wallet: settings.owsActiveWallet }, vm, acct.address, opts.testnet));
+                        }
+                        return printBalanceEntries(results, isJson());
                     }
                 }
                 const stored = loadEnvFile();
@@ -928,54 +890,13 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                     }
                     process.exit(1);
                 }
-                for (const we of envEntries) {
-                    if (!isJson())
-                        console.log(chalk.cyan.bold(`\n  ${we.exchange} (${we.address.slice(0, 8)}...)`));
-                    const balances = we.chain === "solana"
-                        ? await getSolanaBalances(we.address, opts.testnet)
-                        : await getEvmBalances(we.address, opts.testnet);
-                    if (isJson()) {
-                        printJson(jsonOk({ exchange: we.exchange, address: we.address, balances }));
-                        continue;
-                    }
-                    const rows = balances.map((b) => [
-                        chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-                    ]);
-                    console.log(makeTable(["Token", "Balance", "USD Value"], rows));
-                }
-                console.log();
-                return;
-            }
-            for (const ae of activeEntries) {
-                if (!isJson())
-                    console.log(chalk.cyan.bold(`\n  ${ae.name} (${ae.exchange})`));
-                const balances = ae.type === "solana"
-                    ? await getSolanaBalances(ae.address, opts.testnet)
-                    : await getEvmBalances(ae.address, opts.testnet);
-                if (isJson()) {
-                    printJson(jsonOk({ wallet: ae.name, exchange: ae.exchange, balances }));
-                    continue;
-                }
-                const rows = balances.map((b) => [
-                    chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-                ]);
-                console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+                return printBalanceEntries(await balanceEntries(envEntries.map(we => ({ label: { exchange: we.exchange }, vm: we.chain, address: we.address })), opts.testnet), isJson());
             }
-            console.log();
-            return;
+            return printBalanceEntries(await balanceEntries(activeEntries.map(ae => ({
+                label: { wallet: ae.name, exchange: ae.exchange }, vm: ae.type === "solana" ? "solana" : "evm", address: ae.address,
+            })), opts.testnet), isJson());
         }
-        if (!isJson())
-            console.log(chalk.cyan(`\n  Fetching balance for "${entry.name}" (${entry.address.slice(0, 8)}...)\n`));
-        const balances = entry.type === "solana"
-            ? await getSolanaBalances(entry.address, opts.testnet)
-            : await getEvmBalances(entry.address, opts.testnet);
-        if (isJson())
-            return printJson(jsonOk({ wallet: entry.name, balances }));
-        const rows = balances.map((b) => [
-            chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-        ]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
-        console.log();
+        return printBalanceEntries([await balanceEntry({ wallet: entry.name }, entry.type === "solana" ? "solana" : "evm", entry.address, opts.testnet)], isJson());
     });
     // ── direct address balance (kept for convenience) ──
     wallet
@@ -988,8 +909,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         const balances = await getSolanaBalances(address, opts.testnet);
         if (isJson())
             return printJson(jsonOk(balances));
-        const rows = balances.map((b) => [chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-")]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+        console.log(balanceTable(balances));
         console.log(chalk.gray(`\n  Network: ${opts.testnet ? "Devnet" : "Mainnet"}\n`));
     });
     wallet
@@ -999,11 +919,10 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .action(async (address, opts) => {
         if (!isJson())
             console.log(chalk.cyan(`\n  Fetching Arbitrum balances for ${address.slice(0, 8)}...${address.slice(-4)}\n`));
-        const balances = await getEvmBalances(address, opts.testnet);
+        const balances = await getEvmBalances(address, opts.testnet, [opts.testnet ? "arbitrum-sepolia" : "arbitrum"]);
         if (isJson())
             return printJson(jsonOk(balances));
-        const rows = balances.map((b) => [chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-")]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+        console.log(balanceTable(balances));
         console.log(chalk.gray(`\n  Network: Arbitrum ${opts.testnet ? "Sepolia" : "One"}\n`));
     });
     // ── migrate (legacy → OWS) ──

package/dist/cross-chain-margin.d.ts

@@ -15,14 +15,25 @@ export interface ChainMarginStatus {
     marginRatio: number;
     belowThreshold: boolean;
 }
+/** A venue whose margin could not be read: UNKNOWN (never healthy) — callers block new entries on it. */
+export interface ChainMarginUnknown {
+    exchange: string;
+    error: string;
+}
+export interface ChainMarginCheck {
+    statuses: ChainMarginStatus[];
+    /** Venues whose balance read failed / returned non-numeric values (margin unknown). */
+    unknown: ChainMarginUnknown[];
+}
 /**
  * Check margin status across all configured exchanges.
  *
  * @param adapters - Map of exchange name to adapter
  * @param minMarginPct - Warn when free margin / equity falls below this (default: 30%)
- * @returns Per-exchange margin status array
+ * @returns Per-exchange margin status, plus every venue whose margin is unknown (a failed
+ *          read is reported there — never dropped, so it can still block entries)
  */
-export declare function checkChainMargins(adapters: Map<string, ExchangeAdapter>, minMarginPct?: number): Promise<ChainMarginStatus[]>;
+export declare function checkChainMargins(adapters: Map<string, ExchangeAdapter>, minMarginPct?: number): Promise<ChainMarginCheck>;
 /**
  * Check if a specific exchange has critically low margin (below 15%).
  */
@@ -31,6 +42,22 @@ export declare function isCriticalMargin(status: ChainMarginStatus): boolean;
  * Check if a specific exchange should block new entries (below threshold).
  */
 export declare function shouldBlockEntries(status: ChainMarginStatus, minMarginPct?: number): boolean;
+/** Why new entries on a venue are blocked this cycle (closing / reducing stays allowed). */
+export interface MarginEntryBlock {
+    exchange: string;
+    level: "critical" | "low" | "unknown";
+    /** null when the margin is unknown */
+    marginPct: number | null;
+    /** Threshold breached; null when unknown */
+    threshold: number | null;
+    /** Read error when unknown */
+    error?: string;
+}
+/**
+ * Entry blocks from a margin check: critical (<15%), low (< minMarginPct), and UNKNOWN
+ * (failed read — never treated as healthy, so new entries are blocked on it too).
+ */
+export declare function marginEntryBlocks(check: ChainMarginCheck, minMarginPct?: number): MarginEntryBlock[];
 /**
  * Compute the optimal position size automatically based on:
  * 1. Orderbook depth on both sides

package/dist/cross-chain-margin.js

@@ -17,7 +17,8 @@ const EXCHANGE_CHAIN_MAP = {
  *
  * @param adapters - Map of exchange name to adapter
  * @param minMarginPct - Warn when free margin / equity falls below this (default: 30%)
- * @returns Per-exchange margin status array
+ * @returns Per-exchange margin status, plus every venue whose margin is unknown (a failed
+ *          read is reported there — never dropped, so it can still block entries)
  */
 export async function checkChainMargins(adapters, minMarginPct = 30) {
     const entries = [...adapters.entries()];
@@ -25,6 +26,9 @@ export async function checkChainMargins(adapters, minMarginPct = 30) {
         const bal = await adapter.getBalance();
         const equity = Number(bal.equity);
         const usedMargin = Number(bal.marginUsed);
+        if (!Number.isFinite(equity) || !Number.isFinite(usedMargin)) {
+            throw new Error(`balance returned non-numeric equity/marginUsed (${String(bal.equity)}/${String(bal.marginUsed)})`);
+        }
         const freeMargin = equity - usedMargin;
         // marginRatio = (freeMargin / equity) * 100
         // If equity is 0, ratio is 0 (critical). If no margin used, ratio is 100.
@@ -39,9 +43,15 @@ export async function checkChainMargins(adapters, minMarginPct = 30) {
             belowThreshold: marginRatio < minMarginPct,
         };
     }));
-    return results
-        .filter((r) => r.status === "fulfilled")
-        .map((r) => r.value);
+    const statuses = [];
+    const unknown = [];
+    results.forEach((r, i) => {
+        if (r.status === "fulfilled")
+            statuses.push(r.value);
+        else
+            unknown.push({ exchange: entries[i][0], error: r.reason instanceof Error ? r.reason.message : String(r.reason) });
+    });
+    return { statuses, unknown };
 }
 /**
  * Check if a specific exchange has critically low margin (below 15%).
@@ -55,6 +65,22 @@ export function isCriticalMargin(status) {
 export function shouldBlockEntries(status, minMarginPct = 30) {
     return status.marginRatio < minMarginPct;
 }
+/**
+ * Entry blocks from a margin check: critical (<15%), low (< minMarginPct), and UNKNOWN
+ * (failed read — never treated as healthy, so new entries are blocked on it too).
+ */
+export function marginEntryBlocks(check, minMarginPct = 30) {
+    const out = [];
+    for (const ms of check.statuses) {
+        if (isCriticalMargin(ms))
+            out.push({ exchange: ms.exchange, level: "critical", marginPct: ms.marginRatio, threshold: 15 });
+        else if (shouldBlockEntries(ms, minMarginPct))
+            out.push({ exchange: ms.exchange, level: "low", marginPct: ms.marginRatio, threshold: minMarginPct });
+    }
+    for (const u of check.unknown)
+        out.push({ exchange: u.exchange, level: "unknown", marginPct: null, threshold: null, error: u.error });
+    return out;
+}
 // ── Dynamic Auto-Sizing ──
 /**
  * Compute the optimal position size automatically based on: