perp-cli 0.14.1 → 0.14.2

package/dist/dashboard/server.js

@@ -7,11 +7,13 @@
 import { createServer } from "http";
 import { WebSocketServer, WebSocket } from "ws";
 import { getUI } from "./ui.js";
-import { WsFeedManager } from "./ws-feeds.js";
+import { WsFeedManager, isFeedStale } from "./ws-feeds.js";
 // Cached arb data (polled less frequently)
 let cachedArb = { opportunities: [], dexArb: [], dexAssets: [], dexNames: [], exchangeStatus: {}, exchangeErrors: {} };
 // Cached market data (polled with arb cycle — market metadata rarely changes)
 const cachedMarkets = new Map();
+/** venue → why its last markets refresh failed (cleared on the next good read). */
+const marketsErrors = new Map();
 /**
  * Find an available port starting from the given port.
  */
@@ -112,8 +114,10 @@ async function pollArbData() {
             return spreadB - spreadA;
         });
     }
-    catch {
-        // dex arb unavailable
+    catch (e) {
+        // Reported next to the funding errors — an empty dex table is never shown as "no opportunities".
+        exchangeStatus = { ...exchangeStatus, dexArb: "error" };
+        exchangeErrors = { ...exchangeErrors, dexArb: e instanceof Error ? e.message : String(e) };
     }
     const dexNames = [...dexNamesSet].sort();
     return { opportunities, dexArb, dexAssets: dexAssets.slice(0, 30), dexNames, exchangeStatus, exchangeErrors };
@@ -127,9 +131,14 @@ async function pollMarkets(exchanges) {
         try {
             const markets = await ex.adapter.getMarkets();
             cachedMarkets.set(ex.name, markets.slice(0, 10));
+            marketsErrors.delete(ex.name);
         }
-        catch {
-            // keep previous cached data
+        catch (e) {
+            // The last good list stays on screen, flagged by marketsError (never shown as fresh).
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!marketsErrors.has(ex.name))
+                process.stderr.write(`[warn] dashboard ${ex.name} markets refresh failed: ${msg}\n`);
+            marketsErrors.set(ex.name, msg);
         }
     }));
 }
