perp-cli 0.14.1 → 0.14.2

package/dist/commands/portfolio.js

@@ -176,7 +176,7 @@ async function fetchExchangeEntry(exName, getAdapter) {
             adapter.getBalance(),
             adapter.getPositions(),
             adapter.getOpenOrders(),
-            adapter.getFundingPayments(200).catch(() => []),
+            adapter.getFundingPayments(200).then((rows) => ({ rows, error: null }), (e) => ({ rows: null, error: e instanceof Error ? e.message : String(e) })),
         ]);
         // Spot balances for every venue with def.spot (§12). Failures are surfaced on
         // stderr (the perp snapshot is still reported); unpriced tokens are excluded + warned.
@@ -200,8 +200,11 @@ async function fetchExchangeEntry(exName, getAdapter) {
             warn(`${def.displayName} spot balances unavailable: ${e instanceof Error ? e.message : String(e)}`);
         }
         const cutoff24h = Date.now() - 24 * 60 * 60 * 1000;
-        const recent = fundingPayments.filter(f => f.time >= cutoff24h);
-        const funding24h = recent.reduce((sum, f) => sum + Number(f.payment), 0);
+        if (fundingPayments.error !== null)
+            warn(`${def.displayName} funding history unavailable (funding24h null): ${fundingPayments.error}`);
+        const funding24h = fundingPayments.rows === null
+            ? null
+            : fundingPayments.rows.filter(f => f.time >= cutoff24h).reduce((sum, f) => sum + Number(f.payment), 0);
         // Shared balances (Pacifica USDC, HL unified USDC) are already in perp equity (§12.4 #8).
         const nonUsdcSpotValue = spot.filter(b => !b.shared).reduce((s, b) => s + b.valueUsd, 0);
         return {
@@ -227,6 +230,7 @@ async function fetchExchangeEntry(exName, getAdapter) {
             })),
             openOrders: orders.length,
             funding24h,
+            fundingError: fundingPayments.error,
             totalAccountValueUsd: Number(bal.equity) + nonUsdcSpotValue,
             error: null,
         };
@@ -240,7 +244,9 @@ async function fetchExchangeEntry(exName, getAdapter) {
             spot: [],
             positions: [],
             openOrders: 0,
-            funding24h: 0,
+            funding24h: null,
+            // The whole venue was unreadable: funding is unknown for the same reason.
+            fundingError: err instanceof Error ? err.message : String(err),
             totalAccountValueUsd: 0,
             error: err instanceof Error ? err.message : String(err),
         };
