perp-cli 0.14.0 → 0.14.2

package/dist/dashboard/ws-feeds.js

@@ -6,14 +6,36 @@
  * Arb/market data stays on REST (cross-exchange aggregation, no single WS covers it).
  */
 import { WebSocket as NodeWebSocket } from "ws";
-const EMPTY_BALANCE = { equity: "0", available: "0", marginUsed: "0", unrealizedPnl: "0" };
+/** Venue number → string, or null when the field is absent / not a finite number. */
+function numStr(v) {
+    if (v === null || v === undefined || v === "")
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? String(v) : null;
+}
+/** A feed is stale when it has no data yet, its last failure is newer than its last success,
+ *  or (polling mode) its last success is older than this. */
+export const FEED_STALE_MS = 30_000;
+export function isFeedStale(state, now = Date.now()) {
+    if (state.lastOkAt === null)
+        return true;
+    if (state.lastErrorAt !== null && state.lastErrorAt > state.lastOkAt)
+        return true;
+    return state.mode !== "ws" && now - state.lastOkAt > FEED_STALE_MS;
+}
+/** Log the first failure of a source, then every Nth consecutive one (avoid log spam). */
+const LOG_EVERY_N_FAILURES = 20;
 const MAX_RECONNECT_DELAY = 30_000;
 // ── Base WS Feed ──
 class ExchangeWsFeed {
     exchange;
     onUpdate;
     ws = null;
-    state = { balance: { ...EMPTY_BALANCE }, positions: [], orders: [], lastUpdate: 0, mode: "connecting" };
+    state = {
+        balance: null, positions: null, orders: null, lastUpdate: 0, mode: "connecting",
+        lastOkAt: null, lastError: null, lastErrorAt: null,
+    };
+    failureCounts = new Map();
     reconnectDelay = 1000;
     reconnectTimer = null;
     closed = false;
@@ -27,6 +49,29 @@ class ExchangeWsFeed {
         this.onUpdate = onUpdate;
     }
     getState() { return this.state; }
+    /** A read / parse succeeded: the data is fresh again. */
+    recordOk(source) {
+        this.state.lastOkAt = Date.now();
+        this.failureCounts.delete(source);
+    }
+    /** A read / parse failed: record it on the state (the UI marks the feed stale) and log it
+     *  on the first failure and every LOG_EVERY_N_FAILURES consecutive ones after that. */
+    recordError(source, err) {
+        const msg = this.logFailure(source, err);
+        this.state.lastError = `${source}: ${msg}`;
+        this.state.lastErrorAt = Date.now();
+        this.onUpdate(this.state);
+    }
+    /** Log-only (data is still flowing from another path, e.g. REST while WS reconnects). */
+    logFailure(source, err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const n = (this.failureCounts.get(source) ?? 0) + 1;
+        this.failureCounts.set(source, n);
+        if (n === 1 || n % LOG_EVERY_N_FAILURES === 0) {
+            process.stderr.write(`[warn] dashboard ${this.exchange.name} ${source} failed (${n}x): ${msg}\n`);
+        }
+        return msg;
+    }
     /** Start a timer: if no WS data arrives within WS_DATA_TIMEOUT, switch to REST */
     startWsDataTimeout() {
         if (this.wsDataTimer)
@@ -40,6 +85,7 @@ class ExchangeWsFeed {
     }
     emitUpdate() {
         this.state.lastUpdate = Date.now();
+        this.state.lastOkAt = this.state.lastUpdate;
         this.wsDataReceived = true;
         // WS is delivering data — stop REST fallback if running
         if (this.state.mode === "rest" && this.ws?.readyState === NodeWebSocket.OPEN) {
@@ -54,9 +100,13 @@ class ExchangeWsFeed {
         try {
             const { setCached, TTL_ACCOUNT } = await import("../cache.js");
             const name = this.exchange.name;
-            setCached(`dash:${name}:balance`, this.state.balance, TTL_ACCOUNT);
-            setCached(`dash:${name}:positions`, this.state.positions, TTL_ACCOUNT);
-            setCached(`dash:${name}:orders`, this.state.orders, TTL_ACCOUNT);
+            // Only data actually read is shared — an unread (null) part is never cached as empty.
+            if (this.state.balance)
+                setCached(`dash:${name}:balance`, this.state.balance, TTL_ACCOUNT);
+            if (this.state.positions)
+                setCached(`dash:${name}:positions`, this.state.positions, TTL_ACCOUNT);
+            if (this.state.orders)
+                setCached(`dash:${name}:orders`, this.state.orders, TTL_ACCOUNT);
         }
         catch { /* non-fatal */ }
     }
@@ -67,8 +117,11 @@ class ExchangeWsFeed {
             try {
                 await this.connect();
                 this.reconnectDelay = 1000; // reset on success
+                this.failureCounts.delete("ws-reconnect");
             }
-            catch {
+            catch (e) {
+                // REST fallback keeps the data flowing; the reconnect failure is logged, not hidden.
+                this.logFailure("ws-reconnect", e);
                 this.reconnectDelay = Math.min(this.reconnectDelay * 2, MAX_RECONNECT_DELAY);
                 this.scheduleReconnect();
             }
@@ -91,7 +144,10 @@ class ExchangeWsFeed {
                 this.state.orders = orders;
                 this.emitUpdate();
             }
-            catch { /* ignore */ }
+            catch (e) {
+                // Keep the last-read data but mark the feed stale (lastError) — never blank it to 0 / empty.
+                this.recordError("rest-poll", e);
+            }
         };
         doRestPoll(); // immediate first fetch
         this.restFallbackTimer = setInterval(doRestPoll, 5000);
@@ -161,7 +217,9 @@ class HyperliquidFeed extends ExchangeWsFeed {
                             this.handleWebData2(msg.data);
                         }
                     }
-                    catch { /* ignore parse errors */ }
+                    catch (e) {
+                        this.recordError("ws-parse", e);
+                    }
                 });
                 this.ws.on("close", () => {
                     this.stopBalancePolling();
@@ -190,8 +248,11 @@ class HyperliquidFeed extends ExchangeWsFeed {
         const poll = async () => {
             try {
                 this.state.balance = await this.exchange.adapter.getBalance();
+                this.recordOk("balance-poll");
+            }
+            catch (e) {
+                this.recordError("balance-poll", e);
             }
-            catch { /* ignore */ }
         };
         poll(); // immediate
         this.balanceTimer = setInterval(poll, 5000);
@@ -212,19 +273,24 @@ class HyperliquidFeed extends ExchangeWsFeed {
                 this.state.positions = assetPositions
                     .filter((ap) => {
                     const pos = (ap.position ?? ap);
-                    return Number(pos.szi ?? 0) !== 0;
+                    const szi = numStr(pos.szi);
+                    if (szi === null)
+                        throw new Error(`webData2 position without szi: ${JSON.stringify(pos).slice(0, 200)}`);
+                    return Number(szi) !== 0;
                 })
                     .map((ap) => {
                     const pos = (ap.position ?? ap);
                     const szi = Number(pos.szi);
+                    const posValue = numStr(pos.positionValue);
                     return {
                         symbol: String(pos.coin ?? ""),
                         side: (szi > 0 ? "long" : "short"),
                         size: String(Math.abs(szi)),
-                        entryPrice: pos.entryPx ?? "0",
-                        markPrice: String(pos.positionValue ? (Number(pos.positionValue) / Math.abs(szi)).toFixed(2) : "0"),
+                        // A field the message did not carry is unknown (null), never "0".
+                        entryPrice: numStr(pos.entryPx),
+                        markPrice: posValue !== null ? (Number(posValue) / Math.abs(szi)).toFixed(2) : null,
                         liquidationPrice: pos.liquidationPx ?? null, // HL sends null when there is no liquidation price
-                        unrealizedPnl: pos.unrealizedPnl ?? "0",
+                        unrealizedPnl: numStr(pos.unrealizedPnl),
                         leverage: Number(ap.leverage?.value ?? 1),
                     };
                 });
@@ -246,7 +312,9 @@ class HyperliquidFeed extends ExchangeWsFeed {
             }
             this.emitUpdate();
         }
-        catch { /* ignore */ }
+        catch (e) {
+            this.recordError("ws-webData2", e);
+        }
     }
     close() {
         this.stopBalancePolling();
@@ -302,7 +370,9 @@ class PacificaFeed extends ExchangeWsFeed {
                         else if (ch === "account_order_updates")
                             this.handleOrders(msg.data ?? msg);
                     }
-                    catch { /* ignore */ }
+                    catch (e) {
+                        this.recordError("ws-parse", e);
+                    }
                 });
                 this.ws.on("close", () => {
                     this.clearHeartbeat();
@@ -342,28 +412,35 @@ class PacificaFeed extends ExchangeWsFeed {
                 for (const p of positions) {
                     this.markPrices.set(p.symbol, p.markPrice);
                 }
+                this.recordOk("mark-poll");
                 // Update existing WS positions with mark prices + compute PnL
-                if (this.state.positions.length > 0) {
+                if (this.state.positions && this.state.positions.length > 0) {
                     let changed = false;
                     for (const pos of this.state.positions) {
                         const mark = this.markPrices.get(pos.symbol);
-                        if (mark && mark !== "0" && pos.markPrice === "0") {
+                        if (mark && Number(mark) > 0 && pos.markPrice !== mark) {
                             pos.markPrice = mark;
-                            const markNum = Number(mark);
-                            const entry = Number(pos.entryPrice);
-                            const amount = Number(pos.size);
-                            const pnl = pos.side === "long"
-                                ? (markNum - entry) * amount
-                                : (entry - markNum) * amount;
-                            pos.unrealizedPnl = pnl.toFixed(4);
+                            if (pos.entryPrice !== null) {
+                                const markNum = Number(mark);
+                                const entry = Number(pos.entryPrice);
+                                const amount = Number(pos.size);
+                                const pnl = pos.side === "long"
+                                    ? (markNum - entry) * amount
+                                    : (entry - markNum) * amount;
+                                pos.unrealizedPnl = pnl.toFixed(4);
+                            }
                             changed = true;
                         }
                     }
+                    if (changed && this.state.balance)
+                        this.state.balance = { ...this.state.balance, unrealizedPnl: this.positionsUpnl() };
                     if (changed)
                         this.emitUpdate();
                 }
             }
-            catch { /* ignore */ }
+            catch (e) {
+                this.recordError("mark-poll", e);
+            }
         };
         poll(); // immediate
         this.markPriceTimer = setInterval(poll, 5000);
@@ -376,57 +453,86 @@ class PacificaFeed extends ExchangeWsFeed {
     }
     handleAccountInfo(data) {
         // Abbreviated fields: ae=account_equity, as=available_to_spend, mu=margin_used
-        const eq = String(data.ae ?? data.account_equity ?? this.state.balance.equity);
-        const av = String(data.as ?? data.available_to_spend ?? this.state.balance.available);
-        const mu = String(data.mu ?? data.margin_used ?? this.state.balance.marginUsed);
-        this.state.balance = { equity: eq, available: av, marginUsed: mu, unrealizedPnl: this.state.balance.unrealizedPnl };
+        // A field missing from this (partial) update keeps its previously-read value; with no
+        // previous value it is unknown → the update is rejected (recorded), never read as 0.
+        const prev = this.state.balance;
+        const eq = numStr(data.ae ?? data.account_equity) ?? prev?.equity;
+        const av = numStr(data.as ?? data.available_to_spend) ?? prev?.available;
+        const mu = numStr(data.mu ?? data.margin_used) ?? prev?.marginUsed;
+        if (eq == null || av == null || mu == null) {
+            this.recordError("ws-account_info", new Error("account_info without equity / available / margin_used"));
+            return;
+        }
+        // account_info carries no unrealized PnL: the sum of the positions' PnL when all are known, else null.
+        this.state.balance = { equity: eq, available: av, marginUsed: mu, unrealizedPnl: this.positionsUpnl() };
         this.emitUpdate();
     }
+    /** Sum of the positions' unrealized PnL; null when positions are unread or any PnL is unknown. */
+    positionsUpnl() {
+        const ps = this.state.positions;
+        if (!ps || ps.some(p => p.unrealizedPnl === null))
+            return null;
+        return ps.reduce((s, p) => s + Number(p.unrealizedPnl), 0).toFixed(4);
+    }
     handlePositions(data) {
         if (!Array.isArray(data))
             return;
         // WS uses abbreviated fields: s=symbol, d=side, a=amount, p=entry_price, l=liquidation, m=margin
-        this.state.positions = data
-            .filter((p) => {
-            const amount = Number(p.a ?? p.amount ?? 0);
+        const positions = [];
+        for (const p of data) {
             const symbol = p.s ?? p.symbol;
-            return amount !== 0 && symbol;
-        })
-            .map((p) => {
-            const symbol = String(p.s ?? p.symbol ?? "");
+            const amount = numStr(p.a ?? p.amount);
+            if (!symbol || amount === null) {
+                // A row without a symbol / amount cannot be shown — reported, not read as "no position".
+                this.recordError("ws-account_positions", new Error(`position row without symbol/amount: ${JSON.stringify(p).slice(0, 200)}`));
+                continue;
+            }
+            const size = Number(amount);
+            if (size === 0)
+                continue;
             const side = String(p.d ?? p.side ?? "") === "bid" ? "long" : "short";
-            const size = Number(p.a ?? p.amount ?? 0);
-            const entryPrice = Number(p.p ?? p.entry_price ?? 0);
-            const mark = this.markPrices.get(symbol);
-            const markNum = mark ? Number(mark) : 0;
-            const pnl = markNum > 0
-                ? (side === "long" ? (markNum - entryPrice) * size : (entryPrice - markNum) * size)
-                : 0;
-            return {
-                symbol,
+            const entry = numStr(p.p ?? p.entry_price);
+            const mark = this.markPrices.get(String(symbol)) ?? null;
+            const markNum = mark !== null ? Number(mark) : NaN;
+            // PnL needs both prices; unknown (null) otherwise — never 0.
+            const pnl = entry !== null && markNum > 0
+                ? (side === "long" ? (markNum - Number(entry)) * size : (Number(entry) - markNum) * size).toFixed(4)
+                : null;
+            positions.push({
+                symbol: String(symbol),
                 side,
                 size: String(size),
-                entryPrice: String(entryPrice),
-                markPrice: mark ?? "0",
+                entryPrice: entry,
+                markPrice: mark,
                 liquidationPrice: p.l != null ? String(p.l) : p.liquidation_price != null ? String(p.liquidation_price) : null,
-                unrealizedPnl: pnl.toFixed(4),
+                unrealizedPnl: pnl,
                 leverage: Number(p.leverage ?? 1),
-            };
-        });
+            });
+        }
+        this.state.positions = positions;
+        if (this.state.balance)
+            this.state.balance = { ...this.state.balance, unrealizedPnl: this.positionsUpnl() };
         this.emitUpdate();
     }
     handleOrders(data) {
         if (!Array.isArray(data))
             return;
-        this.state.orders = data
-            .filter((o) => String(o.os ?? o.order_status ?? "") === "open")
+        const open = data.filter((o) => String(o.os ?? o.order_status ?? "") === "open");
+        // A row without a readable price / size / filled amount is reported, never shown as "0".
+        const readable = open.filter((o) => {
+            const ok = numStr(o.p ?? o.price) !== null && numStr(o.a ?? o.amount) !== null && numStr(o.f ?? o.filled) !== null;
+            if (!ok)
+                this.recordError("order-row", `order ${String(o.i ?? o.order_id ?? "?")} without price / amount / filled`);
+            return ok;
+        });
+        this.state.orders = readable
             .map((o) => ({
             orderId: String(o.i ?? o.order_id ?? ""),
             symbol: String(o.s ?? o.symbol ?? ""),
             side: (o.d ?? o.side) === "bid" ? "buy" : "sell",
-            price: String(o.p ?? o.price ?? "0"),
-            size: String(o.a ?? o.amount ?? ""),
-            filled: String(o.f ?? o.filled ?? "0"),
+            price: numStr(o.p ?? o.price),
+            size: numStr(o.a ?? o.amount),
+            filled: numStr(o.f ?? o.filled),
             status: "open",
             type: String(o.ot ?? o.order_type ?? ""),
             triggerPrice: Number(o.sp ?? o.stop_price) > 0 ? String(o.sp ?? o.stop_price) : null,
@@ -470,7 +576,9 @@ class LighterFeed extends ExchangeWsFeed {
             const auth = await adapter.signer.createAuthToken(deadline);
             return auth.authToken;
         }
-        catch {
+        catch (e) {
+            // No token → REST polling serves the data; the signer failure is logged, not hidden.
+            this.logFailure("ws-auth", e);
             return null;
         }
     }
@@ -510,7 +618,9 @@ class LighterFeed extends ExchangeWsFeed {
                         const msg = JSON.parse(String(raw));
                         this.handleMessage(msg);
                     }
-                    catch { /* ignore */ }
+                    catch (e) {
+                        this.recordError("ws-parse", e);
+                    }
                 });
                 this.ws.on("close", () => {
                     if (!this.closed) {
@@ -540,11 +650,23 @@ class LighterFeed extends ExchangeWsFeed {
             const stats = (msg.stats ?? msg);
             // total_stats includes cross-margin + isolated totals
             const src = (stats.total_stats ?? stats);
-            const equity = String(src.portfolio_value ?? src.collateral ?? this.state.balance.equity);
-            const available = String(src.available_balance ?? this.state.balance.available);
-            const marginUsed = String(src.margin_usage ?? this.state.balance.marginUsed);
-            this.state.balance = { equity, available, marginUsed, unrealizedPnl: this.state.balance.unrealizedPnl };
-            this.emitUpdate();
+            // A field missing from this update keeps its previously-read value; never read as 0.
+            const prev = this.state.balance;
+            const equity = numStr(src.portfolio_value ?? src.collateral) ?? prev?.equity;
+            const available = numStr(src.available_balance) ?? prev?.available;
+            const marginUsed = numStr(src.margin_usage) ?? prev?.marginUsed;
+            if (equity == null || available == null || marginUsed == null) {
+                this.recordError("ws-user_stats", new Error("user_stats without portfolio_value / available_balance / margin_usage"));
+            }
+            else {
+                // user_stats carries no unrealized PnL: the sum over the positions when all are known, else null.
+                const ps = this.state.positions;
+                const upnl = ps && ps.every(p => p.unrealizedPnl !== null)
+                    ? ps.reduce((s, p) => s + Number(p.unrealizedPnl), 0).toFixed(4)
+                    : null;
+                this.state.balance = { equity, available, marginUsed, unrealizedPnl: upnl };
+                this.emitUpdate();
+            }
         }
         // Positions: subscribed/ = full snapshot, update/ = incremental
         if (type.includes("account_all_positions")) {
@@ -566,19 +688,26 @@ class LighterFeed extends ExchangeWsFeed {
                 }
                 // Rebuild positions from map
                 this.state.positions = [...this.positionMap.values()]
-                    .filter(p => Number(p.position ?? 0) !== 0)
+                    .filter(p => {
+                    // A position entry without a size cannot be shown — reported, not read as flat.
+                    if (numStr(p.position) === null) {
+                        this.recordError("ws-account_all_positions", new Error(`position without size (market ${String(p.market_id)})`));
+                        return false;
+                    }
+                    return Number(p.position) !== 0;
+                })
                     .map(p => {
-                    const posSize = Number(p.position ?? 0);
+                    const posSize = Number(p.position);
+                    const posValue = numStr(p.position_value);
                     return {
                         symbol: String(p.symbol ?? `Market-${p.market_id}`),
                         side: (Number(p.sign) > 0 ? "long" : "short"),
                         size: String(Math.abs(posSize)),
-                        entryPrice: String(p.avg_entry_price ?? "0"),
-                        markPrice: posSize !== 0
-                            ? String((Number(p.position_value ?? 0) / Math.abs(posSize)).toFixed(4))
-                            : "0",
+                        // A field the message did not carry is unknown (null), never "0".
+                        entryPrice: numStr(p.avg_entry_price),
+                        markPrice: posValue !== null ? String((Number(posValue) / Math.abs(posSize)).toFixed(4)) : null,
                         liquidationPrice: p.liquidation_price ? String(p.liquidation_price) : null,
-                        unrealizedPnl: String(p.unrealized_pnl ?? "0"),
+                        unrealizedPnl: numStr(p.unrealized_pnl),
                         leverage: Number(p.initial_margin_fraction ?? 0) > 0
                             ? Math.round(10000 / Number(p.initial_margin_fraction))
                             : 1,
@@ -592,19 +721,27 @@ class LighterFeed extends ExchangeWsFeed {
             const orders = msg.orders;
             if (orders) {
                 const allOrders = Object.values(orders).flat();
-                this.state.orders = allOrders
-                    .filter(o => String(o.status ?? "") === "open")
-                    .map(o => ({
-                    orderId: String(o.order_id ?? o.order_index ?? ""),
-                    symbol: String(o.symbol ?? ""),
-                    side: (o.side === "buy" || o.is_ask === false ? "buy" : "sell"),
-                    price: String(o.price ?? "0"),
-                    size: String(o.remaining_base_amount ?? o.initial_base_amount ?? ""),
-                    filled: String(o.filled_base_amount ?? "0"),
-                    status: "open",
-                    type: String(o.type ?? "limit"),
-                    triggerPrice: Number(o.trigger_price) > 0 ? String(o.trigger_price) : null,
-                }));
+                // A row without a readable price / size / filled / type is reported, never shown as "0" / "limit".
+                const rows = [];
+                for (const o of allOrders.filter(o => String(o.status ?? "") === "open")) {
+                    const price = numStr(o.price);
+                    const size = numStr(o.remaining_base_amount ?? o.initial_base_amount);
+                    const filled = numStr(o.filled_base_amount);
+                    if (price === null || size === null || filled === null || typeof o.type !== "string" || o.type === "") {
+                        this.recordError("order-row", `order ${String(o.order_id ?? o.order_index ?? "?")} without price / size / filled / type`);
+                        continue;
+                    }
+                    rows.push({
+                        orderId: String(o.order_id ?? o.order_index ?? ""),
+                        symbol: String(o.symbol ?? ""),
+                        side: (o.side === "buy" || o.is_ask === false ? "buy" : "sell"),
+                        price, size, filled,
+                        status: "open",
+                        type: o.type,
+                        triggerPrice: Number(o.trigger_price) > 0 ? String(o.trigger_price) : null,
+                    });
+                }
+                this.state.orders = rows;
                 this.emitUpdate();
             }
         }

package/dist/dex-asset-map.d.ts

@@ -52,7 +52,23 @@ export interface DexArbPair {
     viability: "A" | "B" | "C" | "D";
 }
 /**
- * Fetch all assets from all Hyperliquid dexes (native + deployed).
+ * Result of one all-dex read. `failedDexes` maps each dex whose metaAndAssetCtxs read
+ * failed (timeout / 429 / …) to its error: that dex's assets are UNKNOWN, not absent —
+ * a consumer must never treat a pair on a failed dex as gone.
+ */
+export interface DexAssetsResult {
+    assets: DexAsset[];
+    failedDexes: Record<string, string>;
+}
+/**
+ * Fetch all assets from all Hyperliquid dexes (native + deployed), with the dexes whose
+ * read failed. Only a complete read (no failed dex) is cached.
+ */
+export declare function fetchAllDexAssetsDetailed(): Promise<DexAssetsResult>;
+/**
+ * Fetch all assets from all Hyperliquid dexes (display use). A dex whose read failed is
+ * reported on stderr (its assets are missing from the result). Trading paths use
+ * fetchAllDexAssetsDetailed() so a failed dex is never mistaken for an absent pair.
  */
 export declare function fetchAllDexAssets(): Promise<DexAsset[]>;
 /**
@@ -70,11 +86,14 @@ export declare function findDexArbPairs(assets: DexAsset[], opts?: {
     includeNative?: boolean;
 }): DexArbPair[];
 /**
- * Fetch and return arb opportunities across all HIP-3 dexes.
- * Single convenience function for CLI commands.
+ * Fetch and return arb opportunities across all HIP-3 dexes, plus the dexes whose read
+ * failed (pairs on those dexes are unknown this scan — not gone).
  */
 export declare function scanDexArb(opts?: {
     minAnnualSpread?: number;
     maxPriceGapPct?: number;
     includeNative?: boolean;
-}): Promise<DexArbPair[]>;
+}): Promise<{
+    pairs: DexArbPair[];
+    failedDexes: Record<string, string>;
+}>;

package/dist/dex-asset-map.js

@@ -56,17 +56,37 @@ async function hlInfoPost(body) {
     return res.json();
 }
 /**
- * Fetch all assets from all Hyperliquid dexes (native + deployed).
+ * Fetch all assets from all Hyperliquid dexes (native + deployed), with the dexes whose
+ * read failed. Only a complete read (no failed dex) is cached.
  */
-export async function fetchAllDexAssets() {
-    const { withCache, TTL_MARKET } = await import("./cache.js");
+export async function fetchAllDexAssetsDetailed() {
+    const { getCached, setCached, TTL_MARKET } = await import("./cache.js");
     // Network in the key: a mainnet snapshot must never answer a testnet run (L7).
-    return withCache(`pub:hl:${sharedApiNetwork()}:allDexAssets`, TTL_MARKET, () => _fetchAllDexAssetsLive());
+    const key = `pub:hl:${sharedApiNetwork()}:allDexAssets`;
+    const cached = getCached(key);
+    if (cached !== null)
+        return { assets: cached, failedDexes: {} };
+    const res = await _fetchAllDexAssetsLive();
+    if (Object.keys(res.failedDexes).length === 0)
+        setCached(key, res.assets, TTL_MARKET);
+    return res;
+}
+/**
+ * Fetch all assets from all Hyperliquid dexes (display use). A dex whose read failed is
+ * reported on stderr (its assets are missing from the result). Trading paths use
+ * fetchAllDexAssetsDetailed() so a failed dex is never mistaken for an absent pair.
+ */
+export async function fetchAllDexAssets() {
+    const { assets, failedDexes } = await fetchAllDexAssetsDetailed();
+    for (const [dex, err] of Object.entries(failedDexes)) {
+        process.stderr.write(`[perp] HIP-3 dex ${dex} unavailable: ${err} — its assets are missing from this read\n`);
+    }
+    return assets;
 }
 async function _fetchAllDexAssetsLive() {
     const allMetas = await hlInfoPost({ type: "allPerpMetas" });
     if (!Array.isArray(allMetas))
-        return [];
+        throw new Error("HL API error: allPerpMetas returned a non-array response");
     // Collect dex names (index 0 = native "hl", rest = deployed dexes)
     const dexNames = [];
     for (let i = 0; i < allMetas.length; i++) {
@@ -86,6 +106,7 @@ async function _fetchAllDexAssetsLive() {
     // Fetch metaAndAssetCtxs for each dex in batches of 3 to avoid 429 rate limits
     const BATCH_SIZE = 3;
     const allAssets = [];
+    const failedDexes = {};
     const tasks = dexNames.map((dex, i) => ({ dex, i })).filter(t => t.dex !== "");
     for (let b = 0; b < tasks.length; b += BATCH_SIZE) {
         const batch = tasks.slice(b, b + BATCH_SIZE);
@@ -95,8 +116,11 @@ async function _fetchAllDexAssetsLive() {
                     ? { type: "metaAndAssetCtxs" }
                     : { type: "metaAndAssetCtxs", dex };
                 const data = await hlInfoPost(body);
-                const universe = data[0]?.universe ?? [];
-                const ctxs = data[1] ?? [];
+                if (!Array.isArray(data) || !Array.isArray(data[0]?.universe) || !Array.isArray(data[1])) {
+                    throw new Error("metaAndAssetCtxs returned an unexpected shape");
+                }
+                const universe = data[0].universe;
+                const ctxs = data[1];
                 return universe
                     .map((asset, j) => {
                     if (asset.isDelisted)
@@ -118,13 +142,15 @@ async function _fetchAllDexAssetsLive() {
                 })
                     .filter((a) => a !== null && a.markPrice > 0);
             }
-            catch {
+            catch (e) {
+                // Explicit, not empty: the dex's assets are unknown this read.
+                failedDexes[dex] = e instanceof Error ? e.message : String(e);
                 return [];
             }
         }));
         allAssets.push(...results.flat());
     }
-    return allAssets;
+    return { assets: allAssets, failedDexes };
 }
 /**
  * Normalize a base name to its canonical underlying.
@@ -194,10 +220,10 @@ export function findDexArbPairs(assets, opts = {}) {
     return pairs.sort((a, b) => b.annualSpread - a.annualSpread);
 }
 /**
- * Fetch and return arb opportunities across all HIP-3 dexes.
- * Single convenience function for CLI commands.
+ * Fetch and return arb opportunities across all HIP-3 dexes, plus the dexes whose read
+ * failed (pairs on those dexes are unknown this scan — not gone).
  */
 export async function scanDexArb(opts) {
-    const assets = await fetchAllDexAssets();
-    return findDexArbPairs(assets, opts);
+    const { assets, failedDexes } = await fetchAllDexAssetsDetailed();
+    return { pairs: findDexArbPairs(assets, opts), failedDexes };
 }