perp-cli 0.15.0 → 0.16.0

package/dist/commands/arb-auto.js

@@ -5,12 +5,12 @@ import { tradingV2Of } from "../exchanges/legacy-trading-v2.js";
 import { invalidateCache } from "../cache.js";
 import { isDryRun, networkOf, supportsDryRun } from "../cli-flags.js";
 import chalk from "chalk";
-import { formatUsd, printJson, jsonOk, jsonError, makeTable, logSettledRejections, symbolMatch } from "../utils.js";
+import { formatUsd, printJson, jsonOk, jsonError, makeTable, symbolMatch } from "../utils.js";
 import { computeExecutableSize } from "../liquidity.js";
 import { computeMatchedSize, computeSpotPerpMatchedSize } from "../arb/index.js";
-import { toHourlyRate } from "../funding.js";
+import { getFundingHours, toHourlyRate } from "../funding.js";
+import { fetchVenuesRates } from "../funding/rates.js";
 import { toHourlyRateByBasis } from "../funding/normalize.js";
-import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidMetaRaw, parseHyperliquidMetaRaw, fetchLighterOrderBookDetailsRaw, fetchLighterFundingRatesRaw, parseLighterRaw, } from "../shared-api.js";
 import { fetchAllDexAssetsDetailed, findDexArbPairs, scanDexArb } from "../dex-asset-map.js";
 import { logExecution, readExecutionLog } from "../execution-log.js";
 import { smartOrder } from "../smart-order.js";