@@ -139,13 +148,20 @@ function buildSnapshotFromFeeds(feedMgr, exchanges) {
     let exchangeData = [];
     for (const ex of exchanges) {
         const state = states.get(ex.name);
-        const emptyBal = { equity: "0", available: "0", marginUsed: "0", unrealizedPnl: "0" };
+        if (!state) {
+            exchangeData.push({ name: ex.name, balance: null, positions: null, orders: null, topMarkets: cachedMarkets.get(ex.name) ?? [], marketsError: marketsErrors.get(ex.name) ?? null, error: "no feed" });
+            continue;
+        }
+        const stale = isFeedStale(state);
         exchangeData.push({
             name: ex.name,
-            balance: state?.balance ?? emptyBal,
-            positions: [...(state?.positions ?? [])], // copy — mergeAndTotal mutates
-            orders: [...(state?.orders ?? [])],
-            topMarkets: cachedMarkets.get(ex.name) ?? [],
+            // Not read yet = null (unavailable), never a $0 / empty placeholder.
+            balance: state.balance,
+            positions: state.positions ? [...state.positions] : null, // copy — mergeAndTotal mutates
+            orders: state.orders ? [...state.orders] : null,
+            topMarkets: cachedMarkets.get(ex.name) ?? [], marketsError: marketsErrors.get(ex.name) ?? null,
+            error: state.lastError ?? (state.lastOkAt === null ? "no data received yet" : null),
+            feed: { mode: state.mode, lastOkAt: state.lastOkAt, lastError: state.lastError, stale },
         });
     }
     return mergeAndTotal(exchangeData);
@@ -156,23 +172,53 @@ async function pollSnapshot(exchanges, feedMgr) {
     if (feedMgr) {
         return buildSnapshotFromFeeds(feedMgr, exchanges);
     }
+    return mergeAndTotal(await readExchangesRest(exchanges));
+}
+/**
+ * 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 async function readExchangesRest(exchanges) {
     const { withCache, TTL_ACCOUNT } = await import("../cache.js");
-    const emptyBalance = { equity: "0", available: "0", marginUsed: "0", unrealizedPnl: "0" };
-    const results = await Promise.allSettled(exchanges.map(async (ex) => {
-        const [balance, positions, orders] = await Promise.all([
-            withCache(`dash:${ex.name}:balance`, TTL_ACCOUNT, () => ex.adapter.getBalance()).catch(() => emptyBalance),
-            withCache(`dash:${ex.name}:positions`, TTL_ACCOUNT, () => ex.adapter.getPositions()).catch(() => []),
-            withCache(`dash:${ex.name}:orders`, TTL_ACCOUNT, () => ex.adapter.getOpenOrders()).catch(() => []),
+    const errText = (e) => (e instanceof Error ? e.message : String(e));
+    return Promise.all(exchanges.map(async (ex) => {
+        const [balance, positions, orders] = await Promise.allSettled([
+            withCache(`dash:${ex.name}:balance`, TTL_ACCOUNT, () => ex.adapter.getBalance()),
+            withCache(`dash:${ex.name}:positions`, TTL_ACCOUNT, () => ex.adapter.getPositions()),
+            withCache(`dash:${ex.name}:orders`, TTL_ACCOUNT, () => ex.adapter.getOpenOrders()),
         ]);
-        return { name: ex.name, balance, positions, orders, topMarkets: cachedMarkets.get(ex.name) ?? [] };
+        const errs = [];
+        if (balance.status === "rejected")
+            errs.push(`balance: ${errText(balance.reason)}`);
+        if (positions.status === "rejected")
+            errs.push(`positions: ${errText(positions.reason)}`);
+        if (orders.status === "rejected")
+            errs.push(`orders: ${errText(orders.reason)}`);
+        return {
+            name: ex.name,
+            balance: balance.status === "fulfilled" ? balance.value : null,
+            positions: positions.status === "fulfilled" ? positions.value : null,
+            orders: orders.status === "fulfilled" ? orders.value : null,
+            topMarkets: cachedMarkets.get(ex.name) ?? [], marketsError: marketsErrors.get(ex.name) ?? null,
+            error: errs.length > 0 ? errs.join("; ") : null,
+        };
     }));
-    let exchangeData = results
-        .filter((r) => r.status === "fulfilled")
-        .map((r) => r.value);
-    return mergeAndTotal(exchangeData);
 }
-/** Merge HL dex entries + compute totals */
-function mergeAndTotal(exchangeData) {
+/** Merge HL dex entries + compute totals. Unknown (null) parts are skipped and listed in totals.unavailable. */
+export function mergeAndTotal(exchangeData) {
+    const unavailable = [];
+    for (const ex of exchangeData) {
+        if (ex.balance === null)
+            unavailable.push(`${ex.name}.balance`);
+        else if (ex.balance.unrealizedPnl === null)
+            unavailable.push(`${ex.name}.unrealizedPnl`);
+        if (ex.positions === null)
+            unavailable.push(`${ex.name}.positions`);
+        if (ex.orders === null)
+            unavailable.push(`${ex.name}.orders`);
+        if (ex.feed?.stale)
+            unavailable.push(`${ex.name}.stale`);
+    }
     // Merge hl:* dex entries into main hyperliquid (same wallet, dex pools are subsets of main balance)
     const hlEntry = exchangeData.find(e => e.name === "hyperliquid");
     if (hlEntry) {
@@ -181,21 +227,31 @@ function mergeAndTotal(exchangeData) {
         // Only merge positions/orders, and attach dex breakdown for UI display.
         const dexBalances = [];
         let dexPnlSum = 0;
+        let dexPnlUnknown = false;
         for (const dex of dexEntries) {
             const dexName = dex.name.replace("hl:", "");
-            dexBalances.push({ name: dexName, balance: { ...dex.balance } });
-            hlEntry.positions.push(...dex.positions);
-            hlEntry.orders.push(...dex.orders);
-            dexPnlSum += Number(dex.balance.unrealizedPnl) || 0;
+            dexBalances.push({ name: dexName, balance: dex.balance ? { ...dex.balance } : null });
+            // An unread dex list is not merged; it is listed in totals.unavailable and in hlEntry.error below.
+            if (hlEntry.positions && dex.positions)
+                hlEntry.positions.push(...dex.positions);
+            if (hlEntry.orders && dex.orders)
+                hlEntry.orders.push(...dex.orders);
+            if (dex.balance?.unrealizedPnl == null)
+                dexPnlUnknown = true;
+            else
+                dexPnlSum += Number(dex.balance.unrealizedPnl);
+            if (dex.error)
+                hlEntry.error = hlEntry.error ? `${hlEntry.error}; ${dex.name}: ${dex.error}` : `${dex.name}: ${dex.error}`;
         }
         // Add dex unrealizedPnl to main HL balance (equity already includes dex funds, but PnL doesn't)
-        if (dexPnlSum !== 0) {
-            const hlPnl = Number(hlEntry.balance.unrealizedPnl) || 0;
-            hlEntry.balance = { ...hlEntry.balance, unrealizedPnl: String(hlPnl + dexPnlSum) };
+        if (hlEntry.balance && hlEntry.balance.unrealizedPnl !== null) {
+            hlEntry.balance = {
+                ...hlEntry.balance,
+                unrealizedPnl: dexPnlUnknown ? null : String(Number(hlEntry.balance.unrealizedPnl) + dexPnlSum),
+            };
         }
-        if (dexEntries.length > 0) {
+        if (dexEntries.length > 0)
             hlEntry.dexBalances = dexBalances;
-        }
         exchangeData = exchangeData.filter(e => !e.name.startsWith("hl:") || e.name === "hyperliquid");
     }
     const totals = {
@@ -205,14 +261,21 @@ function mergeAndTotal(exchangeData) {
         unrealizedPnl: 0,
         positionCount: 0,
         orderCount: 0,
+        partial: unavailable.length > 0,
+        unavailable,
     };
     for (const ex of exchangeData) {
-        totals.equity += Number(ex.balance.equity) || 0;
-        totals.available += Number(ex.balance.available) || 0;
-        totals.marginUsed += Number(ex.balance.marginUsed) || 0;
-        totals.unrealizedPnl += Number(ex.balance.unrealizedPnl) || 0;
-        totals.positionCount += ex.positions.length;
-        totals.orderCount += ex.orders.length;
+        if (ex.balance) {
+            totals.equity += Number(ex.balance.equity);
+            totals.available += Number(ex.balance.available);
+            totals.marginUsed += Number(ex.balance.marginUsed);
+            if (ex.balance.unrealizedPnl !== null)
+                totals.unrealizedPnl += Number(ex.balance.unrealizedPnl);
+        }
+        if (ex.positions)
+            totals.positionCount += ex.positions.length;
+        if (ex.orders)
+            totals.orderCount += ex.orders.length;
     }
     return { timestamp: new Date().toISOString(), exchanges: exchangeData, totals, arb: cachedArb };
 }
@@ -281,8 +344,10 @@ export async function startDashboard(exchanges, opts = {}) {
             const snap = await pollSnapshot(exchanges, feedMgr);
             ws.send(JSON.stringify({ type: "snapshot", data: snap }));
         }
-        catch {
-            // ignore
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`[warn] dashboard initial snapshot failed: ${msg}\n`);
+            ws.send(JSON.stringify({ type: "error", data: { message: `initial snapshot failed: ${msg}` } }));
         }
     });
     // Arb + market data: stays on REST polling (cross-exchange aggregation, no single WS covers it)
@@ -297,12 +362,18 @@ export async function startDashboard(exchanges, opts = {}) {
                 if (arbResult.status === "fulfilled") {
                     cachedArb = arbResult.value;
                 }
+                else {
+                    // Keep the last good opportunities on screen but mark them as not refreshed.
+                    const msg = arbResult.reason instanceof Error ? arbResult.reason.message : String(arbResult.reason);
+                    process.stderr.write(`[warn] dashboard arb refresh failed: ${msg}\n`);
+                    cachedArb = { ...cachedArb, exchangeStatus: { ...cachedArb.exchangeStatus, arb: "error" }, exchangeErrors: { ...cachedArb.exchangeErrors, arb: msg } };
+                }
                 if (hasClients()) {
                     broadcast(wss, { type: "arb", data: cachedArb });
                 }
             }
-            catch {
-                // ignore
+            catch (e) {
+                process.stderr.write(`[warn] dashboard arb broadcast failed: ${e instanceof Error ? e.message : String(e)}\n`);
             }
         };
         pollArbAndMarkets(); // initial fetch

package/dist/dashboard/ui.js

@@ -239,6 +239,11 @@ function pnlClass(v) { return Number(v)>=0?'pnl-pos':'pnl-neg'; }
 function pnlSign(v) { const n=Number(v)||0; return n>=0?'+$'+fmt(Math.abs(n)):'-$'+fmt(Math.abs(n)); }
 function rateClass(v) { const n=Number(v)||0; return n>0?'rate-positive':n<0?'rate-negative':'rate-neutral'; }
 function spreadClass(v) { return v>=50?'spread-high':v>=20?'spread-mid':'spread-low'; }
+// null = the venue value could not be read / is unknown → shown as such, never as $0.
+const NA = '<span style="color:var(--yellow,#e5c07b)">unavailable</span>';
+function usdOrNA(v, d=2) { return v==null ? NA : '$'+fmt(v,d); }
+function pnlOrNA(v) { return v==null ? NA : pnlSign(v); }
+function escHtml(v) { return String(v).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'})[c]); }
 
 // ── Portfolio Rendering ──
 function renderTotals(t) {
@@ -250,12 +255,13 @@ function renderTotals(t) {
     {label:'Unrealized PnL',value:pnlSign(t.unrealizedPnl),cls:pnlCls},
     {label:'Positions',value:t.positionCount,cls:''},
     {label:'Open Orders',value:t.orderCount,cls:''},
-  ].map(c=>\`<div class="total-card"><div class="label">\${c.label}</div><div class="value \${c.cls}">\${c.value}</div></div>\`).join('');
+  ].map(c=>\`<div class="total-card"><div class="label">\${c.label}\${t.partial?' (partial)':''}</div><div class="value \${c.cls}">\${c.value}</div></div>\`).join('')
+  + (t.partial ? \`<div class="total-card" style="grid-column:1/-1"><div class="label">\${NA} — left out of the totals</div><div style="font-size:12px">\${escHtml((t.unavailable||[]).join(', '))}</div></div>\` : '');
 }
 
 function renderTabs(exchanges) {
   if (!activeExchange && exchanges.length) activeExchange = exchanges[0].name;
-  $('#tabs').innerHTML = exchanges.map(ex=>\`<div class="tab \${ex.name===activeExchange?'active':''}" data-ex="\${ex.name}">\${ex.name}</div>\`).join('');
+  $('#tabs').innerHTML = exchanges.map(ex=>\`<div class="tab \${ex.name===activeExchange?'active':''}" data-ex="\${ex.name}">\${ex.name}\${(ex.feed&&ex.feed.stale)||ex.error?' ⚠':''}</div>\`).join('');
   $$('.tab').forEach(tab => { tab.onclick=()=>{ activeExchange=tab.dataset.ex; render(); }; });
 }
 
@@ -271,16 +277,18 @@ function renderPanels(exchanges) {
 
     // For HL: detect unique dexes from positions/orders
     let dexes = [];
-    let filteredPositions = ex.positions;
-    let filteredOrders = ex.orders;
+    // null = list could not be read (shown as unavailable, never as "no positions")
+    const posKnown = ex.positions != null, ordKnown = ex.orders != null;
+    let filteredPositions = ex.positions || [];
+    let filteredOrders = ex.orders || [];
     if (isHL) {
       const dexSet = new Set();
-      ex.positions.forEach(p => dexSet.add(getDex(p.symbol)));
-      ex.orders.forEach(o => dexSet.add(getDex(o.symbol)));
+      filteredPositions.forEach(p => dexSet.add(getDex(p.symbol)));
+      filteredOrders.forEach(o => dexSet.add(getDex(o.symbol)));
       dexes = ['all', ...Array.from(dexSet).sort()];
       if (activeDexFilters.size > 0) {
-        filteredPositions = ex.positions.filter(p => activeDexFilters.has(getDex(p.symbol)));
-        filteredOrders = ex.orders.filter(o => activeDexFilters.has(getDex(o.symbol)));
+        filteredPositions = filteredPositions.filter(p => activeDexFilters.has(getDex(p.symbol)));
+        filteredOrders = filteredOrders.filter(o => activeDexFilters.has(getDex(o.symbol)));
       }
     }
 
@@ -293,32 +301,38 @@ function renderPanels(exchanges) {
     const dexBreakdown = (field) => {
       if (!dexBal || dexBal.length < 1) return '';
       return '<div style="font-size:10px;color:var(--muted);margin-top:2px">' +
-        dexBal.map(d => d.name + ': $' + fmt(Number(d.balance[field]))).join(' · ') + '</div>';
+        dexBal.map(d => d.name + ': ' + (d.balance ? usdOrNA(d.balance[field]) : NA)).join(' · ') + '</div>';
     };
 
+    const bal = ex.balance || {};
+    const stale = ex.feed && ex.feed.stale;
+    const banner = (stale || ex.error)
+      ? \`<div class="empty-msg" style="color:var(--yellow,#e5c07b)">⚠ \${stale ? 'STALE data' : 'Partial data'}\${ex.feed && ex.feed.lastOkAt ? ' (last update ' + new Date(ex.feed.lastOkAt).toLocaleTimeString() + ')' : ''}\${ex.error ? ': ' + escHtml(ex.error) : ''}</div>\`
+      : '';
     return \`<div class="exchange-panel \${isActive?'active':''}" id="panel-\${ex.name}">
+      \${banner}
       <div class="balance-bar">
-        <div class="balance-item"><div class="label">Equity</div><div class="val">$\${fmt(ex.balance.equity)}</div>\${dexBreakdown('equity')}</div>
-        <div class="balance-item"><div class="label">Available</div><div class="val">$\${fmt(ex.balance.available)}</div>\${dexBreakdown('available')}</div>
-        <div class="balance-item"><div class="label">Margin Used</div><div class="val">$\${fmt(ex.balance.marginUsed)}</div>\${dexBreakdown('marginUsed')}</div>
-        <div class="balance-item"><div class="label">Unrealized PnL</div><div class="val \${pnlClass(ex.balance.unrealizedPnl)}">\${pnlSign(ex.balance.unrealizedPnl)}</div>\${dexBreakdown('unrealizedPnl')}</div>
+        <div class="balance-item"><div class="label">Equity</div><div class="val">\${usdOrNA(bal.equity)}</div>\${dexBreakdown('equity')}</div>
+        <div class="balance-item"><div class="label">Available</div><div class="val">\${usdOrNA(bal.available)}</div>\${dexBreakdown('available')}</div>
+        <div class="balance-item"><div class="label">Margin Used</div><div class="val">\${usdOrNA(bal.marginUsed)}</div>\${dexBreakdown('marginUsed')}</div>
+        <div class="balance-item"><div class="label">Unrealized PnL</div><div class="val \${pnlClass(bal.unrealizedPnl)}">\${pnlOrNA(bal.unrealizedPnl)}</div>\${dexBreakdown('unrealizedPnl')}</div>
       </div>
-      <div class="section-title">Positions (\${filteredPositions.length}\${isHL && activeDexFilters.size>0 ? '/'+ex.positions.length : ''})</div>
+      <div class="section-title">Positions (\${posKnown ? filteredPositions.length : '?'}\${isHL && posKnown && activeDexFilters.size>0 ? '/'+ex.positions.length : ''})</div>
       \${dexFilterHtml}
       \${filteredPositions.length?\`<table><thead><tr>\${isHL?'<th>DEX</th>':''}<th>Symbol</th><th>Side</th><th>Size</th><th>Entry</th><th>Mark</th><th>Liq</th><th>Value</th><th>PnL</th><th>ROE%</th><th>Lev</th></tr></thead><tbody>\${filteredPositions.map(p=>{
         const dex = getDex(p.symbol);
         const sym = p.symbol.includes(':') ? p.symbol.split(':').slice(1).join(':') : p.symbol;
-        const notional = Math.abs(Number(p.size)) * Number(p.markPrice);
-        const margin = p.leverage > 0 ? notional / p.leverage : notional;
-        const roe = margin > 0 ? (Number(p.unrealizedPnl) / margin * 100) : 0;
-        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${p.side}">\${p.side.toUpperCase()}</td><td>\${p.size}</td><td>$\${fmt(p.entryPrice)}</td><td>$\${fmt(p.markPrice)}</td><td>\${(p.liquidationPrice==null||p.liquidationPrice==='N/A')?'-':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">$\${fmt(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlSign(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe>=0?'+':''}\${fmt(roe,1)}%</td><td>\${p.leverage}x</td></tr>\`;
-      }).join('')}</tbody></table>\`:'<div class="empty-msg">No open positions</div>'}
-      <div class="section-title">Open Orders (\${filteredOrders.length})</div>
+        const notional = p.markPrice == null ? null : Math.abs(Number(p.size)) * Number(p.markPrice);
+        const margin = notional == null ? null : p.leverage > 0 ? notional / p.leverage : notional;
+        const roe = margin != null && margin > 0 && p.unrealizedPnl != null ? (Number(p.unrealizedPnl) / margin * 100) : null;
+        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${p.side}">\${p.side.toUpperCase()}</td><td>\${p.size}</td><td>\${usdOrNA(p.entryPrice)}</td><td>\${usdOrNA(p.markPrice)}</td><td>\${(p.liquidationPrice==null||p.liquidationPrice==='N/A')?'-':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">\${usdOrNA(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlOrNA(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe==null?NA:(roe>=0?'+':'')+fmt(roe,1)+'%'}</td><td>\${p.leverage}x</td></tr>\`;
+      }).join('')}</tbody></table>\`:(posKnown?'<div class="empty-msg">No open positions</div>':'<div class="empty-msg">Positions '+NA+'</div>')}
+      <div class="section-title">Open Orders (\${ordKnown ? filteredOrders.length : '?'})</div>
       \${filteredOrders.length?\`<table><thead><tr>\${isHL?'<th>DEX</th>':''}<th>Symbol</th><th>Side</th><th>Type</th><th>Price</th><th>Size</th><th>Filled</th><th>Status</th></tr></thead><tbody>\${filteredOrders.map(o=>{
         const dex = getDex(o.symbol);
         const sym = o.symbol.includes(':') ? o.symbol.split(':').slice(1).join(':') : o.symbol;
         return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${o.side}">\${o.side.toUpperCase()}</td><td>\${o.type}</td><td>$\${fmt(o.price)}</td><td>\${o.size}</td><td>\${o.filled}</td><td>\${o.status}</td></tr>\`;
-      }).join('')}</tbody></table>\`:'<div class="empty-msg">No open orders</div>'}
+      }).join('')}</tbody></table>\`:(ordKnown?'<div class="empty-msg">No open orders</div>':'<div class="empty-msg">Open orders '+NA+'</div>')}
       <div class="section-title">Markets (Top 10)</div>
       \${ex.topMarkets.length?\`<table><thead><tr><th>Symbol</th><th>Mark</th><th>Index</th><th>Funding</th><th>24h Vol</th><th>OI</th><th>Max Lev</th></tr></thead><tbody>\${ex.topMarkets.map(m=>{const fr=Number(m.fundingRate);return\`<tr><td>\${m.symbol}</td><td>$\${fmt(m.markPrice)}</td><td>\${usdOrDash(m.indexPrice)}</td><td class="\${rateClass(fr)}">\${(fr*100).toFixed(4)}%</td><td>\${usdOrDash(m.volume24h,0)}</td><td>\${usdOrDash(m.openInterest,0)}</td><td>\${m.maxLeverage}x</td></tr>\`;}).join('')}</tbody></table>\`:'<div class="empty-msg">No market data</div>'}
     </div>\`;
@@ -510,12 +524,17 @@ function detectEvents(snap) {
   for (const ex of snap.exchanges) {
     const prev = prevSnapshot.exchanges.find(e => e.name === ex.name);
     if (!prev) continue;
-    const prevSyms = new Set(prev.positions.map(p => p.symbol));
-    const currSyms = new Set(ex.positions.map(p => p.symbol));
-    for (const p of ex.positions) { if (!prevSyms.has(p.symbol)) addEvent('position_opened', ex.name, {symbol:p.symbol,side:p.side,size:p.size}); }
-    for (const p of prev.positions) { if (!currSyms.has(p.symbol)) addEvent('position_closed', ex.name, {symbol:p.symbol,side:p.side}); }
-    const eqDelta = Math.abs(Number(ex.balance.equity) - Number(prev.balance.equity));
-    if (eqDelta > 0.01) addEvent('balance_update', ex.name, {equity:ex.balance.equity,delta:eqDelta.toFixed(2)});
+    // An unread (null) side is not a change — no opened/closed events from a failed read.
+    if (prev.positions && ex.positions) {
+      const prevSyms = new Set(prev.positions.map(p => p.symbol));
+      const currSyms = new Set(ex.positions.map(p => p.symbol));
+      for (const p of ex.positions) { if (!prevSyms.has(p.symbol)) addEvent('position_opened', ex.name, {symbol:p.symbol,side:p.side,size:p.size}); }
+      for (const p of prev.positions) { if (!currSyms.has(p.symbol)) addEvent('position_closed', ex.name, {symbol:p.symbol,side:p.side}); }
+    }
+    if (prev.balance && ex.balance) {
+      const eqDelta = Math.abs(Number(ex.balance.equity) - Number(prev.balance.equity));
+      if (eqDelta > 0.01) addEvent('balance_update', ex.name, {equity:ex.balance.equity,delta:eqDelta.toFixed(2)});
+    }
   }
   prevSnapshot = snap;
 }

package/dist/dashboard/ws-feeds.d.ts

@@ -7,13 +7,35 @@
  */
 import type { ExchangeBalance, ExchangePosition, ExchangeOrder } from "../exchanges/index.js";
 import type { DashboardExchange } from "./server.js";
+/** Balance as the dashboard knows it: unrealizedPnl null = the venue feed does not report it / unknown. */
+export type DashboardBalance = Omit<ExchangeBalance, "unrealizedPnl"> & {
+    unrealizedPnl: string | null;
+};
+/** Position as the dashboard knows it: a price / PnL the WS message did not carry is null (unknown), never "0". */
+export type DashboardPosition = Omit<ExchangePosition, "entryPrice" | "markPrice" | "unrealizedPnl"> & {
+    entryPrice: string | null;
+    markPrice: string | null;
+    unrealizedPnl: string | null;
+};
 export interface WsFeedState {
-    balance: ExchangeBalance;
-    positions: ExchangePosition[];
-    orders: ExchangeOrder[];
+    /** null = not read yet (never a zero placeholder). */
+    balance: DashboardBalance | null;
+    /** null = not read yet. */
+    positions: DashboardPosition[] | null;
+    /** null = not read yet. */
+    orders: ExchangeOrder[] | null;
     lastUpdate: number;
     mode: "ws" | "rest" | "connecting";
+    /** Last time a venue read / WS message was applied successfully (ms), null = never. */
+    lastOkAt: number | null;
+    /** Last read / parse failure ("<source>: <message>"), null = none since the feed started. */
+    lastError: string | null;
+    lastErrorAt: number | 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 declare const FEED_STALE_MS = 30000;
+export declare function isFeedStale(state: WsFeedState, now?: number): boolean;
 export interface WsFeedManagerOpts {
     onUpdate: (exchange: string, state: WsFeedState) => void;
     signal?: AbortSignal;