@@ -251,13 +257,17 @@ function buildTotals(entries) {
     let spotValueUsd = 0;
     let marginUsed = 0;
     let funding24h = 0;
+    let fundingIncomplete = false;
     let accountValueUsd = 0;
     for (const e of entries) {
         if (e.perp) {
             equity += Number(e.perp.equity);
             marginUsed += Number(e.perp.marginUsed);
         }
-        funding24h += e.funding24h;
+        if (e.funding24h === null)
+            fundingIncomplete = true;
+        else
+            funding24h += e.funding24h;
         // Non-USDC spot value (for unified accounts USDC is already in equity)
         const exSpot = e.isUnified
             ? e.spot.filter(b => b.token.replace(/-SPOT$/i, "").toUpperCase() !== "USDC")
@@ -272,7 +282,7 @@ function buildTotals(entries) {
     const marginPct = denom > 0 ? (marginUsed / denom) * 100 : 0;
     const level = marginPct < 30 ? "LOW" : marginPct < 60 ? "MEDIUM" : "HIGH";
     return {
-        totals: { equity, spotValueUsd, accountValueUsd, marginUsed, marginPct, funding24h },
+        totals: { equity, spotValueUsd, accountValueUsd, marginUsed, marginPct, funding24h, fundingIncomplete },
         risk: { level, marginPct },
     };
 }
@@ -537,7 +547,11 @@ async function runWatch(resolved, version, getAdapterForExchange, isJsonMode) {
 }
 // ── Serve mode (delegates to dashboard infra) ──────────────────────────────
 const KNOWN_HIP3_DEXES = ["xyz", "flx", "hyna", "km", "cash", "vntl"];
-async function checkDexPositions(address, dex) {
+/**
+ * Open-position count on a HIP-3 dex; null = the read failed (unknown — NOT "no positions").
+ * The failure is warned on stderr; callers must treat null as "may hold positions".
+ */
+export async function checkDexPositions(address, dex) {
     try {
         // Selected network (review L7): follows -n via setSharedApiNetwork (live binding).
         const res = await fetch(HYPERLIQUID_API_URL, {
@@ -545,15 +559,22 @@ async function checkDexPositions(address, dex) {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ type: "clearinghouseState", user: address, dex }),
         });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
         const state = await res.json();
-        const positions = (state?.assetPositions ?? []);
-        return positions.filter(p => {
+        if (!state || !Array.isArray(state.assetPositions))
+            throw new Error("clearinghouseState without assetPositions");
+        return state.assetPositions.filter(p => {
             const pos = (p.position ?? p);
-            return Number(pos.szi ?? 0) !== 0;
+            const szi = Number(pos.szi);
+            if (!Number.isFinite(szi))
+                throw new Error(`position without a numeric szi (${String(pos.coin)})`);
+            return szi !== 0;
         }).length;
     }
-    catch {
-        return 0;
+    catch (e) {
+        process.stderr.write(`[warn] hl:${dex} positions unknown (HIP-3 dex read failed; included in the dashboard): ${e instanceof Error ? e.message : String(e)}\n`);
+        return null;
     }
 }
 async function autoDetectHip3Dexes(address, getHLAdapterForDex, verbose) {
@@ -561,16 +582,22 @@ async function autoDetectHip3Dexes(address, getHLAdapterForDex, verbose) {
         dex,
         count: await checkDexPositions(address, dex),
     })));
-    const activeDexes = checks.filter(c => c.count > 0);
+    // Unknown (null) counts are included: a failed read must not hide a dex that may hold positions.
+    const activeDexes = checks.filter(c => c.count === null || c.count > 0);
     const results = [];
     for (const { dex, count } of activeDexes) {
         try {
             const adapter = await getHLAdapterForDex(dex);
             results.push({ name: `hl:${dex}`, adapter });
-            if (verbose)
-                console.log(chalk.green(`  ✓ hl:${dex} (HIP-3, ${count} position${count > 1 ? "s" : ""})`));
+            if (verbose) {
+                console.log(count === null
+                    ? chalk.yellow(`  ⚠ hl:${dex} (HIP-3, positions unknown — read failed)`)
+                    : chalk.green(`  ✓ hl:${dex} (HIP-3, ${count} position${count > 1 ? "s" : ""})`));
+            }
+        }
+        catch (e) {
+            process.stderr.write(`[warn] hl:${dex} left out of the dashboard (adapter unavailable${count === null ? ", positions unknown" : `, ${count} position(s)`}): ${e instanceof Error ? e.message : String(e)}\n`);
         }
-        catch { /* skip */ }
     }
     return results;
 }
@@ -578,12 +605,20 @@ async function runServe(resolved, getAdapterForExchange, isJsonMode, getHLAdapte
     const { startDashboard } = await import("../dashboard/index.js");
     if (isJsonMode) {
         const exchanges = [];
+        // A venue whose adapter failed is not monitored — reported in serve.errors + stderr, not dropped silently.
+        const errors = {};
+        const noteError = (name, e) => {
+            errors[name] = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`[warn] ${name} not monitored (adapter unavailable): ${errors[name]}\n`);
+        };
         for (const name of resolved.exchangeList) {
             try {
                 const adapter = await getAdapterForExchange(name);
                 exchanges.push({ name, adapter });
             }
-            catch { /* skip */ }
+            catch (e) {
+                noteError(name, e);
+            }
         }
         if (getHLAdapterForDex) {
             for (const dex of resolved.dexList) {
@@ -591,7 +626,9 @@ async function runServe(resolved, getAdapterForExchange, isJsonMode, getHLAdapte
                     const adapter = await getHLAdapterForDex(dex);
                     exchanges.push({ name: `hl:${dex}`, adapter });
                 }
-                catch { /* skip */ }
+                catch (e) {
+                    noteError(`hl:${dex}`, e);
+                }
             }
             if (resolved.autoDex && !resolved.dexList.length && resolved.exchangeList.includes("hyperliquid")) {
                 const hlEx = exchanges.find(e => e.name === "hyperliquid");
@@ -612,12 +649,13 @@ async function runServe(resolved, getAdapterForExchange, isJsonMode, getHLAdapte
             scope: resolved.scope,
             mode: "serve",
             exchanges: [],
-            totals: { equity: 0, spotValueUsd: 0, accountValueUsd: 0, marginUsed: 0, marginPct: 0, funding24h: 0 },
+            totals: { equity: 0, spotValueUsd: 0, accountValueUsd: 0, marginUsed: 0, marginPct: 0, funding24h: 0, fundingIncomplete: false },
             risk: { level: "LOW", marginPct: 0 },
             serve: {
                 url: `http://localhost:${dashboard.port}`,
                 port: dashboard.port,
                 exchanges: exchanges.map(e => e.name),
+                errors,
             },
         };
         printJson(jsonOk(data));
@@ -757,7 +795,7 @@ export function registerPortfolioCommand(program, getAdapterForExchange, isJson,
                     scope: resolved.scope,
                     mode: "health",
                     exchanges: [],
-                    totals: { equity: 0, spotValueUsd: 0, accountValueUsd: 0, marginUsed: 0, marginPct: 0, funding24h: 0 },
+                    totals: { equity: 0, spotValueUsd: 0, accountValueUsd: 0, marginUsed: 0, marginPct: 0, funding24h: 0, fundingIncomplete: false },
                     risk: { level: "LOW", marginPct: 0 },
                     health,
                 };

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

@@ -114,7 +114,7 @@ function balanceTable(balances) {
         b.chain,
         chalk.white.bold(b.token),
         b.balance === null ? chalk.red("read failed") : b.balance,
-        b.usdValue === null ? chalk.gray("-") : `$${formatUsd(b.usdValue)}`,
+        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)") : ""}`]);

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:

package/dist/dashboard/server.d.ts

@@ -4,7 +4,8 @@
  * Polls all configured exchange adapters and pushes updates to connected clients.
  * Includes cross-exchange arb data: funding rate comparison + dex arb scan.
  */
-import type { ExchangeAdapter, ExchangeBalance, ExchangePosition, ExchangeOrder, ExchangeMarketInfo } from "../exchanges/index.js";
+import type { ExchangeAdapter, ExchangeOrder, ExchangeMarketInfo } from "../exchanges/index.js";
+import { type DashboardBalance, type DashboardPosition } from "./ws-feeds.js";
 export interface DashboardExchange {
     name: string;
     adapter: ExchangeAdapter;
@@ -40,15 +41,40 @@ export interface DexAssetRow {
         oi: number;
     }[];
 }
-export interface DashboardSnapshot {
-    timestamp: string;
-    exchanges: {
+/**
+ * JSON shape served on /api/snapshot and pushed over the WS ("snapshot" messages).
+ *
+ * A venue part that could not be read is null — never a $0 balance / empty list:
+ *   exchanges[].balance / positions / orders: null = unavailable, the reason is in `error`.
+ *   exchanges[].balance.unrealizedPnl, positions[].entryPrice / markPrice / unrealizedPnl: null = unknown.
+ *   exchanges[].feed: live-feed health (WS manager only) — stale = no fresh data (see isFeedStale).
+ *   totals cover only the known values; totals.partial = some venue part was left out,
+ *   totals.unavailable lists which ("<venue>.<part>").
+ */
+export interface DashboardExchangeData {
+    name: string;
+    balance: DashboardBalance | null;
+    positions: DashboardPosition[] | null;
+    orders: ExchangeOrder[] | null;
+    topMarkets: ExchangeMarketInfo[];
+    /** Why topMarkets could not be refreshed (the list shown is the last good read); null = fresh. */
+    marketsError: string | null;
+    /** Why a part is null / the feed is stale; null = everything read. */
+    error: string | null;
+    feed?: {
+        mode: "ws" | "rest" | "connecting";
+        lastOkAt: number | null;
+        lastError: string | null;
+        stale: boolean;
+    };
+    dexBalances?: {
         name: string;
-        balance: ExchangeBalance;
-        positions: ExchangePosition[];
-        orders: ExchangeOrder[];
-        topMarkets: ExchangeMarketInfo[];
+        balance: DashboardBalance | null;
     }[];
+}
+export interface DashboardSnapshot {
+    timestamp: string;
+    exchanges: DashboardExchangeData[];
     totals: {
         equity: number;
         available: number;
@@ -56,6 +82,10 @@ export interface DashboardSnapshot {
         unrealizedPnl: number;
         positionCount: number;
         orderCount: number;
+        /** true = some venue part (or a stale feed) is not reflected in these sums. */
+        partial: boolean;
+        /** "<venue>.<part>" left out of the sums (balance, unrealizedPnl, positions, orders, stale). */
+        unavailable: string[];
     };
     arb: {
         opportunities: ArbOpportunity[];
@@ -73,6 +103,13 @@ export interface DashboardOpts {
     arbInterval?: number;
     signal?: AbortSignal;
 }
+/**
+ * REST read of every venue. A failed read is null + its reason in `error` — never a $0
+ * balance or an empty position / order list (those would read as "flat, no money").
+ */
+export declare function readExchangesRest(exchanges: DashboardExchange[]): Promise<DashboardExchangeData[]>;
+/** Merge HL dex entries + compute totals. Unknown (null) parts are skipped and listed in totals.unavailable. */
+export declare function mergeAndTotal(exchangeData: DashboardExchangeData[]): DashboardSnapshot;
 /**
  * Start the dashboard HTTP + WebSocket server.
  */