perp-cli 0.14.0 → 0.14.2

package/dist/commands/arb-auto.js

@@ -11,11 +11,11 @@ import { computeMatchedSize, computeSpotPerpMatchedSize } from "../arb/index.js"
 import { toHourlyRate } from "../funding.js";
 import { toHourlyRateByBasis } from "../funding/normalize.js";
 import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidMetaRaw, parseHyperliquidMetaRaw, fetchLighterOrderBookDetailsRaw, fetchLighterFundingRatesRaw, parseLighterRaw, } from "../shared-api.js";
-import { fetchAllDexAssets, findDexArbPairs, scanDexArb } from "../dex-asset-map.js";
+import { fetchAllDexAssetsDetailed, findDexArbPairs, scanDexArb } from "../dex-asset-map.js";
 import { logExecution, readExecutionLog } from "../execution-log.js";
 import { smartOrder } from "../smart-order.js";
 import { aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk, notifyIfEnabled, } from "../arb-utils.js";
-import { checkChainMargins, isCriticalMargin, shouldBlockEntries, computeAutoSize, } from "../cross-chain-margin.js";
+import { checkChainMargins, marginEntryBlocks, computeAutoSize, } from "../cross-chain-margin.js";
 import { loadArbState, addPosition as persistAddPosition, removePosition as persistRemovePosition, updatePosition as persistUpdatePosition, createInitialState, createDaemonStateStore, } from "../arb-state.js";
 import { handleRates, handleBasisScan, handleDexScan, handleCompare, handleFundingHistory, handleFundingPositions, fetchAllPrices, printGapTable, printTrackSummary, formatGapPrice, } from "./arb.js";
 // ── Fee-Adjusted Net Spread Calculation ──
@@ -323,6 +323,62 @@ export function isSpreadReversed(longExchange, shortExchange, snapshot) {
     // Reversed if the long side rate exceeds the short side rate
     return longHourly > shortHourly;
 }