@@ -18,9 +18,23 @@ import { aggressiveSettleBoost, estimateFundingUntilSettlement, computeBasisRisk
 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";
+/** The venue symbol a snapshot / position leg trades on `exchange` (the canonical key when the venue uses it). */
+export function legSymbol(row, exchange) {
+    return row.venueSymbols?.[exchange] ?? row.symbol;
+}
+/** longSymbol / shortSymbol of a new position — only when a leg's venue symbol differs from the key. */
+function legSymbolsOf(snap, longExchange, shortExchange) {
+    const l = legSymbol(snap, longExchange), sh = legSymbol(snap, shortExchange);
+    return l === snap.symbol && sh === snap.symbol ? {} : { longSymbol: l, shortSymbol: sh };
+}
+/** --symbols matches a row by its canonical key or any venue's own symbol (kPEPE or 1000PEPE). */
+export function matchesSymbolFilter(row, filter) {
+    const want = new Set(filter.map(s => s.toUpperCase()));
+    return want.has(row.symbol.toUpperCase()) || Object.values(row.venueSymbols ?? {}).some(v => want.has(v.toUpperCase()));
+}
 // ── Fee-Adjusted Net Spread Calculation ──
 import { getTakerFee } from "../constants.js";
-import { assertFundingArbVenue, getVenue, listVenuesWithRole, networkConfig, resolveVenueId, roleUnsupported, tryResolveVenueId } from "../exchanges/venue.js";
+import { assertFundingArbVenue, getVenue, listVenuesWithRole, resolveVenueId, roleUnsupported, tryResolveVenueId } from "../exchanges/venue.js";
 import { sharedApiNetwork } from "../api/public/urls.js";
 import { findSpotQuoteBalance, readSpotQuoteAvailableFresh, requireBotSpotVenue, requireSpotAdapter, spotNetworkOf, spotPairSymbol, spotSharesPerpMargin, sweepSpotQuoteToPerp, transferQuoteToPerp, transferQuoteToSpot } from "../exchanges/spot-factory.js";
 import { fillSizeString, readSpotBalancesFresh, sizeDecimalsOf, spotLotStepOf, spotMarketFill } from "../exchanges/spot-result.js";
@@ -380,67 +394,60 @@ export function dexCloseBlockedBy(pos, failedDexes) {
     return null;
 }
 const _warnedArbPriceMismatch = new Set();
-async function fetchFundingSpreads() {
-    // Selected network (review L7): the Pacifica / HL / Lighter raw fetchers follow -n via
-    // setSharedApiNetwork; Aster's REST base comes from the venue definition for that network.
-    const asterRest = networkConfig(getVenue("aster"), sharedApiNetwork()).restUrl;
-    // SSOT rule #2: each DEX fetch is independent. allSettled lets us keep the
-    // multi-DEX comparison alive when one DEX errors out, while the rejection
-    // reasons get logged to stderr (explicit failure, never silent).
-    const settled = await Promise.allSettled([
-        fetchPacificaPricesRaw(),
-        fetchHyperliquidMetaRaw(),
-        fetchLighterOrderBookDetailsRaw(),
-        fetchLighterFundingRatesRaw(),
-        fetch(`${asterRest}/fapi/v1/premiumIndex`).then(r => r.json()),
-        fetch(`${asterRest}/fapi/v3/fundingInfo`).then(r => r.json()),
-    ]);
-    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter:orderbook", "lighter:funding", "aster:premiumIndex", "aster:fundingInfo"], "arb-auto");
-    const pacRes = settled[0].status === "fulfilled" ? settled[0].value : null;
-    const hlRes = settled[1].status === "fulfilled" ? settled[1].value : null;
-    const ltDetailsRes = settled[2].status === "fulfilled" ? settled[2].value : null;
-    const ltFundingRes = settled[3].status === "fulfilled" ? settled[3].value : null;
-    // Both Aster calls are needed: a rate without its per-symbol interval cannot be normalized.
-    const astPremiums = settled[4].status === "fulfilled" && settled[5].status === "fulfilled"
-        ? settled[4].value
-        : [];
-    const astFundingInfo = settled[5].status === "fulfilled" ? settled[5].value : [];
+/** " (lastSettled)"-style tag of a snapshot leg's rate kind; "" when the venue is not a leg. */
+const kindTag = (s, ex) => { const k = s.rateKinds?.[ex]; return k === undefined ? "" : `(${k ?? "?"})`; };
+export async function fetchFundingSpreads() {
+    // The SAME rate rows as `arb scan --rates` (fetchVenuesRates over each venue's public directory):
+    // one rate per venue and canonical symbol (unclassified / ambiguous tickers and non-matchable
+    // listings have no canonical and never pair), each with its basis and rateKind. A venue that
+    // fails is reported, never silently treated as "no spread".
+    const venues = ["pacifica", "hyperliquid", "lighter", "aster"].map(id => getVenue(id));
+    const { rates: fetched, exchangeErrors } = await fetchVenuesRates(venues, sharedApiNetwork(), false);
+    // Never a leg on an unverified rate (row label; the venue filter above already drops them).
+    const rates = fetched.filter(r => r.fundingVerified);
+    for (const [ex, msg] of Object.entries(exchangeErrors))
+        process.stderr.write(`[arb-auto] ${ex}: funding rates unavailable — ${msg}\n`);
+    const pacRates = new Map(), pacPrices = new Map();
+    const hlRates = new Map(), hlPrices = new Map();
+    const ltRates = new Map(), ltPrices = new Map();
+    const astRates = new Map(), astPrices = new Map();
     const astHoursBySym = new Map();
-    for (const row of Array.isArray(astFundingInfo) ? astFundingInfo : []) {
-        const rawSym = String(row.symbol ?? "");
-        const hours = Number(row.fundingIntervalHours);
-        if (rawSym.endsWith("USDT") && Number.isFinite(hours) && hours > 0)
-            astHoursBySym.set(rawSym.replace(/USDT$/, ""), hours);
-    }
-    const { rates: pacRates, prices: pacPrices } = parsePacificaRaw(pacRes);
-    const { rates: hlRates, prices: hlPrices } = parseHyperliquidMetaRaw(hlRes);
-    const { rates: ltRates, prices: ltPrices } = parseLighterRaw(ltDetailsRes, ltFundingRes);
-    // Aster: parse premiumIndex.
-    // SSOT rule #2: never silently coerce missing markPrice/lastFundingRate to 0
-    // — a 0 markPrice corrupts every downstream sizing calculation, and a 0
-    // funding rate flips the symbol off the arb radar without explanation.
-    // Skip the symbol entirely if either field is missing or non-finite.
-    const astRates = new Map();
-    const astPrices = new Map();
+    const kindsBySym = new Map();
+    const venueSymbolsBySym = new Map();
     const astNoInterval = [];
-    for (const p of astPremiums ?? []) {
-        const rawSym = String(p.symbol ?? "");
-        if (!rawSym.endsWith("USDT"))
-            continue;
-        const sym = rawSym.replace(/USDT$/, "");
-        const fundingRate = Number(p.lastFundingRate);
-        const markPrice = Number(p.markPrice);
-        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
-            // Aster premiumIndex omitted or returned non-numeric values for this
-            // symbol; skip rather than poison downstream math with a 0.
+    for (const r of rates) {
+        const sym = r.canonical;
+        const kinds = kindsBySym.get(sym) ?? {};
+        kinds[r.exchange] = r.rateKind;
+        kindsBySym.set(sym, kinds);
+        const vs = venueSymbolsBySym.get(sym) ?? {};
+        vs[r.exchange] = r.symbol; // the venue's own symbol (orders use it)
+        venueSymbolsBySym.set(sym, vs);
+        if (r.exchange === "aster") {
+            if (r.basis.kind !== "perHours") {
+                astNoInterval.push(r.symbol);
+                continue;
+            }
+            astRates.set(sym, r.fundingRate);
+            astPrices.set(sym, r.markPrice);
+            astHoursBySym.set(sym, r.basis.hours);
             continue;
         }
-        if (!astHoursBySym.has(sym)) {
-            astNoInterval.push(sym);
-            continue;
+        // The snapshot keeps each venue's rate in the venue's own basis (snapshotHourly /
+        // computeAnnualSpread normalize with it): convert from the row's hourly rate.
+        const inVenueBasis = r.hourlyRate * getFundingHours(r.exchange);
+        if (r.exchange === "pacifica") {
+            pacRates.set(sym, inVenueBasis);
+            pacPrices.set(sym, r.markPrice);
+        }
+        else if (r.exchange === "hyperliquid") {
+            hlRates.set(sym, inVenueBasis);
+            hlPrices.set(sym, r.markPrice);
+        }
+        else if (r.exchange === "lighter") {
+            ltRates.set(sym, inVenueBasis);
+            ltPrices.set(sym, r.markPrice);
         }
-        astRates.set(sym, fundingRate);
-        astPrices.set(sym, markPrice);
     }
     if (astNoInterval.length > 0) {
         process.stderr.write(`[arb-auto] aster: ${astNoInterval.length} symbol(s) excluded — no fundingIntervalHours in /fapi/v3/fundingInfo: ${astNoInterval.slice(0, 10).join(", ")}${astNoInterval.length > 10 ? ", …" : ""}\n`);
@@ -528,12 +535,54 @@ async function fetchFundingSpreads() {
             ltMarkPrice: ltPrices.get(sym) ?? 0,
             astMarkPrice: astPrices.get(sym) ?? 0,
             astHours: ast !== undefined ? astHours : null,
+            rateKinds: Object.fromEntries(available.map(r => [r.exchange, kindsBySym.get(sym)?.[r.exchange] ?? null])),
+            venueSymbols: venueSymbolsBySym.get(sym) ?? {},
         });
     }
     return snapshots.sort((a, b) => Math.abs(b.spread) - Math.abs(a.spread));
 }
 // Module-level holder for spot-close handler -- assigned inside registerArbAutoCommands.
 export let handleSpotClose;
+/**
+ * `arb auto` flag validation: every numeric flag must be a finite number in its range, `--size` a
+ * number or "auto", `--settle-strategy` one of block | aggressive | off. INVALID_PARAMS otherwise.
+ */
+export function assertArbAutoFlags(opts) {
+    const num = (flag, key, min, opt = {}) => {
+        const raw = opts[key];
+        if (raw === undefined)
+            return;
+        const text = String(raw).trim();
+        const v = Number(text);
+        const ok = text !== "" && Number.isFinite(v) && (opt.exclusiveMin ? v > min : v >= min) && (!opt.integer || Number.isInteger(v));
+        if (!ok) {
+            throw new PerpError("INVALID_PARAMS", `${flag} must be ${opt.integer ? "a whole number" : "a number"} ${opt.exclusiveMin ? ">" : ">="} ${min}, got "${text}"`, {
+                remediation: `Pass e.g. ${flag} ${opt.exclusiveMin ? min + 1 : Math.max(min, 1)}`,
+            });
+        }
+    };
+    num("--min-spread", "minSpread", 0);
+    num("--close-spread", "closeSpread", 0);
+    if (opts.size !== undefined && String(opts.size).toLowerCase() !== "auto")
+        num("--size", "size", 0, { exclusiveMin: true });
+    num("--min-size", "minSize", 0);
+    num("--max-positions", "maxPositions", 1, { integer: true });
+    num("--interval", "interval", 0, { integer: true });
+    num("--hold-days", "holdDays", 0, { exclusiveMin: true });
+    num("--bridge-cost", "bridgeCost", 0);
+    num("--min-margin", "minMargin", 0);
+    num("--max-basis", "maxBasis", 0, { exclusiveMin: true });
+    num("--cooldown", "cooldown", 0);
+    num("--min-oi", "minOi", 0);
+    const strat = opts.settleStrategy;
+    if (strat !== undefined && !["block", "aggressive", "off"].includes(String(strat))) {
+        throw new PerpError("INVALID_PARAMS", `--settle-strategy must be block, aggressive or off, got "${String(strat)}"`, { remediation: "Pass --settle-strategy block (default)" });
+    }
+    const grade = opts.minGrade;
+    if (grade !== undefined && !["A", "B", "C", "D"].includes(String(grade).toUpperCase())) {
+        throw new PerpError("INVALID_PARAMS", `--min-grade must be A, B, C or D, got "${String(grade)}"`, { remediation: "Pass --min-grade C (default)" });
+    }
+}
 export function registerArbAutoCommands(program, getAdapterForExchange, isJson, getHLAdapterForDex) {
     const arb = program.commands.find(c => c.name() === "arb");
     if (!arb)
@@ -567,6 +616,9 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         .option("--min-oi <usd>", "Min OI (USD) to enter (hip3 mode)", "50000")
         .option("--min-grade <grade>", "Min viability grade: A, B, C, D (hip3 mode)", "C")
         .action(async (opts) => {
+        // Numeric flags are checked up front (also before --background starts a job): a value that is
+        // not a number ("--cooldown abc" → NaN) would otherwise silently disable the check it feeds.
+        assertArbAutoFlags(opts);
         // Route to HIP-3 dex-auto logic if --hip3 flag is set
         if (opts.hip3) {
             return handleDexAuto({
@@ -647,6 +699,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         const marginUnknownNotified = new Set();
         // Track close times per symbol to prevent close→re-entry loops
         const closeCooldowns = new Map(); // symbol → close timestamp ms
+        // --symbols entries already reported as resolving to another canonical symbol (logged once).
+        const aliasNoted = new Set();
         // Consecutive definite close failures per symbol (quarantined at MAX_PAIR_CLOSE_FAILURES)
         const closeFailures = new Map();
         // -- State Persistence: Initialize or recover --
@@ -687,7 +741,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     (await getAdapterForExchange(p.longExchange)).getPositions(),
                     (await getAdapterForExchange(p.shortExchange)).getPositions(),
                 ]);
-                const has = (list, side) => list.some(x => symbolMatch(x.symbol, p.symbol) && x.side === side && Math.abs(Number(x.size)) > 0);
+                const has = (list, side) => list.some(x => symbolMatch(x.symbol, (side === "long" ? p.longSymbol : p.shortSymbol) ?? p.symbol) && x.side === side && Math.abs(Number(x.size)) > 0);
                 if (has(longs, "long") && has(shorts, "short")) {
                     staleSymbols.delete(p.symbol);
                     return true;
@@ -722,6 +776,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     entryMarkPrice: persisted.entryLongPrice,
                     accumulatedFundingUsd: persisted.accumulatedFunding,
                     lastCheckTime: new Date(persisted.lastCheckTime).getTime(),
+                    longSymbol: persisted.longSymbol, shortSymbol: persisted.shortSymbol,
                 });
             }
             daemonState.lastStartTime = new Date().toISOString();
@@ -793,6 +848,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             entryMarkPrice: persisted.entryLongPrice,
                             accumulatedFundingUsd: persisted.accumulatedFunding,
                             lastCheckTime: new Date(persisted.lastCheckTime).getTime(),
+                            longSymbol: persisted.longSymbol, shortSymbol: persisted.shortSymbol,
                         });
                     }
                 }
@@ -813,7 +869,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             try {
                 const spreads = await fetchFundingSpreads();
                 const filtered = filterSymbols
-                    ? spreads.filter(s => filterSymbols.includes(s.symbol))
+                    ? spreads.filter(s => matchesSymbolFilter(s, filterSymbols))
                     : spreads;
                 const now = new Date().toLocaleTimeString();
                 // Check for close conditions on open positions
@@ -827,7 +883,9 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     // Per-position isolation: one position's failing exit check (e.g. an
                     // unknown funding basis in snapshotHourly) must not skip the others.
                     try {
-                        const current = filtered.find(s => s.symbol === pos.symbol);
+                        // By canonical key; a position opened before 0.15.1 is keyed by its (shared) venue symbol.
+                        const current = filtered.find(s => s.symbol === pos.symbol
+                            || (legSymbol(s, pos.longExchange) === pos.symbol && legSymbol(s, pos.shortExchange) === pos.symbol));
                         if (!current)
                             continue;
                         const currentSpread = Math.abs(current.spread);
@@ -884,8 +942,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                     const sizeStr = String(pos.size);
                                     const closeRes = await closePerpPairVerified({
                                         source: "arb-auto", sym: pos.symbol,
-                                        longAdapter, longExch: pos.longExchange, longSym: pos.symbol, longSize: sizeStr,
-                                        shortAdapter, shortExch: pos.shortExchange, shortSym: pos.symbol, shortSize: sizeStr, smart: false,
+                                        longAdapter, longExch: pos.longExchange, longSym: pos.longSymbol ?? pos.symbol, longSize: sizeStr,
+                                        shortAdapter, shortExch: pos.shortExchange, shortSym: pos.shortSymbol ?? pos.symbol, shortSize: sizeStr, smart: false,
                                         log: (m) => console.log(chalk.red(m)),
                                     });
                                     if (closeRes.status === "closed") {
@@ -1098,8 +1156,15 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     }
                 };
                 for (const sym of filterSymbols ?? []) {
-                    if (!filtered.some(x => x.symbol === sym))
+                    // A --symbols entry may be a venue form (kPEPE): it monitors the canonical row it resolves to.
+                    const hit = filtered.find(x => matchesSymbolFilter(x, [sym]));
+                    if (hit === undefined)
                         console.log(chalk.gray(`  ${now} SKIP ${sym}: not in this cycle's funding scan (no rate on two compared venues)`));
+                    else if (hit.symbol !== sym && !aliasNoted.has(sym)) {
+                        aliasNoted.add(sym);
+                        const forms = Object.entries(hit.venueSymbols ?? {}).map(([v, vs]) => `${v} ${vs}`).join(" / ");
+                        console.log(chalk.gray(`  ${now} MONITOR ${sym} → ${hit.symbol} (canonical${forms !== "" ? `; ${forms}` : ""})`));
+                    }
                 }
                 if (openPositions.length >= maxPositions) {
                     console.log(chalk.gray(`  ${now} NO ENTRY: max positions reached (${openPositions.length}/${maxPositions}: ${openPositions.map(p => `${p.symbol} ${p.longExchange}/${p.shortExchange}`).join(", ")})`));
@@ -1195,7 +1260,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             try {
                                 const longAdapter = await getAdapterForExchange(longExchange);
                                 const shortAdapter = await getAdapterForExchange(shortExchange);
-                                actualSizeUsd = await computeAutoSize(longAdapter, shortAdapter, snap.symbol, 0.3);
+                                actualSizeUsd = await computeAutoSize(longAdapter, shortAdapter, legSymbol(snap, longExchange), 0.3, legSymbol(snap, shortExchange));
                                 if (actualSizeUsd <= 0) {
                                     console.log(chalk.gray(`  ${now} SKIP ${snap.symbol}: auto-size returned $0 (insufficient depth/margin)`));
                                     continue;
@@ -1239,7 +1304,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                 legsStarted = true;
                                 const res = await openPerpPairVerified({
                                     source: "arb-auto", sym: snap.symbol,
-                                    longAdapter, longExch: longExchange, longSym: snap.symbol, shortAdapter, shortExch: shortExchange, shortSym: snap.symbol,
+                                    longAdapter, longExch: longExchange, longSym: legSymbol(snap, longExchange), shortAdapter, shortExch: shortExchange, shortSym: legSymbol(snap, shortExchange),
                                     size: sizeInAsset, smart: false, log: (m) => console.log(chalk.red(m)),
                                 });
                                 legsStarted = false; // outcome known (opened / not opened / quarantined)
@@ -1268,6 +1333,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                             entryShortPrice: snap.markPrice,
                                             accumulatedFunding: 0,
                                             lastCheckTime: entryTime,
+                                            ...legSymbolsOf(snap, longExchange, shortExchange),
                                         });
                                     }
                                     catch (e) {
@@ -1291,6 +1357,9 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                     });
                                     console.error(chalk.red(`  ${now} ENTRY FAILED ${snap.symbol}: ${res.reason}${res.rolledBack !== null ? ` — rolled back long ${res.rolledBack}; no open exposure` : " — nothing opened"}`));
                                     donePending();
+                                    // Cool down like a close: a leg the venue rejects (unknown symbol, lot, margin)
+                                    // is not re-sent — with its fees and rollback — every cycle.
+                                    closeCooldowns.set(snap.symbol, Date.now());
                                     continue;
                                 }
                                 else {
@@ -1341,6 +1410,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             entryMarkPrice: snap.markPrice,
                             accumulatedFundingUsd: 0,
                             lastCheckTime: Date.now(),
+                            ...legSymbolsOf(snap, longExchange, shortExchange),
                         });
                         // Dry-run: record the simulated entry in the in-memory state only (never the real file).
                         if (dryRun) {
@@ -1594,7 +1664,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             const topCheck = filtered.slice(0, 5);
                             await Promise.allSettled(topCheck.map(async (s) => {
                                 try {
-                                    const [hlOB, ltOB] = await Promise.all([fetchHLOrderbook(s.symbol), fetchLighterOrderbook(s.symbol)]);
+                                    const [hlOB, ltOB] = await Promise.all([fetchHLOrderbook(legSymbol(s, "hyperliquid")), fetchLighterOrderbook(legSymbol(s, "lighter"))]);
                                     const hlDepth = hlOB.reduce((sum, l) => sum + l[0] * l[1], 0);
                                     const ltDepth = ltOB.reduce((sum, l) => sum + l[0] * l[1], 0);
                                     const hlBest = hlOB[0]?.[0] ?? 0;
@@ -1613,12 +1683,13 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             const grossColor = grossSpread >= 50 ? chalk.green.bold : grossSpread >= 30 ? chalk.green : chalk.yellow;
                             const netColor = netSpread >= 20 ? chalk.green : netSpread >= 0 ? chalk.yellow : chalk.red;
                             const rates = [];
+                            // Each leg names which rate it is (lastSettled / accruing / predicted; ? = unverified).
                             if (s.pacRate)
-                                rates.push(`PAC:${(s.pacRate * 100).toFixed(4)}%`);
+                                rates.push(`PAC:${(s.pacRate * 100).toFixed(4)}%${kindTag(s, "pacifica")}`);
                             if (s.hlRate)
-                                rates.push(`HL:${(s.hlRate * 100).toFixed(4)}%`);
+                                rates.push(`HL:${(s.hlRate * 100).toFixed(4)}%${kindTag(s, "hyperliquid")}`);
                             if (s.ltRate)
-                                rates.push(`LT:${(s.ltRate * 100).toFixed(4)}%`);
+                                rates.push(`LT:${(s.ltRate * 100).toFixed(4)}%${kindTag(s, "lighter")}`);
                             let liqInfo = "";
                             const ld = liqData.get(s.symbol);
                             if (ld)
@@ -1682,8 +1753,10 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     const netSpread = computeNetSpread(s.annualSpreadPct, holdDays, rtCost, effectiveBridgeCost, sizeUsd);
                     return {
                         mode: "spot-perp", symbol: s.symbol, perpExchange: s.perpExchange,
-                        spotExchanges: s.spotExchanges, grossSpreadPct: s.annualSpreadPct,
-                        netSpreadPct: netSpread, estFeesPct: rtCost,
+                        // grossSpread / netSpread: the names every other arb scan row uses (same % values);
+                        // the *Pct names stay for existing consumers.
+                        spotExchanges: s.spotExchanges, grossSpreadPct: s.annualSpreadPct, grossSpread: s.annualSpreadPct,
+                        netSpreadPct: netSpread, netSpread, estFeesPct: rtCost,
                         perpFundingRate: s.perpFundingRate, direction: s.direction,
                         markPrice: s.bestMarkPrice, estHourlyIncomeUsd: s.estHourlyIncomeUsd,
                         breakEvenDays: rtCost > 0 ? Math.ceil(rtCost / (s.annualSpreadPct / 365)) : 0,
@@ -1747,7 +1820,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 const shortPrice = pFor(s.shortExch);
                 const mid = (longPrice + shortPrice) / 2;
                 const priceGapPct = mid > 0 ? Math.abs(longPrice - shortPrice) / mid * 100 : 0;
-                return { mode: "perp-perp", symbol: s.symbol, longExch: s.longExch, shortExch: s.shortExch, markPrice: s.markPrice, grossSpread, netSpread: net, estFeesPct: rtCost, priceGapPct: Math.round(priceGapPct * 10000) / 10000 };
+                return { mode: "perp-perp", symbol: s.symbol, longExch: s.longExch, shortExch: s.shortExch, markPrice: s.markPrice, grossSpread, grossSpreadPct: grossSpread, netSpread: net, netSpreadPct: net, estFeesPct: rtCost, priceGapPct: Math.round(priceGapPct * 10000) / 10000 };
             });
             // Merge spot-perp results if "all" mode
             const spotPerp = (opts.mode === "all" && spotSpreads) ? spotSpreads.map(s => {
@@ -1757,8 +1830,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 const net = computeNetSpread(s.annualSpreadPct, holdDays, rtCost, effectiveBridgeCost, sizeUsd);
                 return {
                     mode: "spot-perp", symbol: s.symbol, perpExchange: s.perpExchange,
-                    spotExchanges: s.spotExchanges, grossSpread: s.annualSpreadPct,
-                    netSpread: net, estFeesPct: rtCost,
+                    spotExchanges: s.spotExchanges, grossSpread: s.annualSpreadPct, grossSpreadPct: s.annualSpreadPct,
+                    netSpread: net, netSpreadPct: net, estFeesPct: rtCost,
                     perpFundingRate: s.perpFundingRate, direction: s.direction,
                     markPrice: s.bestMarkPrice, breakEvenDays: rtCost > 0 ? Math.ceil(rtCost / (s.annualSpreadPct / 365)) : 0,
                 };
@@ -1787,14 +1860,15 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             const priceGapPct = mid > 0 ? Math.abs(longPrice - shortPrice) / mid * 100 : 0;
             const gapColor = priceGapPct >= 0.5 ? chalk.red : priceGapPct >= 0.1 ? chalk.yellow : chalk.gray;
             const rates = [];
+            // Each leg names which rate it is (lastSettled / accruing / predicted; ? = unverified).
             if (s.pacRate)
-                rates.push(`PAC:${(s.pacRate * 100).toFixed(4)}%`);
+                rates.push(`PAC:${(s.pacRate * 100).toFixed(4)}%${kindTag(s, "pacifica")}`);
             if (s.hlRate)
-                rates.push(`HL:${(s.hlRate * 100).toFixed(4)}%`);
+                rates.push(`HL:${(s.hlRate * 100).toFixed(4)}%${kindTag(s, "hyperliquid")}`);
             if (s.ltRate)
-                rates.push(`LT:${(s.ltRate * 100).toFixed(4)}%`);
+                rates.push(`LT:${(s.ltRate * 100).toFixed(4)}%${kindTag(s, "lighter")}`);
             if (s.astRate)
-                rates.push(`AST:${(s.astRate * 100).toFixed(4)}%`);
+                rates.push(`AST:${(s.astRate * 100).toFixed(4)}%${kindTag(s, "aster")}`);
             return [
                 chalk.white.bold(s.symbol),
                 grossColor(`${grossSpread.toFixed(1)}%`),

package/dist/commands/arb.d.ts

@@ -13,6 +13,14 @@ export interface PriceSnapshot {
     expensive: string;
 }
 export declare function fetchAllPrices(): Promise<PriceSnapshot[]>;
+/**
+ * Cross-venue price gaps by venue symbol. The same ticker on two venues is not proof of the same
+ * instrument (Pacifica SAMSUNG 165.8 USD vs Lighter SAMSUNG 220,597 — a KRW-quoted listing): each
+ * symbol's prices go through the funding scan's median price-outlier guard (dropPriceOutliers,
+ * MAX_PRICE_DEVIATION_PCT, one warning per symbol / venue) before a gap is computed, so a gap is
+ * only reported between prices that agree within the guard.
+ */
+export declare function buildGapSnapshots(pacPrices: Map<string, number>, hlPrices: Map<string, number>, ltPrices: Map<string, number>): PriceSnapshot[];
 export declare function formatGapPrice(p: number): string;
 export declare function printGapTable(snapshots: PriceSnapshot[], minGap: number): void;
 export declare function printTrackSummary(symbol: string, samples: {

package/dist/commands/arb.js

@@ -1,7 +1,7 @@
 import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, withJsonErrors, logSettledRejections } from "../utils.js";
 import chalk from "chalk";
 import { toHourlyRate, annualizeHourlyRate, estimateHourlyFundingFromHourly } from "../funding.js";
-import { fetchAllFundingRates, fetchCanonicalPriceGroups, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
+import { fetchAllFundingRates, fetchCanonicalPriceGroups, dropPriceOutliers, fetchSymbolFundingRates, isRankedComparison, TOP_SYMBOLS, } from "../funding-rates.js";
 import { saveFundingSnapshot, getHistoricalRates, getCompoundedAnnualReturn, getExchangeCompoundingHours, } from "../funding-history.js";
 import { getVenue, listVenuesWithRole, tryResolveVenueId } from "../exchanges/venue.js";
 import "../exchanges/venues/index.js";
@@ -46,23 +46,34 @@ export async function fetchAllPrices() {
                 ltPrices.set(sym, price);
         }
     }
+    return buildGapSnapshots(pacPrices, hlPrices, ltPrices);
+}
+/**
+ * Cross-venue price gaps by venue symbol. The same ticker on two venues is not proof of the same
+ * instrument (Pacifica SAMSUNG 165.8 USD vs Lighter SAMSUNG 220,597 — a KRW-quoted listing): each
+ * symbol's prices go through the funding scan's median price-outlier guard (dropPriceOutliers,
+ * MAX_PRICE_DEVIATION_PCT, one warning per symbol / venue) before a gap is computed, so a gap is
+ * only reported between prices that agree within the guard.
+ */
+export function buildGapSnapshots(pacPrices, hlPrices, ltPrices) {
     const allSymbols = new Set([...pacPrices.keys(), ...hlPrices.keys(), ...ltPrices.keys()]);
     const snapshots = [];
+    const LABEL = { pacifica: "PAC", hyperliquid: "HL", lighter: "LT" };
     for (const sym of allSymbols) {
-        const pac = pacPrices.get(sym) ?? null;
-        const hl = hlPrices.get(sym) ?? null;
-        const lt = ltPrices.get(sym) ?? null;
-        // Need at least 2 exchanges
-        const available = [];
-        if (pac !== null)
-            available.push({ ex: "PAC", price: pac });
-        if (hl !== null)
-            available.push({ ex: "HL", price: hl });
-        if (lt !== null)
-            available.push({ ex: "LT", price: lt });
-        if (available.length < 2)
+        const listed = [];
+        for (const [exchange, map] of [["pacifica", pacPrices], ["hyperliquid", hlPrices], ["lighter", ltPrices]]) {
+            const p = map.get(sym);
+            if (p !== undefined)
+                listed.push({ exchange, markPrice: p });
+        }
+        if (listed.length < 2)
             continue;
-        available.sort((a, b) => a.price - b.price);
+        const kept = dropPriceOutliers(sym, listed, "gaps");
+        // Need at least 2 exchanges whose prices agree
+        if (kept.length < 2)
+            continue;
+        const priceOf = (ex) => kept.find(k => k.exchange === ex)?.markPrice ?? null;
+        const available = kept.map(k => ({ ex: LABEL[k.exchange], price: k.markPrice })).sort((a, b) => a.price - b.price);
         const cheapest = available[0];
         const expensive = available[available.length - 1];
         const maxGap = expensive.price - cheapest.price;
@@ -70,9 +81,9 @@ export async function fetchAllPrices() {
         const maxGapPct = mid > 0 ? (maxGap / mid) * 100 : 0;
         snapshots.push({
             symbol: sym,
-            pacPrice: pac,
-            hlPrice: hl,
-            ltPrice: lt,
+            pacPrice: priceOf("pacifica"),
+            hlPrice: priceOf("hyperliquid"),
+            ltPrice: priceOf("lighter"),
             maxGap,
             maxGapPct,
             cheapest: cheapest.ex,
@@ -194,7 +205,8 @@ function printSnapshotTable(snapshot) {
     }
     const rows = snapshot.symbols.map(s => {
         const rateOf = (id) => s.rates.find(r => r.exchange === id);
-        const spreadColor = s.maxSpreadAnnual >= 30 ? chalk.green : s.maxSpreadAnnual >= 10 ? chalk.yellow : chalk.white;
+        const spread = s.maxSpreadAnnual;
+        const spreadColor = spread === null ? chalk.gray : spread >= 30 ? chalk.green : spread >= 10 ? chalk.yellow : chalk.white;
         // Historical-average source preference: HL, PAC, LT, AST, then whichever venue quoted.
         const bestRate = rateOf("hyperliquid") ?? rateOf("pacifica") ?? rateOf("lighter") ?? rateOf("aster") ?? s.rates[0];
         const trend = trendMap.get(s.symbol) ?? chalk.gray("-");
@@ -204,8 +216,10 @@ function printSnapshotTable(snapshot) {
                 const r = rateOf(v.id);
                 return r ? formatPercent(r.fundingRate) : chalk.gray("-");
             }),
-            spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`), trend,
-            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}${s.executable ? "" : chalk.gray(" (read-only)")}` : chalk.gray("-"),
+            // No ranked pair (< 2 verified rows): unverified rates are shown, never ranked.
+            spread === null ? chalk.gray("n/a") : spreadColor(`${spread.toFixed(1)}%`), trend,
+            spread === null || s.longExchange === null || s.shortExchange === null ? chalk.gray("unranked (unverified)")
+                : spread >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}${s.executable ? "" : chalk.gray(s.readOnlyLegs.length > 0 ? " (read-only)" : " (unverified)")}` : chalk.gray("-"),
             formatAvgRate(bestRate?.historicalAvg?.avg8h), formatAvgRate(bestRate?.historicalAvg?.avg24h), formatAvgRate(bestRate?.historicalAvg?.avg7d),
         ];
     });
@@ -232,9 +246,16 @@ function printDetailedComparison(comparison) {
         const color = r.fundingRate > 0 ? chalk.red : r.fundingRate < 0 ? chalk.green : chalk.white;
         console.log(`  ${chalk.white.bold(exAbbr(r.exchange).padEnd(4))} Raw: ${color(formatPercent(r.fundingRate).padEnd(14))} Hourly: ${(r.hourlyRate * 100).toFixed(6)}%  Annual: ${r.annualizedPct.toFixed(2)}%  APY: ${(compoundedReturn * 100).toFixed(2)}%`);
     }
+    if (!isRankedComparison(comparison)) {
+        console.log(chalk.yellow(`\n  No ranked pair: fewer than two venues with verified funding (${comparison.unverifiedLegs.join(", ")} unverified — display only, never a long / short leg).\n`));
+        return;
+    }
     const spreadColor = comparison.maxSpreadAnnual >= 30 ? chalk.green.bold : comparison.maxSpreadAnnual >= 10 ? chalk.yellow : chalk.white;
     console.log(`\n  Max Spread:     ${spreadColor(`${comparison.maxSpreadAnnual.toFixed(1)}%`)} annual`);
-    console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}${comparison.executable ? "" : chalk.yellow(`  — not executable: ${comparison.readOnlyLegs.join(", ")} is read-only in perp-cli`)}`);
+    console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}${comparison.executable ? "" : chalk.yellow(`  — not executable: ${[
+        ...comparison.readOnlyLegs.map(v => `${v} is read-only in perp-cli`),
+        ...comparison.unverifiedLegs.map(v => `${v} funding is unverified (display only)`),
+    ].join("; ")}`)}`);
     console.log(`  Est. Income:    $${comparison.estHourlyIncomeUsd.toFixed(4)}/hr per $1K notional\n`);
 }
 // registerFundingSubcommands removed — use 'arb scan --rates/--compare/--history/--positions' instead
@@ -287,12 +308,17 @@ export async function handleRates(isJson, opts) {
             const history = getHistoricalRates(s.symbol, bestEx, h24ago, now);
             return { ...s, rateHistory: history.map(h => ({ ts: h.ts, hourlyRate: h.hourlyRate })) };
         });
+        // --min never hides rows silently: the threshold and the hidden count are in meta (and data).
+        const minMeta = { minSpread: snapshot.minSpread, belowMinSpread: snapshot.belowMinSpread };
         if (process.argv.includes("--ndjson") || process.argv.includes("--fields"))
-            return printJson(jsonOk(enriched));
-        return printJson(jsonOk({ ...snapshot, symbols: enriched }));
+            return printJson(jsonOk(enriched, minMeta));
+        return printJson(jsonOk({ ...snapshot, symbols: enriched }, minMeta));
     }
     printSnapshotTable(snapshot);
     printFundingExchangeStatus(snapshot);
+    if (snapshot.belowMinSpread > 0) {
+        console.log(chalk.gray(`  ${snapshot.belowMinSpread} pair${snapshot.belowMinSpread === 1 ? "" : "s"} below --min ${snapshot.minSpread}% hidden (show them: --min 0)\n`));
+    }
 }
 /**
  * Cross-venue price basis — a PRICE comparison, independent of funding.