perp-cli 0.14.3 → 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, 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
@@ -821,13 +877,15 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     if (stop.requested())
                         break; // stopping: no new close sequence
                     const pos = openPositions[i];
-                    // Quarantined (design §12.3): hands off until a human clears it.
+                    // Quarantined: hands off until a human clears it.
                     if (isQuarantined(pos.symbol, (m) => console.log(chalk.red(m))))
                         continue;
                     // 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);
@@ -877,15 +935,15 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                 try {
                                     const longAdapter = await getAdapterForExchange(pos.longExchange);
                                     const shortAdapter = await getAdapterForExchange(pos.shortExchange);
-                                    // Sequential, reduce-only, verified (design §12.3): long first, then
+                                    // Sequential, reduce-only, verified: long first, then
                                     // short. A definite long-close failure changes nothing → retried next
                                     // cycle, quarantined after MAX_PAIR_CLOSE_FAILURES in a row. An unknown
                                     // outcome, a partial close or an unhedged leg quarantines (no retry).
                                     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(", ")})`));
@@ -1114,7 +1179,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             skip(snap.symbol, "already open");
                             continue;
                         }
-                        // Global quarantine (design §12.3): unknown / unhedged outcome on this symbol somewhere.
+                        // Global quarantine: unknown / unhedged outcome on this symbol somewhere.
                         if (isQuarantined(snap.symbol, (m) => console.log(chalk.red(m)))) {
                             skip(snap.symbol, "quarantined");
                             continue;
@@ -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;
@@ -1234,12 +1299,12 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             try {
                                 const longAdapter = await getAdapterForExchange(longExchange);
                                 const shortAdapter = await getAdapterForExchange(shortExchange);
-                                // Sequential verified legs (design §12.3): long, then short sized to the
+                                // Sequential verified legs: long, then short sized to the
                                 // long's verified fill; reduce-only rollback / trim; unknown → quarantine.
                                 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) {
@@ -1445,7 +1515,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         .option("--duration <minutes>", "Track duration in minutes (with --track)", "10")
         .option("--beep", "Beep on large gaps (with --gaps)")
         .option("--check-liquidity", "Check orderbook depth in live mode (slower)")
-        .option("--include-unverified", "With --rates / --compare: also show venues whose funding rate is unverified (qfex) — display only, never ranked for trading")
+        .option("--include-unverified", "With --rates / --compare: also show venues whose funding rate is unverified (qfex; txflow — unofficial API; variational; grvt — indicative rate; extended) — display only, never ranked for trading")
         .action(async (opts) => {
         // ── Price gap modes ──
         if (opts.gaps || opts.track || opts.alert) {
@@ -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)}%`),
@@ -1857,6 +1931,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         for (const ex of [longExch, shortExch]) {
             const venue = getVenue(ex);
             if (!venue.roles.includes("trading")) {
+                if (venue.gatedRoles !== null)
+                    throw roleUnsupported(venue, "trading");
                 throw unsupported(venue.displayName, "trading", "no trading API — it cannot be an arb leg", `Use a trading venue: ${listVenuesWithRole("trading").map(v => v.id).join(", ")}`);
             }
         }
@@ -1867,7 +1943,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             console.log(chalk.red("  Long and short exchange must be different."));
             return;
         }
-        // Global quarantine (design §12.3): an unknown / unhedged outcome on this symbol
+        // Global quarantine: an unknown / unhedged outcome on this symbol
         // anywhere blocks new trades until a human clears it.
         const quarantined = quarantineEntryFor(sym, (m) => console.error(m));
         if (quarantined !== null) {
@@ -1875,7 +1951,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 remediation: `${quarantined.remediation} — then: perp strategy quarantine-clear ${sym}`,
             });
         }
-        // A venue whose funding rate is unverified is never a funding-arb leg (design §14.12 #6).
+        // A venue whose funding rate is unverified is never a funding-arb leg.
         assertFundingArbVenue(longExch);
         assertFundingArbVenue(shortExch);
         const longAdapter = await getAdapterForExchange(longExch);
@@ -1991,7 +2067,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         }
         if (!isJson())
             console.log(chalk.gray(`    Executing legs sequentially (long, then short sized to the verified long fill)...\n`));
-        // 5. Sequential verified legs (design §12.3). The second leg is sized to the
+        // 5. Sequential verified legs. The second leg is sized to the
         //    first leg's VERIFIED fill, any shortfall is trimmed off the long
         //    (reduce-only, verified — always, --reconcile is implied), a definite short
         //    failure rolls the long back reduce-only, and an unknown outcome (incl. a
@@ -2070,12 +2146,14 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // Resolve exchange aliases
         spotExch = resolveVenueId(spotExch);
         perpExch = resolveVenueId(perpExch);
