perp-cli 0.14.1 → 0.14.2

package/dist/commands/bot.js

@@ -162,17 +162,10 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
         .option("--background", "Run in background (tmux)")
         .option("--headless", "Run without TUI dashboard")
         .option("--job-id <id>", "Job ID")
-        .action(async (opts) => {
-        const exchangeNames = opts.exchanges.split(",").map(e => e.trim());
-        const adapters = new Map();
-        for (const name of exchangeNames) {
-            try {
-                adapters.set(name, await getAdapterFor(name));
-            }
-            catch {
-                // skip unavailable
-            }
-        }
+        .action(async (opts, cmd) => {
+        const adapters = await loadBotVenueAdapters(opts.exchanges.split(",").map(e => e.trim()), cmd.getOptionValueSource("exchanges") === "cli", getAdapterFor);
+        // The strategy scans only the venues that loaded.
+        const exchangeNames = [...adapters.keys()];
         if (adapters.size < 2) {
             console.error(chalk.red("\n  Need at least 2 exchanges for arbitrage.\n"));
             return;
@@ -207,7 +200,8 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
                 `strategy`, `quick-arb`,
                 `--min-spread`, opts.minSpread, `--close-spread`, opts.closeSpread,
                 `--size`, opts.size, `--max-positions`, opts.maxPositions,
-                `--exchanges`, opts.exchanges, `--interval`, opts.interval,
+                // The venues the parent loaded (a skipped default venue is not re-tried as "explicit").
+                `--exchanges`, exchangeNames.join(","), `--interval`, opts.interval,
                 `--max-drawdown`, opts.maxDrawdown,
             ];
             const job = startJob({
@@ -241,17 +235,10 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
         .option("--background", "Run in background (tmux)")
         .option("--headless", "Run without TUI dashboard")
         .option("--job-id <id>", "Job ID")
-        .action(async (opts) => {
-        const exchangeNames = opts.exchanges.split(",").map(e => e.trim());
-        const adapters = new Map();
-        for (const name of exchangeNames) {
-            try {
-                adapters.set(name, await getAdapterFor(name));
-            }
-            catch {
-                // skip unavailable
-            }
-        }
+        .action(async (opts, cmd) => {
+        const adapters = await loadBotVenueAdapters(opts.exchanges.split(",").map(e => e.trim()), cmd.getOptionValueSource("exchanges") === "cli", getAdapterFor);
+        // The strategy trades only the venues that loaded.
+        const exchangeNames = [...adapters.keys()];
         if (adapters.size < 1) {
             console.error(chalk.red("\n  Need at least 1 exchange for delta-neutral.\n"));
             return;
@@ -287,7 +274,7 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
                 `strategy`, `delta-neutral`,
                 `--min-rate`, opts.minRate, `--close-rate`, opts.closeRate,
                 `--size`, opts.size, `--max-positions`, opts.maxPositions,
-                `--leverage`, opts.leverage, `--exchanges`, opts.exchanges,
+                `--leverage`, opts.leverage, `--exchanges`, exchangeNames.join(","),
                 `--interval`, opts.interval, `--max-drawdown`, opts.maxDrawdown,
             ];
             const job = startJob({
@@ -355,15 +342,9 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
             const built = preset.buildConfig("multi", sym);
             const config = opts.size !== undefined ? withPresetSize(built, opts.size) : built;
             const arbStrategy = config.strategy;
-            const adapters = new Map();
-            for (const exName of arbStrategy.exchanges) {
-                try {
-                    adapters.set(exName, await getAdapterFor(exName));
-                }
-                catch {
-                    // skip unavailable
-                }
-            }
+            // The preset's venue list is a default (not user-passed): a failing venue is skipped with a warning.
+            const adapters = await loadBotVenueAdapters(arbStrategy.exchanges, false, getAdapterFor);
+            arbStrategy.exchanges = [...adapters.keys()];
             if (adapters.size < 2) {
                 console.error(chalk.red("\n  Need at least 2 exchanges for arbitrage.\n"));
                 return;
@@ -756,6 +737,44 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
     // Nested scripted plans: `perp strategy plan {validate|execute|example}`
     registerStrategyPlanCommands(bot, getAdapter, isJson);
 }
+/**
+ * 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 async function loadBotVenueAdapters(names, explicit, getAdapterFor) {
+    const adapters = new Map();
+    for (const name of names) {
+        try {
+            const a = await getAdapterFor(name);
+            // A venue without credentials gets a read-only adapter: it can neither trade nor report
+            // the bot's balances, so it is "not configured" — refused when listed explicitly.
+            if (a.isReadOnly === true) {
+                if (explicit) {
+                    throw new PerpError("NO_SIGNER_AVAILABLE", `--exchanges venue ${name} has no credentials configured`, {
+                        exchange: name, remediation: `Set it up (perp setup) or remove it from --exchanges`,
+                    });
+                }
+                process.stderr.write(`[info] ${name} not configured (no credentials) — the bot runs without it\n`);
+                continue;
+            }
+            adapters.set(name, a);
+        }
+        catch (e) {
+            if (e instanceof PerpError && e.structured.code === "NO_SIGNER_AVAILABLE" && explicit)
+                throw e;
+            const cause = e instanceof Error ? e.message : String(e);
+            if (explicit) {
+                throw new PerpError(e instanceof PerpError ? e.structured.code : "EXCHANGE_ERROR", `--exchanges venue ${name} could not be initialised: ${cause}`, {
+                    exchange: name,
+                    remediation: `Fix ${name}'s setup (credentials / network: perp -e ${name} portfolio), or remove it from --exchanges`,
+                });
+            }
+            process.stderr.write(`[warn] ${name} unavailable (${cause}) — the bot runs without it\n`);
+        }
+    }
+    return adapters;
+}
 function makeLog() {
     return (msg) => {
         const ts = new Date().toLocaleTimeString();
@@ -898,19 +917,10 @@ function registerRunSubcommands(parent, getAdapter, getAdapterFor, isJson) {
         .option("--rebalance-threshold <usd>", "Rebalance when available < this ($)", "100")
         .option("--max-drawdown <usd>", "Close all positions if total uPnL exceeds this loss ($)")
         .option("--job-id <id>", "Job ID (set automatically for background jobs)")
-        .action(async (opts) => {
+        .action(async (opts, cmd) => {
         const exchangeNames = opts.exchanges.split(",").map((e) => e.trim());
-        const adapters = new Map();
-        for (const name of exchangeNames) {
-            try {
-                const a = await getAdapterFor(name);
-                adapters.set(name, a);
-            }
-            catch {
-                if (!isJson())
-                    console.log(chalk.yellow(`  Skipping ${name} (no credentials)`));
-            }
-        }
+        // An explicitly listed venue that fails to load refuses the start; a default one is skipped with a warning.
+        const adapters = await loadBotVenueAdapters(exchangeNames, cmd.getOptionValueSource("exchanges") === "cli", getAdapterFor);
         if (adapters.size < 2) {
             console.error(chalk.red("Need at least 2 exchanges for arbitrage. Set credentials for 2+ exchanges."));
             process.exit(1);

package/dist/commands/funds-onchain.js

@@ -238,11 +238,12 @@ export function registerOnchainFundsCommands(ctx) {
     // Ondo Perps withdrawals are web-app only (the API does not allow them), so an address-book
     // entry made here would serve nothing. The command stays so the refusal is explicit.
     const addressBook = funds.command("address-book").description("Not available: the Ondo Perps withdrawal address book is managed in the web app");
-    supportsDryRun(addressBook.command("add <venue> <address>"))
-        .description("Not available: Ondo Perps withdrawals and their address book are web-app only (refused, also with --dry-run)")
+    // Optional arguments: a bare `address-book add` gets the same explicit refusal, not a usage error.
+    supportsDryRun(addressBook.command("add [venue] [address]"))
+        .description("Not available: no venue offers a withdrawal address book over the CLI (Ondo Perps: web app only; refused, also with --dry-run)")
         .option("--label <text>", "Ignored")
-        .action(async (venue) => {
-        const def = getVenue(venue);
-        throw unsupported(def.displayName, "address-book", "the Ondo Perps API does not allow withdrawals, so the CLI keeps no withdrawal address book", "Manage withdrawals and the address book in the Ondo Perps web app");
+        // Venue-neutral: no venue has a CLI address book, so the arguments are not even resolved.
+        .action(async () => {
+        throw unsupported("perp-cli", "address-book", "perp-cli has no withdrawal address book for any venue (Ondo Perps withdrawals are web-app only)", "Manage withdrawals and address books in the venue's web app");
     });
 }

package/dist/commands/funds.js

@@ -94,6 +94,13 @@ export function chainLabel(chain) {
         throw new Error(`no display label for chain "${chain}" (add it to CHAIN_LABELS)`);
     return label;
 }
+/** Circle forwarding fee per HL CCTP destination, from HL_CCTP_ROUTES (null = not published). */
+async function hlCctpFeeText() {
+    const { HL_CCTP_ROUTES } = await import("../exchanges/hyperliquid.js");
+    return Object.entries(HL_CCTP_ROUTES)
+        .map(([chain, r]) => `${chain}: ${r.forwardingFeeUsdc === null ? "fee not published" : `${r.forwardingFeeUsdc} USDC`}`)
+        .join(", ");
+}
 /** Withdraw asset declared by the venue definition (capabilities.withdrawAssets[0]). */
 function withdrawAssetOf(def) {
     const assets = requireCapabilities(def).withdrawAssets;
@@ -1345,11 +1352,13 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
                 },
                 withdraw: {
                     pacifica: { chain: "Solana", token: "USDC", speed: "~10s", fee: "none" },
-                    hyperliquid: { chain: "Arbitrum", token: "USDC", speed: "minutes", fee: "$1" },
+                    hyperliquid: { chain: "Arbitrum (default) / Ethereum / Base", token: "USDC", speed: "minutes (CCTP attestation)", method: "CCTP (sendToEvmWithData)", fee: await hlCctpFeeText(), command: "perp funds withdraw hyperliquid <amount> [--chain arbitrum|ethereum|base]" },
                     lighter: { chain: "Ethereum L1", token: "USDC", speed: "~12 hours (standard), minutes (fast)", fee: "varies" },
                     "lighter-rh": { chain: "Robinhood Chain", token: "USDG", command: "perp -e lighter-rh funds withdraw lighter <amount>" },
                     ondo: { supported: false, note: "the Ondo Perps API does not allow withdrawals — withdraw in the Ondo Perps web app" },
-                    qfex: { supported: false, note: "QFEX withdrawals are disabled in perp-cli for now — withdraw in the QFEX web app" },
+                    qfex: QFEX_WITHDRAW_ENABLED
+                        ? { chain: chainLabel(QFEX_WITHDRAW_NETWORK), token: "USDC", command: "perp funds withdraw qfex <amount> --to <allowlisted address>", gate: "settings withdraw.qfex (allowlist, maxPerTx, maxPerDay)", note: "needs a key with the \"Deposit and withdraw\" permission" }
+                        : { supported: false, note: `${QFEX_WITHDRAW_DISABLED.reason} — ${QFEX_WITHDRAW_DISABLED.remediation}` },
                     arcus: { chain: "Robinhood Chain", token: "USDG", command: "perp funds withdraw arcus <amount>" },
                     aster: { chain: "BNB Chain (default) / Arbitrum", token: "USDT (default) / USDC", command: "perp funds withdraw aster <amount> [--chain bsc|arbitrum] [--asset USDT|USDC]", fee: "POST /fapi/v3/aster/user-withdraw-info (taken from the amount)", requires: "mainnet; API wallet approved with --can-withdraw --ip-whitelist; destination = the account's own address" },
                 },
@@ -1390,9 +1399,9 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
         console.log(chalk.white.bold("  Pacifica") + chalk.gray(" → Solana"));
         console.log(`  Speed: ~10s  |  Fee: none`);
         console.log(`  Command: ${chalk.green("perp funds withdraw pacifica <amount>")}`);
-        console.log(chalk.white.bold("\n  Hyperliquid") + chalk.gray(" → Arbitrum"));
-        console.log(`  Speed: minutes  |  Fee: ~$1`);
-        console.log(`  Command: ${chalk.green("perp -e hl funds withdraw hyperliquid <amount>")}`);
+        console.log(chalk.white.bold("\n  Hyperliquid") + chalk.gray(" → Arbitrum (default) / Ethereum / Base over CCTP"));
+        console.log(`  Fee: ${await hlCctpFeeText()}`);
+        console.log(`  Command: ${chalk.green("perp funds withdraw hyperliquid <amount> [--chain arbitrum|ethereum|base]")}`);
         console.log(chalk.white.bold("\n  Lighter") + chalk.gray(" → Ethereum L1"));
         console.log(`  Speed: ~12h (standard)  |  Fee: varies`);
         console.log(`  Command: ${chalk.green("perp -e lt funds withdraw lighter <amount>")}`);
@@ -1402,6 +1411,10 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
         console.log(chalk.gray("  Withdraw in the Ondo Perps web app."));
         console.log(chalk.white.bold("\n  Arcus") + chalk.gray(" → Robinhood Chain (USDG, to the account owner)"));
         console.log(`  Command: ${chalk.green("perp funds withdraw arcus <amount>")}`);
+        console.log(chalk.white.bold("\n  QFEX") + chalk.gray(QFEX_WITHDRAW_ENABLED ? ` → ${chainLabel(QFEX_WITHDRAW_NETWORK)} (USDC, allowlisted address)` : " — disabled in perp-cli for now"));
+        console.log(QFEX_WITHDRAW_ENABLED
+            ? `  Command: ${chalk.green("perp funds withdraw qfex <amount> --to <allowlisted address>")}`
+            : chalk.gray(`  ${QFEX_WITHDRAW_DISABLED.remediation}.`));
         console.log(chalk.white.bold("\n  Aster") + chalk.gray(" → BNB Chain / Arbitrum (USDT, to the account's own address; mainnet only)"));
         console.log(`  Needs an API wallet approved with --can-withdraw --ip-whitelist; fee from user-withdraw-info`);
         console.log(`  Command: ${chalk.green("perp funds withdraw aster <amount> [--chain bsc|arbitrum] [--asset USDT|USDC]")}`);

package/dist/commands/history.js

@@ -359,26 +359,39 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             const limit = parseInt(opts.limit);
             const allTrades = [];
             const allFunding = [];
+            // A venue whose adapter / trades / funding read failed is listed here and left out of the
+            // totals (partial: true) — never counted as 0.
+            const errors = {};
+            const errText = (e) => (e instanceof Error ? e.message : String(e));
             // Fetch trades + funding in parallel from all exchanges
             await Promise.allSettled(exchanges.map(async (ex) => {
+                let adapter;
                 try {
-                    const adapter = await getAdapterForExchange(ex);
-                    const [trades, funding] = await Promise.all([
-                        adapter.getTradeHistory(limit),
-                        adapter.getFundingPayments(limit),
-                    ]);
-                    for (const t of trades) {
+                    adapter = await getAdapterForExchange(ex);
+                }
+                catch (e) {
+                    errors[`${ex}.adapter`] = errText(e);
+                    return;
+                }
+                const [trades, funding] = await Promise.allSettled([adapter.getTradeHistory(limit), adapter.getFundingPayments(limit)]);
+                if (trades.status === "fulfilled") {
+                    for (const t of trades.value) {
                         if (sinceMs && t.time < sinceMs)
                             continue;
                         allTrades.push({ exchange: ex, symbol: t.symbol, side: t.side, price: Number(t.price), size: Number(t.size), fee: Number(t.fee), time: t.time });
                     }
-                    for (const f of funding) {
+                }
+                else
+                    errors[`${ex}.trades`] = errText(trades.reason);
+                if (funding.status === "fulfilled") {
+                    for (const f of funding.value) {
                         if (sinceMs && f.time < sinceMs)
                             continue;
                         allFunding.push({ exchange: ex, symbol: f.symbol, payment: Number(f.payment), time: f.time });
                     }
                 }
-                catch { /* skip unavailable exchanges */ }
+                else
+                    errors[`${ex}.funding`] = errText(funding.reason);
             }));
             // Aggregate by exchange
             const byExchange = new Map();
@@ -428,6 +441,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 netPnl,
                 byExchange: Object.fromEntries([...byExchange.entries()].map(([ex, d]) => [ex, { ...d, netPnl: d.funding - d.fees }])),
                 daily,
+                errors,
+                partial: Object.keys(errors).length > 0,
             };
             if (isJson())
                 return printJson(jsonOk(result));
@@ -438,6 +453,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             console.log(`  Trading Fees:    ${chalk.red(`-$${formatUsd(totalFees)}`)}`);
             console.log(`  Funding Income:  ${formatPnl(totalFunding)}`);
             console.log(`  Net P&L:         ${formatPnl(netPnl)}`);
+            for (const [k, msg] of Object.entries(errors))
+                console.log(chalk.yellow(`  ⚠ ${k} unavailable (left out of the totals): ${msg}`));
             if (byExchange.size > 0) {
                 console.log(chalk.white.bold("\n  By Exchange:"));
                 const rows = [...byExchange.entries()].map(([ex, d]) => [
@@ -480,27 +497,44 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             const allFunding = [];
             // Fetch funding payments and current positions in parallel
             const positionNotionals = new Map();
+            // A venue whose adapter / funding / positions read failed is listed here; its funding is
+            // left out of the totals (partial: true) — never counted as 0.
+            const errors = {};
+            const errText = (e) => (e instanceof Error ? e.message : String(e));
             await Promise.allSettled(exchanges.map(async (ex) => {
+                let adapter;
                 try {
-                    const adapter = await getAdapterForExchange(ex);
-                    const [payments, positions] = await Promise.all([
-                        adapter.getFundingPayments(parseInt(opts.limit)),
-                        adapter.getPositions(),
-                    ]);
-                    for (const p of payments) {
+                    adapter = await getAdapterForExchange(ex);
+                }
+                catch (e) {
+                    errors[`${ex}.adapter`] = errText(e);
+                    return;
+                }
+                const [payments, positions] = await Promise.allSettled([
+                    adapter.getFundingPayments(parseInt(opts.limit)),
+                    adapter.getPositions(),
+                ]);
+                if (payments.status === "fulfilled") {
+                    for (const p of payments.value) {
                         if (sinceMs && p.time < sinceMs)
                             continue;
                         if (opts.symbol && !p.symbol.toUpperCase().includes(opts.symbol.toUpperCase()))
                             continue;
                         allFunding.push({ exchange: ex, symbol: p.symbol, payment: Number(p.payment), time: p.time });
                     }
-                    for (const p of positions) {
+                }
+                else
+                    errors[`${ex}.funding`] = errText(payments.reason);
+                // Positions only feed the annualized rate (null when the notional is unknown).
+                if (positions.status === "fulfilled") {
+                    for (const p of positions.value) {
                         if (Number(p.size) > 0) {
                             positionNotionals.set(`${ex}:${p.symbol}`, Math.abs(Number(p.size) * Number(p.markPrice)));
                         }
                     }
                 }
-                catch { /* skip unavailable exchanges */ }
+                else
+                    errors[`${ex}.positions`] = errText(positions.reason);
             }));
             allFunding.sort((a, b) => a.time - b.time);
             // Aggregate by exchange×symbol
@@ -556,16 +590,19 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             const arbRows = arbPositions
                 .map(pos => {
                 const af = arbFunding.get(pos.symbol);
-                if (!af || (af.longFunding === 0 && af.shortFunding === 0))
+                // A leg on a venue whose funding read failed is unknown (null), not 0.
+                const longFunding = af && !(`${pos.longExchange}.adapter` in errors || `${pos.longExchange}.funding` in errors) ? af.longFunding : null;
+                const shortFunding = af && !(`${pos.shortExchange}.adapter` in errors || `${pos.shortExchange}.funding` in errors) ? af.shortFunding : null;
+                if (!af || (longFunding === 0 && shortFunding === 0))
                     return null;
                 return {
                     symbol: pos.symbol,
                     mode: pos.mode ?? "perp-perp",
                     longExchange: pos.longExchange,
                     shortExchange: pos.shortExchange,
-                    netFunding: af.longFunding + af.shortFunding,
-                    longFunding: af.longFunding,
-                    shortFunding: af.shortFunding,
+                    netFunding: longFunding !== null && shortFunding !== null ? longFunding + shortFunding : null,
+                    longFunding,
+                    shortFunding,
                     daysSinceEntry: Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000)),
                 };
             })
@@ -580,6 +617,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 byExchange: Object.fromEntries(byExchange),
                 arbPositions: arbRows,
                 ...(opts.daily ? { daily } : {}),
+                errors,
+                partial: Object.keys(errors).length > 0,
             };
             if (isJson())
                 return printJson(jsonOk(result));
@@ -588,6 +627,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             console.log(`  Total Payments:  ${allFunding.length}`);
             console.log(`  Net Funding:     ${formatPnl(totalFunding)}`);
             console.log(`  Period:          ~${Math.round(periodDays)} days`);
+            for (const [k, msg] of Object.entries(errors))
+                console.log(chalk.yellow(`  ⚠ ${k} unavailable (left out of the totals): ${msg}`));
             if (exSymRows.length > 0) {
                 console.log(chalk.white.bold("\n  By Exchange × Symbol:"));
                 const rows = exSymRows.map(e => [
@@ -605,7 +646,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                     chalk.white.bold(a.symbol),
                     `${a.longExchange} → ${a.shortExchange}`,
                     a.mode,
-                    formatPnl(a.netFunding),
+                    a.netFunding !== null ? formatPnl(a.netFunding) : chalk.yellow("unavailable"),
                     `${a.daysSinceEntry}d`,
                 ]);
                 console.log(makeTable(["Symbol", "Long → Short", "Mode", "Net Funding", "Held"], rows));
@@ -650,6 +691,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             // A venue whose read failed is reported here and left out of the totals — never counted as 0.
             const errors = {};
             const errText = (e) => (e instanceof Error ? e.message : String(e));
+            let venuesRead = 0;
             await Promise.allSettled(exchanges.map(async (ex) => {
                 let adapter;
                 try {
@@ -663,6 +705,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                     const balance = await adapter.getBalance();
                     totalEquity += Number(balance.equity);
                     totalUPnl += Number(balance.unrealizedPnl);
+                    venuesRead++;
                 }
                 catch (e) {
                     errors[`${ex}.balance`] = errText(e);
@@ -710,6 +753,10 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                         : "0",
                 },
                 errors,
+                // partial: some venue read failed — portfolio / costs cover only the venues that answered.
+                partial: Object.keys(errors).length > 0,
+                venuesRead,
+                venuesRequested: exchanges.length,
             };
             if (isJson())
                 return printJson(jsonOk(report));
@@ -759,25 +806,49 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             // Fetch funding + current positions from all relevant exchanges
             const fundingByExSym = new Map();
             const currentPrices = new Map();
+            // A venue whose adapter / funding / positions read failed is keyed here: rows touching it
+            // report null for the unknown part (funding / pricePnl), never 0 or the entry price.
+            const errors = {};
+            const errText = (e) => (e instanceof Error ? e.message : String(e));
+            const fundingFailed = new Set();
             await Promise.allSettled([...exchangeSet].map(async (ex) => {
+                let adapter;
                 try {
-                    const adapter = await getAdapterForExchange(ex);
-                    const [funding, livePositions] = await Promise.all([
-                        adapter.getFundingPayments(limit),
-                        adapter.getPositions(),
-                    ]);
-                    for (const f of funding) {
+                    adapter = await getAdapterForExchange(ex);
+                }
+                catch (e) {
+                    errors[`${ex}.adapter`] = errText(e);
+                    fundingFailed.add(ex);
+                    return;
+                }
+                const [funding, livePositions] = await Promise.allSettled([
+                    adapter.getFundingPayments(limit),
+                    adapter.getPositions(),
+                ]);
+                if (funding.status === "fulfilled") {
+                    for (const f of funding.value) {
                         if (sinceMs && f.time < sinceMs)
                             continue;
                         const key = `${ex}:${f.symbol}`;
                         fundingByExSym.set(key, (fundingByExSym.get(key) ?? 0) + Number(f.payment));
                     }
-                    for (const p of livePositions) {
+                }
+                else {
+                    errors[`${ex}.funding`] = errText(funding.reason);
+                    fundingFailed.add(ex);
+                }
+                if (livePositions.status === "fulfilled") {
+                    for (const p of livePositions.value) {
                         currentPrices.set(`${ex}:${p.symbol}`, Number(p.markPrice));
                     }
                 }
-                catch { /* skip */ }
+                else
+                    errors[`${ex}.positions`] = errText(livePositions.reason);
             }));
+            // Funding of a venue that answered: the sum of its payments (none = 0). A failed venue: unknown (null).
+            const fundingOf = (ex, sym) => fundingFailed.has(ex) ? null : fundingByExSym.get(`${ex}:${sym}`) ?? 0;
+            // Current mark from the live position; none (failed read / no live leg) = unknown (null), never the entry price.
+            const priceOf = (ex, sym) => currentPrices.get(`${ex}:${sym}`) ?? null;
             // Entries without a verified entry price (a bot leg the venue reported no fill price for)
             // have no price PnL: listed apart, never priced at a guess.
             const priced = positions.filter((p) => p.entryLongPrice !== null && p.entryShortPrice !== null);
@@ -785,21 +856,21 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             // Build comparison data
             const rows = priced.map(pos => {
                 const daysHeld = Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000));
-                const longFunding = fundingByExSym.get(`${pos.longExchange}:${pos.symbol}`) ?? 0;
-                const shortFunding = fundingByExSym.get(`${pos.shortExchange}:${pos.symbol}`) ?? 0;
-                const netFunding = longFunding + shortFunding;
-                // Estimate unrealized PnL from price movement
-                const longPrice = currentPrices.get(`${pos.longExchange}:${pos.symbol}`) ?? pos.entryLongPrice;
-                const shortPrice = currentPrices.get(`${pos.shortExchange}:${pos.symbol}`) ?? pos.entryShortPrice;
-                const longPnl = (longPrice - pos.entryLongPrice) * pos.longSize;
-                const shortPnl = (pos.entryShortPrice - shortPrice) * pos.shortSize;
-                const pricePnl = longPnl + shortPnl;
-                const totalPnl = pricePnl + netFunding;
+                const longFunding = fundingOf(pos.longExchange, pos.symbol);
+                const shortFunding = fundingOf(pos.shortExchange, pos.symbol);
+                const netFunding = longFunding !== null && shortFunding !== null ? longFunding + shortFunding : null;
+                // Estimate unrealized PnL from price movement (null when either leg's mark is unknown)
+                const longPrice = priceOf(pos.longExchange, pos.symbol);
+                const shortPrice = priceOf(pos.shortExchange, pos.symbol);
+                const pricePnl = longPrice !== null && shortPrice !== null
+                    ? (longPrice - pos.entryLongPrice) * pos.longSize + (pos.entryShortPrice - shortPrice) * pos.shortSize
+                    : null;
+                const totalPnl = pricePnl !== null && netFunding !== null ? pricePnl + netFunding : null;
                 // Notional for ROI calculation
                 const notional = pos.entryLongPrice * pos.longSize + pos.entryShortPrice * pos.shortSize;
-                const roi = notional > 0 ? (totalPnl / notional) * 100 : 0;
-                const fundingRoi = notional > 0 ? (netFunding / notional) * 100 : 0;
-                const annualizedRoi = daysHeld > 0 ? (fundingRoi / daysHeld) * 365 : 0;
+                const roi = totalPnl !== null ? (notional > 0 ? (totalPnl / notional) * 100 : 0) : null;
+                const fundingRoi = netFunding !== null ? (notional > 0 ? (netFunding / notional) * 100 : 0) : null;
+                const annualizedRoi = fundingRoi !== null ? (daysHeld > 0 ? (fundingRoi / daysHeld) * 365 : 0) : null;
                 return {
                     symbol: pos.symbol,
                     mode: pos.mode ?? "perp-perp",
@@ -816,14 +887,19 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                     annualizedRoi,
                 };
             });
-            // Sort by total PnL descending
-            rows.sort((a, b) => b.totalPnl - a.totalPnl);
+            // Sort by total PnL descending (unknown totals last)
+            rows.sort((a, b) => (a.totalPnl === null ? 1 : b.totalPnl === null ? -1 : b.totalPnl - a.totalPnl));
+            // Totals skip the unknown (null) values; partial flags that they do not cover every row.
+            const sumKnown = (vals) => vals.reduce((s, v) => s + (v ?? 0), 0);
+            const complete = rows.filter(r => r.totalPnl !== null);
             const totals = {
-                funding: rows.reduce((s, r) => s + r.funding, 0),
-                pricePnl: rows.reduce((s, r) => s + r.pricePnl, 0),
-                totalPnl: rows.reduce((s, r) => s + r.totalPnl, 0),
-                notional: rows.reduce((s, r) => s + r.notional, 0),
+                funding: sumKnown(rows.map(r => r.funding)),
+                pricePnl: sumKnown(rows.map(r => r.pricePnl)),
+                totalPnl: sumKnown(complete.map(r => r.totalPnl)),
+                // ROI base: only the rows whose total PnL is known.
+                notional: complete.reduce((s, r) => s + r.notional, 0),
             };
+            const partial = Object.keys(errors).length > 0 || rows.some(r => r.funding === null || r.pricePnl === null);
             const result = {
                 period: opts.period ?? "all",
                 positionCount: rows.length,
@@ -833,6 +909,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                     ...totals,
                     roi: totals.notional > 0 ? (totals.totalPnl / totals.notional) * 100 : 0,
                 },
+                errors,
+                partial,
             };
             if (isJson())
                 return printJson(jsonOk(result));
@@ -843,11 +921,11 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 `${r.longExchange} → ${r.shortExchange}`,
                 r.mode,
                 `${r.daysHeld}d`,
-                formatPnl(r.funding),
-                formatPnl(r.pricePnl),
-                formatPnl(r.totalPnl),
-                `${r.roi >= 0 ? "+" : ""}${r.roi.toFixed(2)}%`,
-                `${r.annualizedRoi >= 0 ? "+" : ""}${r.annualizedRoi.toFixed(1)}%`,
+                r.funding !== null ? formatPnl(r.funding) : chalk.yellow("unavailable"),
+                r.pricePnl !== null ? formatPnl(r.pricePnl) : chalk.yellow("unavailable"),
+                r.totalPnl !== null ? formatPnl(r.totalPnl) : chalk.yellow("unavailable"),
+                r.roi !== null ? `${r.roi >= 0 ? "+" : ""}${r.roi.toFixed(2)}%` : chalk.yellow("unavailable"),
+                r.annualizedRoi !== null ? `${r.annualizedRoi >= 0 ? "+" : ""}${r.annualizedRoi.toFixed(1)}%` : chalk.yellow("unavailable"),
             ]);
             console.log(makeTable(["Symbol", "Long → Short", "Mode", "Held", "Funding", "Price PnL", "Total PnL", "ROI", "Ann.ROI"], tableRows));
             if (unpricedPositions.length > 0)
@@ -859,6 +937,10 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             if (totals.notional > 0) {
                 console.log(`    Total ROI:        ${result.totals.roi >= 0 ? "+" : ""}${result.totals.roi.toFixed(2)}%`);
             }
+            if (partial)
+                console.log(chalk.yellow("    ⚠ Partial: totals leave out the unavailable values above"));
+            for (const [k, msg] of Object.entries(errors))
+                console.log(chalk.yellow(`    ⚠ ${k} unavailable: ${msg}`));
             console.log();
         });
     });

package/dist/commands/portfolio.d.ts

@@ -17,4 +17,9 @@
 import type { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
 import "../exchanges/venues/index.js";
+/**
+ * Open-position count on a HIP-3 dex; null = the read failed (unknown — NOT "no positions").
+ * The failure is warned on stderr; callers must treat null as "may hold positions".
+ */
+export declare function checkDexPositions(address: string, dex: string): Promise<number | null>;
 export declare function registerPortfolioCommand(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean, version: string, getHLAdapterForDex?: (dex: string) => Promise<ExchangeAdapter>): void;