+/**
+ * Read open positions on each venue for `arb pnl`. A venue whose adapter/positions read
+ * fails lands in `positionErrors` (never silently dropped); a venue with no credentials
+ * (read-only adapter) lands in `notConfigured`.
+ */
+export async function collectArbPnlPositions(exchangeNames, getAdapterForExchange) {
+    const positions = [];
+    const positionErrors = {};
+    const notConfigured = [];
+    for (const exName of exchangeNames) {
+        try {
+            const adapter = await getAdapterForExchange(exName);
+            if (adapter.isReadOnly === true) {
+                notConfigured.push(exName);
+                continue;
+            }
+            for (const p of await adapter.getPositions()) {
+                positions.push({
+                    exchange: exName,
+                    symbol: p.symbol.replace("-PERP", ""),
+                    side: p.side,
+                    size: Math.abs(Number(p.size)),
+                    entry: Number(p.entryPrice),
+                    mark: Number(p.markPrice),
+                    upnl: Number(p.unrealizedPnl),
+                    lev: p.leverage,
+                });
+            }
+        }
+        catch (e) {
+            positionErrors[exName] = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return { positions, positionErrors, notConfigured };
+}
+/**
+ * "arb" when the symbol has both a long and a short leg; otherwise "unknown" if any venue's
+ * positions were unread (its missing leg may be there — never call it naked), else "single".
+ */
+export function arbPnlPairStatus(positions, failedVenues) {
+    if (positions.length >= 2 && positions.some(p => p.side === "long") && positions.some(p => p.side === "short"))
+        return "arb";
+    return failedVenues.length > 0 ? "unknown" : "single";
+}
+/**
+ * HIP-3 auto-arb: the dex (either leg) whose market read failed this cycle, or null.
+ * A non-null result means the pair's spread is UNKNOWN — the position is kept (never
+ * closed as "pair disappeared"); only a pair missing from a successfully read dex is gone.
+ */
+export function dexCloseBlockedBy(pos, failedDexes) {
+    if (Object.hasOwn(failedDexes, pos.longDex))
+        return pos.longDex;
+    if (Object.hasOwn(failedDexes, pos.shortDex))
+        return pos.shortDex;
+    return null;
+}
 const _warnedArbPriceMismatch = new Set();
 async function fetchFundingSpreads() {
     // Selected network (review L7): the Pacifica / HL / Lighter raw fetchers follow -n via
@@ -587,6 +643,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         const openPositions = [];
         // Track which exchanges have low margin (block entries)
         const blockedExchanges = new Set();
+        // Venues whose margin was unknown last cycle (webhook sent once per transition)
+        const marginUnknownNotified = new Set();
         // Track close times per symbol to prevent close→re-entry loops
         const closeCooldowns = new Map(); // symbol → close timestamp ms
         // Consecutive definite close failures per symbol (quarantined at MAX_PAIR_CLOSE_FAILURES)
@@ -960,40 +1018,74 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                         console.log(chalk.yellow(`  ${now} DEGRADED ${pos.symbol}: ${downExchanges.has(pos.longExchange) ? pos.longExchange : pos.shortExchange} is down`));
                     }
                 }
-                try {
-                    // Only check margins when we have open positions (avoid slow adapter init)
-                    const needMarginCheck = openPositions.length > 0;
-                    const adaptersMap = new Map();
-                    if (needMarginCheck) {
-                        const marginExchanges = ["hyperliquid", "lighter", "pacifica"];
-                        for (const name of marginExchanges) {
+                // Only check margins when we have open positions (avoid slow adapter init).
+                // An unreadable margin is UNKNOWN, never healthy: logged every cycle (stderr) and new
+                // entries on that venue are blocked (closing / reducing stays allowed).
+                if (openPositions.length > 0) {
+                    const marginCheck = { statuses: [], unknown: [] };
+                    try {
+                        const adaptersMap = new Map();
+                        for (const name of ["hyperliquid", "lighter", "pacifica"]) {
                             try {
-                                adaptersMap.set(name, await getAdapterForExchange(name));
+                                const a = await getAdapterForExchange(name);
+                                // No credentials (read-only adapter): no positions / margin there to monitor, and
+                                // the bot cannot enter on it either — not "unknown".
+                                if (a.isReadOnly === true) {
+                                    blockedExchanges.add(name);
+                                    continue;
+                                }
+                                adaptersMap.set(name, a);
                             }
-                            catch { /* skip */ }
+                            catch (e) {
+                                marginCheck.unknown.push({ exchange: name, error: `adapter init failed: ${e instanceof Error ? e.message : String(e)}` });
+                            }
+                        }
+                        if (adaptersMap.size > 0) {
+                            const res = await checkChainMargins(adaptersMap, minMarginPct);
+                            marginCheck.statuses.push(...res.statuses);
+                            marginCheck.unknown.push(...res.unknown);
                         }
                     }
-                    if (adaptersMap.size > 0) {
-                        const marginStatuses = await checkChainMargins(adaptersMap, minMarginPct);
-                        for (const ms of marginStatuses) {
-                            if (isCriticalMargin(ms)) {
-                                console.log(chalk.red.bold(`  ${now} EMERGENCY: ${ms.exchange} margin ratio ${ms.marginRatio.toFixed(1)}% — CRITICAL (below 15%)`));
-                                blockedExchanges.add(ms.exchange);
-                                await notifyIfEnabled(webhookUrl, notifyEvents, "margin", {
-                                    exchange: ms.exchange, marginPct: ms.marginRatio, threshold: 15,
-                                });
-                            }
-                            else if (shouldBlockEntries(ms, minMarginPct)) {
-                                console.log(chalk.yellow(`  ${now} WARNING: ${ms.exchange} margin ${ms.marginRatio.toFixed(1)}% below ${minMarginPct}% — blocking new entries`));
-                                blockedExchanges.add(ms.exchange);
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        for (const name of ["hyperliquid", "lighter", "pacifica"]) {
+                            if (blockedExchanges.has(name))
+                                continue;
+                            if (!marginCheck.statuses.some(s => s.exchange === name) && !marginCheck.unknown.some(u => u.exchange === name))
+                                marginCheck.unknown.push({ exchange: name, error: msg });
+                        }
+                    }
+                    const nowUnknown = new Set();
+                    for (const b of marginEntryBlocks(marginCheck, minMarginPct)) {
+                        blockedExchanges.add(b.exchange);
+                        if (b.level === "critical") {
+                            console.log(chalk.red.bold(`  ${now} EMERGENCY: ${b.exchange} margin ratio ${b.marginPct.toFixed(1)}% — CRITICAL (below 15%)`));
+                            await notifyIfEnabled(webhookUrl, notifyEvents, "margin", {
+                                exchange: b.exchange, marginPct: b.marginPct, threshold: 15,
+                            });
+                        }
+                        else if (b.level === "low") {
+                            console.log(chalk.yellow(`  ${now} WARNING: ${b.exchange} margin ${b.marginPct.toFixed(1)}% below ${minMarginPct}% — blocking new entries`));
+                            await notifyIfEnabled(webhookUrl, notifyEvents, "margin", {
+                                exchange: b.exchange, marginPct: b.marginPct, threshold: minMarginPct,
+                            });
+                        }
+                        else {
+                            nowUnknown.add(b.exchange);
+                            console.error(chalk.yellow(`  ${now} MARGIN UNKNOWN: ${b.exchange} (${b.error}) — blocking new entries until margin is readable`));
+                            // Webhook once per transition into unknown (stderr carries the per-cycle signal).
+                            if (!marginUnknownNotified.has(b.exchange)) {
                                 await notifyIfEnabled(webhookUrl, notifyEvents, "margin", {
-                                    exchange: ms.exchange, marginPct: ms.marginRatio, threshold: minMarginPct,
+                                    exchange: b.exchange, marginPct: null, threshold: minMarginPct,
+                                    message: `MARGIN UNKNOWN: ${b.exchange} (${b.error}) — new entries blocked`,
                                 });
                             }
                         }
                     }
+                    marginUnknownNotified.clear();
+                    for (const ex of nowUnknown)
+                        marginUnknownNotified.add(ex);
                 }
-                catch { /* margin check failed, continue without blocking */ }
                 // Entry decisions: every monitored symbol that is not entered gets its reason — logged per
                 // symbol for --symbols, summarized per cycle for a full scan (a silent run is impossible).
                 const skipCounts = new Map();
@@ -1058,7 +1150,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                         const shortExchange = snap.shortExch;
                         // Block entries if either exchange has low margin
                         if (blockedExchanges.has(longExchange) || blockedExchanges.has(shortExchange)) {
-                            skip(snap.symbol, `entries blocked on ${blockedExchanges.has(longExchange) ? longExchange : shortExchange} (margin low / venue down)`);
+                            skip(snap.symbol, `entries blocked on ${blockedExchanges.has(longExchange) ? longExchange : shortExchange} (margin low / margin unknown / venue down)`);
                             continue;
                         }
                         // Compute net spread after fees and bridge costs
@@ -2624,30 +2716,22 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         if (!isJson())
             console.log(chalk.cyan("\n  Checking arb positions...\n"));
         const exchangeNames = ["hyperliquid", "lighter", "pacifica"];
-        const allPositions = [];
-        for (const exName of exchangeNames) {
-            try {
-                const adapter = await getAdapterForExchange(exName);
-                const positions = await adapter.getPositions();
-                for (const p of positions) {
-                    allPositions.push({
-                        exchange: exName,
-                        symbol: p.symbol.replace("-PERP", ""),
-                        side: p.side,
-                        size: Math.abs(Number(p.size)),
-                        entry: Number(p.entryPrice),
-                        mark: Number(p.markPrice),
-                        upnl: Number(p.unrealizedPnl),
-                        lev: p.leverage,
-                    });
-                }
-            }
-            catch {
-                // exchange not configured, skip
-            }
+        // A venue whose positions could not be read is reported (never dropped): pairs that may
+        // involve it are UNKNOWN, not naked. Only a venue with no credentials is skipped — and said so.
+        const { positions: allPositions, positionErrors, notConfigured } = await collectArbPnlPositions(exchangeNames, getAdapterForExchange);
+        const failedVenues = Object.keys(positionErrors);
+        if (!isJson()) {
+            for (const ex of notConfigured)
+                console.log(chalk.gray(`  ${ex}: not configured (no credentials) — skipped`));
+            for (const [ex, msg] of Object.entries(positionErrors))
+                console.error(chalk.red(`  ${ex}: positions unavailable — ${msg} (pairs involving ${ex} are UNKNOWN)`));
         }
         if (allPositions.length === 0) {
-            console.log(chalk.gray("  No positions found on any exchange.\n"));
+            if (isJson())
+                return printJson(jsonOk({ pairs: [], positionErrors, notConfigured }));
+            console.log(failedVenues.length > 0
+                ? chalk.yellow(`  No positions read — ${failedVenues.join(", ")} unavailable, holdings there are UNKNOWN.\n`)
+                : chalk.gray("  No positions found on any configured exchange.\n"));
             return;
         }
         // Group by symbol to find arb pairs
@@ -2665,6 +2749,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         const TAKER_FEE = getTakerFee("default");
         // Fetch actual settled funding payments from each exchange
         const actualFundingByExSymbol = new Map(); // "exchange:SYMBOL" → total settled USD
+        // Venues whose funding history could not be read: their symbols' actualFunding is null, never 0.
+        const fundingErrors = {};
         for (const exName of exchangeNames) {
             try {
                 const adapter = await getAdapterForExchange(exName);
@@ -2675,30 +2761,39 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     actualFundingByExSymbol.set(key, (actualFundingByExSymbol.get(key) ?? 0) + Number(fp.payment));
                 }
             }
-            catch {
-                // exchange not configured or API error, skip
+            catch (e) {
+                fundingErrors[exName] = e instanceof Error ? e.message : String(e);
             }
         }
+        /** Settled funding of `symbol` across its legs; null when a leg's venue history was not read. */
+        const actualFundingOf = (symbol, positions) => {
+            let sum = 0;
+            for (const p of positions) {
+                if (fundingErrors[p.exchange] !== undefined)
+                    return null;
+                sum += actualFundingByExSymbol.get(`${p.exchange}:${symbol}`) ?? 0; // read, no payment for this symbol = 0
+            }
+            return sum;
+        };
         if (isJson()) {
             const result = [...bySymbol.entries()].map(([symbol, positions]) => {
                 const spread = spreadMap.get(symbol);
-                // Sum actual funding across exchanges for this symbol
-                let actualFunding = 0;
-                for (const p of positions) {
-                    actualFunding += actualFundingByExSymbol.get(`${p.exchange}:${symbol}`) ?? 0;
-                }
-                return { symbol, positions, currentSpread: spread?.spread ?? 0, actualFunding };
+                const failed = positions.map(p => fundingErrors[p.exchange] === undefined ? null : `${p.exchange}: ${fundingErrors[p.exchange]}`).filter((x) => x !== null);
+                return { symbol, positions, pairStatus: arbPnlPairStatus(positions, failedVenues), currentSpread: spread === undefined ? null : spread.spread, actualFunding: actualFundingOf(symbol, positions), fundingError: failed.length > 0 ? failed.join("; ") : null };
             });
-            return printJson(jsonOk(result));
+            return printJson(jsonOk({ pairs: result, positionErrors, notConfigured }));
         }
         let totalUpnl = 0;
         let totalFees = 0;
         let totalEstFunding = 0;
         let totalActualFunding = 0;
+        let actualFundingIncomplete = false;
         for (const [symbol, positions] of bySymbol) {
-            const isArb = positions.length >= 2 && positions.some(p => p.side === "long") && positions.some(p => p.side === "short");
+            const pairStatus = arbPnlPairStatus(positions, failedVenues);
             const spread = spreadMap.get(symbol);
-            console.log(chalk.white.bold(`  ${symbol}`) + (isArb ? chalk.green(" [ARB PAIR]") : chalk.gray(" [single]")));
+            console.log(chalk.white.bold(`  ${symbol}`) + (pairStatus === "arb" ? chalk.green(" [ARB PAIR]")
+                : pairStatus === "unknown" ? chalk.yellow(` [UNKNOWN — ${failedVenues.join(", ")} positions unread]`)
+                    : chalk.gray(" [single]")));
             for (const p of positions) {
                 const sideColor = p.side === "long" ? chalk.green : chalk.red;
                 const pnlColor = p.upnl >= 0 ? chalk.green : chalk.red;
@@ -2734,19 +2829,22 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     const holdHours = entryTime ? (Date.now() - entryTime) / (1000 * 60 * 60) : null;
                     // Estimated funding based on current spread × hold time
                     const estFunding = holdHours !== null ? hourlyIncome * holdHours : 0;
-                    // Actual settled funding from exchange APIs
-                    let actualFunding = 0;
-                    for (const p of positions) {
-                        actualFunding += actualFundingByExSymbol.get(`${p.exchange}:${symbol}`) ?? 0;
-                    }
+                    // Actual settled funding from exchange APIs (null = a leg's venue history was not read)
+                    const actualFunding = actualFundingOf(symbol, positions);
                     totalEstFunding += estFunding;
-                    totalActualFunding += actualFunding;
-                    const diff = actualFunding - estFunding;
-                    const diffColor = Math.abs(diff) < 0.01 ? chalk.gray : diff >= 0 ? chalk.green : chalk.red;
                     const fmtVal = (v) => v >= 0 ? `$${v.toFixed(4)}` : `-$${Math.abs(v).toFixed(4)}`;
-                    console.log(chalk.white(`    Funding: Est. ${chalk.yellow(fmtVal(estFunding))} / ` +
-                        `Actual ${chalk.cyan(fmtVal(actualFunding))} / ` +
-                        `Diff: ${diffColor(fmtVal(diff))}`));
+                    if (actualFunding === null) {
+                        actualFundingIncomplete = true;
+                        console.log(chalk.white(`    Funding: Est. ${chalk.yellow(fmtVal(estFunding))} / Actual ${chalk.yellow("unavailable")}`));
+                    }
+                    else {
+                        totalActualFunding += actualFunding;
+                        const diff = actualFunding - estFunding;
+                        const diffColor = Math.abs(diff) < 0.01 ? chalk.gray : diff >= 0 ? chalk.green : chalk.red;
+                        console.log(chalk.white(`    Funding: Est. ${chalk.yellow(fmtVal(estFunding))} / ` +
+                            `Actual ${chalk.cyan(fmtVal(actualFunding))} / ` +
+                            `Diff: ${diffColor(fmtVal(diff))}`));
+                    }
                 }
             }
             console.log();
@@ -2764,10 +2862,12 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             const fundingDiff = totalActualFunding - totalEstFunding;
             const diffPct = totalEstFunding !== 0 ? ((fundingDiff / Math.abs(totalEstFunding)) * 100).toFixed(1) : "N/A";
             console.log(`    Est. funding:    ${chalk.yellow(`$${totalEstFunding.toFixed(4)}`)}`);
-            console.log(`    Actual funding:  ${chalk.cyan(`$${totalActualFunding.toFixed(4)}`)}`);
+            console.log(`    Actual funding:  ${chalk.cyan(`$${totalActualFunding.toFixed(4)}`)}${actualFundingIncomplete ? chalk.yellow(" (incomplete: some venues' funding history unavailable)") : ""}`);
             console.log(`    Funding diff:    ${fundingDiff >= 0 ? chalk.green(`+$${fundingDiff.toFixed(4)}`) : chalk.red(`-$${Math.abs(fundingDiff).toFixed(4)}`)} (${diffPct}%)`);
         }
-        console.log(`    Net (if closed now): ${netColor(`$${netPnl.toFixed(4)}`)}`);
+        console.log(`    Net (if closed now): ${netColor(`$${netPnl.toFixed(4)}`)}${actualFundingIncomplete ? chalk.yellow(" (excludes unread funding)") : ""}`);
+        for (const [ex, msg] of Object.entries(fundingErrors))
+            console.log(chalk.yellow(`    ${ex} funding history unavailable: ${msg}`));
         console.log(chalk.gray(`    (Fees assume ${(TAKER_FEE * 100).toFixed(3)}% taker. Actual may vary.)`));
         console.log(chalk.gray(`    * Net includes actual settled funding where available.\n`));
     }
@@ -2787,10 +2887,13 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             cycle++;
             const ts = new Date().toLocaleTimeString();
             try {
-                const pairs = await scanDexArb({
+                const { pairs, failedDexes } = await scanDexArb({
                     minAnnualSpread: minSpread,
                     includeNative: opts.includeNative,
                 });
+                // Failed dex reads are reported, never shown as "no opportunities" for that dex.
+                for (const [dex, msg] of Object.entries(failedDexes))
+                    console.error(chalk.yellow(`  ${ts} HIP-3 dex ${dex} unavailable: ${msg} — its pairs are missing this cycle`));
                 const shown = pairs.slice(0, topN);
                 // Clear previous output
                 if (cycle > 1) {
@@ -2859,7 +2962,22 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             // Positions live only in memory: a restart re-reads what is held on the dexes, so a
             // held underlying is managed (closed when the spread converges), never re-entered.
             // Unpaired / size-mismatched legs are quarantined. An unreadable dex → not started.
-            const assets = await fetchAllDexAssets();
+            // A transient 429 / timeout on one of the deployed dexes is retried (2 s, 5 s) before
+            // refusing: a partial read is never cached, so each attempt re-reads every dex.
+            let { assets, failedDexes: startFailed } = await fetchAllDexAssetsDetailed();
+            for (const waitMs of [2_000, 5_000]) {
+                if (Object.keys(startFailed).length === 0)
+                    break;
+                console.error(chalk.yellow(`  HIP-3 dex read failed at start (${Object.keys(startFailed).join(", ")}) — retrying in ${waitMs / 1000}s`));
+                await new Promise(r => setTimeout(r, waitMs));
+                ({ assets, failedDexes: startFailed } = await fetchAllDexAssetsDetailed());
+            }
+            if (Object.keys(startFailed).length > 0) {
+                // A dex not read → its held legs are unknown: not started (never re-enter a held pair).
+                throw new PerpError("EXCHANGE_ERROR", `arb auto --hip3: dex market data unreadable at start (${Object.entries(startFailed).map(([d, m]) => `${d}: ${m}`).join("; ")}) — not started (held pairs unknown)`, {
+                    exchange: "hyperliquid", remediation: `Check connectivity (perp arb scan --hip3), then restart`,
+                });
+            }
             const pairsNow = findDexArbPairs(assets, { minAnnualSpread: 0, includeNative: true });
             const legs = new Map();
             for (const dex of [...new Set(assets.map(a => a.dex))]) {
@@ -2931,16 +3049,24 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         }
         const cycle = async () => {
             try {
-                const pairs = await scanDexArb({
+                const { pairs, failedDexes } = await scanDexArb({
                     minAnnualSpread: 0, // get all, filter ourselves
                     includeNative: true,
                 });
                 const now = new Date().toLocaleTimeString();
+                for (const [dex, msg] of Object.entries(failedDexes))
+                    console.error(chalk.yellow(`  ${now} HIP-3 dex ${dex} unavailable: ${msg}`));
                 // Check close conditions
                 for (let i = openPositions.length - 1; i >= 0; i--) {
                     if (stop.requested())
                         break; // stopping: no new close sequence
                     const pos = openPositions[i];
+                    // A leg's dex not read this cycle → spread unknown: never close on missing data.
+                    const unreadDex = dexCloseBlockedBy(pos, failedDexes);
+                    if (unreadDex !== null) {
+                        console.error(chalk.yellow(`  ${now} dex ${unreadDex} unavailable — ${pos.underlying} position kept, re-checked next cycle`));
+                        continue;
+                    }
                     // Find current pair for this position
                     const current = pairs.find(p => p.underlying === pos.underlying &&
                         ((p.long.dex === pos.longDex && p.short.dex === pos.shortDex) ||

package/dist/commands/arb.js

@@ -28,34 +28,33 @@ async function fetchHyperliquidRates() {
 async function fetchAsterRates() {
     // SSOT rule #2: do NOT silently coerce missing markPrice / lastFundingRate
     // to 0 — that would corrupt comparisons against other DEXs. Skip symbols
-    // whose Aster row is malformed instead. The outer try/catch is intentional:
-    // if the entire endpoint fails, the arb command can still compare the
-    // remaining DEXs (graceful degradation is an explicit caller-facing
-    // behavior, not a silent data substitution).
-    try {
-        const premiums = await fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json());
-        const out = [];
-        for (const p of premiums ?? []) {
-            const rawSym = String(p.symbol ?? "");
-            if (!rawSym.endsWith("USDT"))
-                continue;
-            const fundingRate = Number(p.lastFundingRate);
-            const markPrice = Number(p.markPrice);
-            if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
-                continue;
-            }
-            out.push({
-                exchange: "aster",
-                symbol: rawSym.replace(/USDT$/, ""),
-                fundingRate,
-                markPrice,
-            });
+    // whose Aster row is malformed instead. An endpoint failure PROPAGATES: the
+    // caller (handleBasisScan) runs every DEX under Promise.allSettled and reports
+    // the rejection on stderr — Aster is never silently absent from the scan.
+    const res = await fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex");
+    if (!res.ok)
+        throw new Error(`Aster premiumIndex HTTP ${res.status}`);
+    const premiums = await res.json();
+    if (!Array.isArray(premiums))
+        throw new Error("Aster premiumIndex returned a non-array response");
+    const out = [];
+    for (const p of premiums) {
+        const rawSym = String(p.symbol ?? "");
+        if (!rawSym.endsWith("USDT"))
+            continue;
+        const fundingRate = Number(p.lastFundingRate);
+        const markPrice = Number(p.markPrice);
+        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
+            continue;
         }
-        return out;
-    }
-    catch {
-        return [];
+        out.push({
+            exchange: "aster",
+            symbol: rawSym.replace(/USDT$/, ""),
+            fundingRate,
+            markPrice,
+        });
     }
+    return out;
 }
 async function fetchLighterRates() {
     // SSOT rule #2: error must propagate. Caller (handleBasisScan) uses
@@ -450,7 +449,10 @@ export async function handleBasisScan(isJson, opts) {
 export async function handleDexScan(isJson, opts) {
     if (!isJson())
         console.log(chalk.cyan("  Scanning HIP-3 deployed dex funding spreads...\n"));
-    const pairs = await scanDexArb({ minAnnualSpread: parseFloat(opts.minSpread), maxPriceGapPct: parseFloat(opts.maxGap), includeNative: opts.includeNative });
+    const { pairs, failedDexes } = await scanDexArb({ minAnnualSpread: parseFloat(opts.minSpread), maxPriceGapPct: parseFloat(opts.maxGap), includeNative: opts.includeNative });
+    // A dex whose read failed is reported (stderr, both modes — JSON stdout keeps its shape); its pairs are unknown, not absent.
+    for (const [dex, msg] of Object.entries(failedDexes))
+        process.stderr.write(`[dex-scan] HIP-3 dex ${dex} unavailable: ${msg} — its pairs are missing from this scan\n`);
     const topN = parseInt(opts.top);
     const shown = pairs.slice(0, topN);
     if (isJson())
@@ -543,10 +545,11 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
         const results = [];
         const exchangeErrors = {};
         const fundingUnknown = [];
+        /* venue → why its funding history could not be read; its positions get actual* = null (never 0) */ const fundingHistoryErrors = {};
         await Promise.all(targetExchanges.map(async (exchange) => {
             try {
                 const adapter = await getAdapterForExchange(exchange);
-                const [positions, markets, fp] = await Promise.all([adapter.getPositions(), adapter.getMarkets(), adapter.getFundingPayments(100).catch(() => [])]);
+                const [positions, markets, fp] = await Promise.all([adapter.getPositions(), adapter.getMarkets(), adapter.getFundingPayments(100).then((rows) => rows, (e) => { fundingHistoryErrors[exchange] = e instanceof Error ? e.message : String(e); return null; })]);
                 if (positions.length === 0)
                     return;
                 /* rate null = the venue reports no funding rate for the market (never read as 0) */ const fm = new Map();
@@ -557,11 +560,15 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                 }
                 const dayAgo = Date.now() - 86400000;
                 const af = new Map();
-                for (const f of fp) {
+                for (const f of fp ?? []) {
                     if (f.time < dayAgo)
                         continue;
                     const sym = f.symbol.toUpperCase().replace(/-PERP$/, "");
-                    const amt = Number(f.payment) || 0;
+                    const amt = Number(f.payment);
+                    if (!Number.isFinite(amt)) {
+                        fundingHistoryErrors[exchange] = `non-numeric funding payment ${JSON.stringify(f.payment)}`;
+                        continue;
+                    }
                     if (!af.has(sym))
                         af.set(sym, { received: 0, paid: 0 });
                     const e = af.get(sym);
@@ -570,6 +577,7 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                     else
                         e.paid += Math.abs(amt);
                 }
+                /* a venue whose history was unreadable or had an unparsable row: actual* = null (never a partial sum shown as complete) */ const histBad = fp === null || fundingHistoryErrors[exchange] !== undefined;
                 for (const pos of positions) {
                     const sym = pos.symbol.toUpperCase().replace(/-PERP$/, "");
                     const fd = fm.get(sym);
@@ -578,7 +586,12 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                         continue;
                     }
                     const fr = fd.rate;
-                    const mk = Number(pos.markPrice) || fd?.markPrice || 0;
+                    const posMark = Number(pos.markPrice);
+                    const mk = Number.isFinite(posMark) && posMark > 0 ? posMark : fd.markPrice;
+                    if (!(mk > 0)) {
+                        fundingUnknown.push(`${exchange}:${sym} (no mark price)`);
+                        continue;
+                    }
                     const sz = Math.abs(Number(pos.size));
                     const nu = sz * mk;
                     const fh = fd ? fd.fundingHours : null; /* market basis first (§10.1) */
@@ -586,7 +599,7 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                     const ap = annualizeHourlyRate(hr);
                     const hp = estimateHourlyFundingFromHourly(hr, nu, pos.side);
                     const a = af.get(sym);
-                    results.push({ exchange, symbol: sym, side: pos.side, size: pos.size, entryPrice: pos.entryPrice, markPrice: pos.markPrice, unrealizedPnl: pos.unrealizedPnl, leverage: pos.leverage, notionalUsd: nu, fundingRate: fr, hourlyRate: hr, annualPct: ap, hourlyPayment: hp, dailyPayment: hp * 24, actualReceived24h: a?.received ?? 0, actualPaid24h: a?.paid ?? 0, actualNet24h: (a?.received ?? 0) - (a?.paid ?? 0) });
+                    results.push({ exchange, symbol: sym, side: pos.side, size: pos.size, entryPrice: pos.entryPrice, markPrice: pos.markPrice, unrealizedPnl: pos.unrealizedPnl, leverage: pos.leverage, notionalUsd: nu, fundingRate: fr, hourlyRate: hr, annualPct: ap, hourlyPayment: hp, dailyPayment: hp * 24, actualReceived24h: histBad ? null : a?.received ?? 0, actualPaid24h: histBad ? null : a?.paid ?? 0, actualNet24h: histBad ? null : (a?.received ?? 0) - (a?.paid ?? 0) });
                 }
             }
             catch (err) {
@@ -603,15 +616,18 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
         const tH = results.reduce((s, r) => s + r.hourlyPayment, 0);
         const tD = results.reduce((s, r) => s + r.dailyPayment, 0);
         const tN = results.reduce((s, r) => s + r.notionalUsd, 0);
-        const tA = results.reduce((s, r) => s + r.actualNet24h, 0);
+        const tA = results.reduce((s, r) => s + (r.actualNet24h ?? 0), 0);
+        const actualIncomplete = results.some(r => r.actualNet24h === null);
         if (isJson())
-            return printJson(jsonOk({ positions: results.map(r => ({ exchange: r.exchange, symbol: r.symbol, side: r.side, size: r.size, notionalUsd: +r.notionalUsd.toFixed(2), fundingRate: r.fundingRate, annualPct: +r.annualPct.toFixed(2), predicted: { hourly: +r.hourlyPayment.toFixed(6), daily: +r.dailyPayment.toFixed(4) }, actual24h: { received: +r.actualReceived24h.toFixed(6), paid: +r.actualPaid24h.toFixed(6), net: +r.actualNet24h.toFixed(6) }, unrealizedPnl: r.unrealizedPnl })), totals: { predicted: { hourly: +tH.toFixed(6), daily: +tD.toFixed(4) }, actual24h: { net: +tA.toFixed(6) }, notionalUsd: +tN.toFixed(2) }, fundingUnknown, errors: Object.keys(exchangeErrors).length > 0 ? exchangeErrors : undefined }));
+            return printJson(jsonOk({ positions: results.map(r => ({ exchange: r.exchange, symbol: r.symbol, side: r.side, size: r.size, notionalUsd: +r.notionalUsd.toFixed(2), fundingRate: r.fundingRate, annualPct: +r.annualPct.toFixed(2), predicted: { hourly: +r.hourlyPayment.toFixed(6), daily: +r.dailyPayment.toFixed(4) }, actual24h: r.actualNet24h === null ? null : { received: +(r.actualReceived24h ?? 0).toFixed(6), paid: +(r.actualPaid24h ?? 0).toFixed(6), net: +r.actualNet24h.toFixed(6) }, unrealizedPnl: r.unrealizedPnl })), totals: { predicted: { hourly: +tH.toFixed(6), daily: +tD.toFixed(4) }, actual24h: { net: +tA.toFixed(6), incomplete: actualIncomplete }, notionalUsd: +tN.toFixed(2) }, fundingUnknown, fundingHistoryErrors, errors: Object.keys(exchangeErrors).length > 0 ? exchangeErrors : undefined }));
         const exAbbr = venueAbbr;
         console.log(chalk.cyan.bold("  Position Funding Impact\n"));
-        const rows = results.map(r => { const sc = r.side === "long" ? chalk.green : chalk.red; const rc = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white; const as = r.actualNet24h !== 0 ? (r.actualNet24h > 0 ? chalk.green : chalk.red)(`${r.actualNet24h > 0 ? "+" : ""}$${r.actualNet24h.toFixed(4)}`) : chalk.gray("-"); return [chalk.white.bold(exAbbr(r.exchange)), chalk.white.bold(r.symbol), sc(r.side.toUpperCase()), `$${formatUsd(r.notionalUsd)}`, rc(formatPercent(r.fundingRate)), rc(`${r.annualPct.toFixed(1)}%`), as, formatPnl(r.unrealizedPnl)]; });
+        const rows = results.map(r => { const sc = r.side === "long" ? chalk.green : chalk.red; const rc = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white; const as = r.actualNet24h === null ? chalk.yellow("unavailable") : r.actualNet24h !== 0 ? (r.actualNet24h > 0 ? chalk.green : chalk.red)(`${r.actualNet24h > 0 ? "+" : ""}$${r.actualNet24h.toFixed(4)}`) : chalk.gray("-"); return [chalk.white.bold(exAbbr(r.exchange)), chalk.white.bold(r.symbol), sc(r.side.toUpperCase()), `$${formatUsd(r.notionalUsd)}`, rc(formatPercent(r.fundingRate)), rc(`${r.annualPct.toFixed(1)}%`), as, formatPnl(r.unrealizedPnl)]; });
         console.log(makeTable(["Ex", "Symbol", "Side", "Notional", "Rate(now)", "Annual(now)", "Actual 24h", "uPnL"], rows));
         console.log(`\n  Total: $${formatUsd(tN)} | Actual 24h: ${tA >= 0 ? "+" : ""}$${tA.toFixed(4)} | Predicted: ${tD >= 0 ? "-" : "+"}$${Math.abs(tD).toFixed(4)}/d\n`);
         if (fundingUnknown.length > 0)
             console.log(chalk.yellow(`  Funding rate not published (excluded, not counted as 0): ${fundingUnknown.join(", ")}\n`));
+        for (const [ex, msg] of Object.entries(fundingHistoryErrors))
+            console.log(chalk.yellow(`  ${ex} funding history unavailable (Actual 24h excluded, not 0): ${msg}`));
     });
 }

package/dist/commands/bot.d.ts

@@ -1,3 +1,9 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
 export declare function registerStrategyCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, getAdapterFor: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;
+/**
+ * Adapters for a multi-venue bot. An explicitly passed list (--exchanges on the command line)
+ * must load in full: a venue that fails refuses the start with a PerpError naming it. A default
+ * list skips a failing venue with a stderr warning naming it and the cause.
+ */
+export declare function loadBotVenueAdapters(names: string[], explicit: boolean, getAdapterFor: (exchange: string) => Promise<ExchangeAdapter>): Promise<Map<string, ExchangeAdapter>>;