-        // Validate spot exchange: bot/arb spot scope (§12.4 #3) — throws CAPABILITY_UNSUPPORTED
+        // Validate spot exchange: bot/arb spot scope — throws CAPABILITY_UNSUPPORTED
         // for venues without spot or outside the scope (pacifica shared margin, arcus swaps).
         const spotDef = requireBotSpotVenue(spotExch.replace(/-spot$/, ""));
         spotExch = spotDef.id;
         perpExch = tryResolveVenueId(perpExch) ?? perpExch;
         if (!getVenue(perpExch).roles.includes("trading")) {
+            if (getVenue(perpExch).gatedRoles !== null)
+                throw roleUnsupported(getVenue(perpExch), "trading");
             throw unsupported(perpExch, "trading", "no trading API — it cannot be the perp leg", `Use a trading venue: ${listVenuesWithRole("trading").map(v => v.id).join(", ")}`);
         }
         assertFundingArbVenue(perpExch);
@@ -2093,7 +2171,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 return;
             console.log(chalk.red(`  ${msg}`));
         };
-        // Global quarantine (design §12.3): checked before anything is read or moved.
+        // Global quarantine: checked before anything is read or moved.
         const quarantined = quarantineEntryFor(sym, (m) => console.error(m));
         if (quarantined !== null) {
             throw new PerpError("RISK_VIOLATION", `${sym} is quarantined (${quarantined.strategy}: ${quarantined.reason})`, {
@@ -2273,7 +2351,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // 7. Execute both legs. Same exchange shares a nonce → sequential; else parallel.
         if (!isJson())
             console.log(chalk.gray(`    Executing ${sameVenue ? "sequentially" : "both legs simultaneously"}...\n`));
-        // The perp leg goes through placePerpVerified (design §12.3): a fill is the measured
+        // The perp leg goes through placePerpVerified: a fill is the measured
         // position delta; an unknown outcome is ORDER_PENDING (quarantine, never roll back).
         let spotResult;
         let perpResult;
@@ -2523,7 +2601,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 remediation: `Pass both: perp arb close ${sym} --spot-exch <spot venue> --perp-exch <perp venue>`,
             });
         }
-        // Load adapters (bot/arb spot scope — §12.4 #3)
+        // Load adapters (bot/arb spot scope)
         const spotDef = requireBotSpotVenue(spotExch.replace(/-spot$/, ""));
         const spotAdapter = await requireSpotAdapter(spotDef.id, await getAdapter(spotDef.id));
         const perpAdapter = await getAdapter(perpExch);
@@ -2551,12 +2629,12 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // Read before anything moves — a failure aborts the close.
         const preCloseQuote = await readSpotQuoteAvailableFresh(spotAdapter);
         // Same exchange → sequential (nonce collision), different → parallel.
-        // The spot leg's REAL fill decides the outcome (§12.4 #5): only a confirmed spot sale
+        // The spot leg's REAL fill decides the outcome: only a confirmed spot sale
         // counts as closed; legs are re-matched so no naked short / unhedged spot is left.
         const sameVenue = spotDef.id === (tryResolveVenueId(perpExch) ?? perpExch);
         const closeDec = sizeDecimalsOf(closeSize);
-        // The perp buy-back and every re-match order go through placePerpVerified (design
-        // §12.3): only a measured position change counts; an unknown outcome stops the close.
+        // The perp buy-back and every re-match order go through placePerpVerified:
+        // only a measured position change counts; an unknown outcome stops the close.
         let spotResult;
         let perpResult;
         if (sameVenue) {
@@ -3073,7 +3151,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             (p.long.dex === pos.shortDex && p.short.dex === pos.longDex)));
                     const currentSpread = current?.annualSpread ?? 0;
                     if (currentSpread <= closeSpread || !current) {
-                        // Quarantined (design §12.3): hands off until a human clears it.
+                        // Quarantined: hands off until a human clears it.
                         if (isQuarantined(pos.underlying, (m) => console.error(chalk.red(m))))
                             continue;
                         const reason = !current ? "pair disappeared" : `spread ${currentSpread.toFixed(1)}% <= ${closeSpread}%`;

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: {
@@ -29,6 +37,18 @@ export declare function handleRates(isJson: () => boolean, opts: {
     top?: string;
     includeUnverified?: boolean;
 }): Promise<void>;
+/**
+ * Cross-venue price basis — a PRICE comparison, independent of funding.
+ *
+ * Venue scope: every venue with the "trading" role (both legs must be executable), whether or not
+ * its funding rate is verified; market-data-only venues (TxFlow, unofficial API) are out. Prices
+ * come from each venue's market directory and are grouped by `canonical` symbol with the funding
+ * scan's guards (fetchCanonicalPriceGroups): unclassified / ambiguous tickers have no canonical and
+ * never pair, and a venue whose mark deviates more than MAX_PRICE_DEVIATION_PCT from the group
+ * median is dropped. The chosen cheap / rich pair must itself agree within MAX_PRICE_DEVIATION_PCT:
+ * a wider gap is a different asset under the same ticker (BB on Lighter 8.50 vs Aster 0.0091).
+ * A venue that fails is reported on stderr and is absent from the scan, never silently empty.
+ */
 export declare function handleBasisScan(isJson: () => boolean, opts: {
     minBasis: string;
     symbol?: string;