perp-cli 0.14.3 → 0.15.0

package/dist/commands/arb-auto.js

@@ -20,7 +20,7 @@ import { loadArbState, addPosition as persistAddPosition, removePosition as pers
 import { handleRates, handleBasisScan, handleDexScan, handleCompare, handleFundingHistory, handleFundingPositions, fetchAllPrices, printGapTable, printTrackSummary, formatGapPrice, } from "./arb.js";
 // ── 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, networkConfig, 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";
@@ -821,7 +821,7 @@ 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
@@ -877,7 +877,7 @@ 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).
@@ -1114,7 +1114,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;
@@ -1234,7 +1234,7 @@ 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({
@@ -1445,7 +1445,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) {
@@ -1857,6 +1857,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 +1869,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 +1877,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 +1993,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 +2072,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 +2097,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 +2277,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 +2527,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 +2555,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 +3077,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

@@ -29,6 +29,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;

package/dist/commands/arb.js

@@ -1,99 +1,13 @@
 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, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
+import { fetchAllFundingRates, fetchCanonicalPriceGroups, fetchSymbolFundingRates, 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";
-import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidAllMidsRaw, fetchLighterOrderBookDetailsRaw, } from "../shared-api.js";
+import { MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
+import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidAllMidsRaw, fetchLighterOrderBookDetailsRaw, } from "../shared-api.js";
 import { scanDexArb } from "../dex-asset-map.js";
-async function fetchPacificaRates() {
-    const assets = await fetchPacificaPrices();
-    return assets.map(p => ({
-        exchange: "pacifica",
-        symbol: p.symbol,
-        fundingRate: p.funding,
-        markPrice: p.mark,
-    }));
-}
-async function fetchHyperliquidRates() {
-    const assets = await fetchHyperliquidMeta();
-    return assets.map(a => ({
-        exchange: "hyperliquid",
-        symbol: a.symbol,
-        fundingRate: a.funding,
-        markPrice: a.markPx,
-    }));
-}
-async function fetchAsterRates() {
-    // SSOT rule #2: do NOT silently coerce missing markPrice / lastFundingRate
-    // to 0 — that would corrupt comparisons against other DEXs. Skip symbols
-    // whose Aster row is malformed instead. An endpoint failure PROPAGATES: the
-    // caller (handleBasisScan) runs every DEX under Promise.allSettled and reports
-    // the rejection on stderr — Aster is never silently absent from the scan.
-    const res = await fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex");
-    if (!res.ok)
-        throw new Error(`Aster premiumIndex HTTP ${res.status}`);
-    const premiums = await res.json();
-    if (!Array.isArray(premiums))
-        throw new Error("Aster premiumIndex returned a non-array response");
-    const out = [];
-    for (const p of premiums) {
-        const rawSym = String(p.symbol ?? "");
-        if (!rawSym.endsWith("USDT"))
-            continue;
-        const fundingRate = Number(p.lastFundingRate);
-        const markPrice = Number(p.markPrice);
-        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
-            continue;
-        }
-        out.push({
-            exchange: "aster",
-            symbol: rawSym.replace(/USDT$/, ""),
-            fundingRate,
-            markPrice,
-        });
-    }
-    return out;
-}
-async function fetchLighterRates() {
-    // SSOT rule #2: error must propagate. Caller (handleBasisScan) uses
-    // Promise.allSettled to keep multi-DEX comparison alive when one DEX is
-    // down, with explicit stderr logging.
-    const [details, funding] = await Promise.all([
-        fetchLighterOrderBookDetails(),
-        fetchLighterFundingRates(),
-    ]);
-    const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
-    const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-    const rates = [];
-    for (const fr of funding) {
-        const symbol = fr.symbol || symMap.get(fr.marketId);
-        if (!symbol)
-            continue;
-        // Prefer fr.markPrice; fall back to orderBook last-trade as documented
-        // price-source preference (NOT error fallback). Skip if neither resolves
-        // — never publish a 0 markPrice downstream.
-        const directMark = fr.markPrice;
-        const fallbackMark = priceMap.get(fr.marketId);
-        let markPrice;
-        if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
-            markPrice = directMark;
-        }
-        else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
-            markPrice = fallbackMark;
-        }
-        if (markPrice === undefined || !Number.isFinite(fr.rate))
-            continue;
-        rates.push({
-            exchange: "lighter",
-            symbol,
-            fundingRate: fr.rate,
-            markPrice,
-        });
-    }
-    return rates;
-}
 // annualize moved to ../funding.ts — use annualizeRate() / computeAnnualSpread()
 export function registerArbCommands(program, isJson, getAdapterForExchange) {
     const arb = program.command("arb").description("Funding rate arbitrage & basis trading");
@@ -291,12 +205,15 @@ function printSnapshotTable(snapshot) {
                 return r ? formatPercent(r.fundingRate) : chalk.gray("-");
             }),
             spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`), trend,
-            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}` : chalk.gray("-"),
+            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}${s.executable ? "" : chalk.gray(" (read-only)")}` : chalk.gray("-"),
             formatAvgRate(bestRate?.historicalAvg?.avg8h), formatAvgRate(bestRate?.historicalAvg?.avg24h), formatAvgRate(bestRate?.historicalAvg?.avg7d),
         ];
     });
-    console.log(makeTable(["Symbol", ...columns.map(v => v.displayName), "Spread", "24h", "Direction", "Avg 8h", "Avg 24h", "Avg 7d"], rows));
+    console.log(makeTable(["Symbol", ...columns.map(v => v.apiStatus.kind === "unofficial" ? `${v.displayName}*` : v.displayName), "Spread", "24h", "Direction", "Avg 8h", "Avg 24h", "Avg 7d"], rows));
     console.log(chalk.gray(`\n  ${snapshot.symbols.length} symbols compared across exchanges.\n`));
+    const unofficial = columns.filter(v => v.apiStatus.kind === "unofficial");
+    if (unofficial.length > 0)
+        console.log(chalk.yellow(`  * ${unofficial.map(v => v.displayName).join(", ")}: UNOFFICIAL API (undocumented, read-only; may change or break). Unverified funding — shown only with --include-unverified.\n`));
 }
 function printFundingExchangeStatus(snapshot) {
     const statuses = Object.entries(snapshot.exchangeStatus).map(([ex, status]) => {
@@ -317,7 +234,7 @@ function printDetailedComparison(comparison) {
     }
     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)}`);
+    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(`  Est. Income:    $${comparison.estHourlyIncomeUsd.toFixed(4)}/hr per $1K notional\n`);
 }
 // registerFundingSubcommands removed — use 'arb scan --rates/--compare/--history/--positions' instead
@@ -325,9 +242,13 @@ function printDetailedComparison(comparison) {
 /** One-line stderr notice when rows of unverified-funding venues are shown (--include-unverified). */
 function warnUnverifiedFunding(rates) {
     const venues = [...new Set(rates.filter(r => !r.fundingVerified).map(r => r.exchange))];
-    if (venues.length === 0)
-        return;
-    process.stderr.write(`[warn] ${venues.join(", ")}: funding rates are UNVERIFIED (unit not confirmed against funding payments; annualized values overstate venues whose funding accrues only during market hours). Shown on request — not for trading decisions.\n`);
+    if (venues.length > 0) {
+        process.stderr.write(`[warn] ${venues.join(", ")}: funding rates are UNVERIFIED (unit not confirmed against funding payments; annualized values overstate venues whose funding accrues only during market hours). Shown on request — not for trading decisions.\n`);
+    }
+    const unofficial = [...new Set(rates.filter(r => r.apiStatus === "unofficial").map(r => r.exchange))];
+    if (unofficial.length > 0) {
+        process.stderr.write(`[warn] ${unofficial.join(", ")}: read through an UNOFFICIAL API (undocumented; may change or be blocked without notice). Rows carry apiStatus "unofficial".\n`);
+    }
 }
 export async function handleRates(isJson, opts) {
     const minSpread = parseFloat(opts.minSpread);
@@ -373,59 +294,52 @@ export async function handleRates(isJson, opts) {
     printSnapshotTable(snapshot);
     printFundingExchangeStatus(snapshot);
 }
+/**
+ * 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 async function handleBasisScan(isJson, opts) {
     if (!isJson())
         console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
-    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
-    // alive when one DEX errors out, while rejection reasons get logged to
-    // stderr (explicit failure, never silent [] downgrade).
-    const settled = await Promise.allSettled([
-        fetchPacificaRates(),
-        fetchHyperliquidRates(),
-        fetchLighterRates(),
-        fetchAsterRates(),
-    ]);
-    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter", "aster"], "basis-scan");
-    const pacRates = settled[0].status === "fulfilled" ? settled[0].value : [];
-    const hlRates = settled[1].status === "fulfilled" ? settled[1].value : [];
-    const ltRates = settled[2].status === "fulfilled" ? settled[2].value : [];
-    const astRates = settled[3].status === "fulfilled" ? settled[3].value : [];
-    const exchangePrices = new Map();
     const filterSymbol = opts.symbol?.toUpperCase();
-    for (const r of [...pacRates, ...hlRates, ...ltRates, ...astRates]) {
-        if (r.markPrice <= 0)
-            continue;
-        if (filterSymbol && r.symbol.toUpperCase() !== filterSymbol)
-            continue;
-        if (!exchangePrices.has(r.symbol))
-            exchangePrices.set(r.symbol, new Map());
-        exchangePrices.get(r.symbol).set(r.exchange, r.markPrice);
-    }
+    const snapshot = await fetchCanonicalPriceGroups(listVenuesWithRole("trading"), {
+        symbols: filterSymbol !== undefined ? [filterSymbol] : undefined, tag: "basis-scan",
+    });
+    for (const [venue, msg] of Object.entries(snapshot.exchangeErrors))
+        console.error(`[basis-scan] ${venue} fetch failed: ${msg}`);
     const opps = [];
-    for (const [symbol, prices] of exchangePrices.entries()) {
-        if (prices.size < 2)
+    for (const [symbol, priced] of snapshot.groups) {
+        if (priced.length < 2)
             continue;
-        let minEx = "", maxEx = "", minPrice = Infinity, maxPrice = 0;
-        for (const [ex, price] of prices) {
-            if (price < minPrice) {
-                minPrice = price;
-                minEx = ex;
-            }
-            if (price > maxPrice) {
-                maxPrice = price;
-                maxEx = ex;
-            }
+        let min = priced[0], max = priced[0];
+        for (const r of priced) {
+            if (r.markPrice < min.markPrice)
+                min = r;
+            if (r.markPrice > max.markPrice)
+                max = r;
         }
-        if (minEx === maxEx)
+        if (min.exchange === max.exchange)
             continue;
-        const diff = maxPrice - minPrice;
-        const avgPrice = (maxPrice + minPrice) / 2;
+        const diff = max.markPrice - min.markPrice;
+        const avgPrice = (max.markPrice + min.markPrice) / 2;
         const pctDiff = (diff / avgPrice) * 100;
+        if (!(pctDiff <= MAX_PRICE_DEVIATION_PCT)) {
+            console.error(`[basis-scan] excluded ${symbol} ${min.exchange}↔${max.exchange}: mark gap ${pctDiff.toFixed(1)}% > ${MAX_PRICE_DEVIATION_PCT}% (likely a different asset with the same ticker)`);
+            continue;
+        }
         if (pctDiff * 365 >= parseFloat(opts.minBasis)) {
             const priceObj = {};
-            for (const [ex, p] of prices)
-                priceObj[ex] = p;
-            opps.push({ symbol, prices: priceObj, priceDiff: diff, pctDiff, buyOn: minEx, sellOn: maxEx });
+            for (const r of priced)
+                priceObj[r.exchange] = r.markPrice;
+            opps.push({ symbol, prices: priceObj, priceDiff: diff, pctDiff, buyOn: min.exchange, sellOn: max.exchange });
         }
     }
     opps.sort((a, b) => b.pctDiff - a.pctDiff);
@@ -439,12 +353,12 @@ export async function handleBasisScan(isJson, opts) {
     console.log(chalk.gray("  Strategy: Buy cheap, sell expensive, profit from convergence.\n"));
     const rows = opps.map((o) => [
         chalk.white.bold(o.symbol),
-        o.prices.pacifica ? `$${formatUsd(o.prices.pacifica)}` : chalk.gray("-"),
-        o.prices.hyperliquid ? `$${formatUsd(o.prices.hyperliquid)}` : chalk.gray("-"),
-        o.prices.lighter ? `$${formatUsd(o.prices.lighter)}` : chalk.gray("-"),
+        `$${formatUsd(o.prices[o.buyOn])}`,
+        `$${formatUsd(o.prices[o.sellOn])}`,
         `$${formatUsd(o.priceDiff)}`, `${o.pctDiff.toFixed(4)}%`, chalk.green(o.buyOn), chalk.red(o.sellOn),
+        chalk.gray(String(Object.keys(o.prices).length)),
     ]);
-    console.log(makeTable(["Symbol", "Pacifica", "Hyperliquid", "Lighter", "Diff", "Basis %", "Buy On", "Sell On"], rows));
+    console.log(makeTable(["Symbol", "Buy Price", "Sell Price", "Diff", "Basis %", "Buy On", "Sell On", "Venues"], rows));
 }
 export async function handleDexScan(isJson, opts) {
     if (!isJson())
@@ -497,9 +411,13 @@ export async function handleCompare(isJson, symbol, includeUnverified = false) {
     if (comparison)
         warnUnverifiedFunding(comparison.rates);
     if (!comparison) {
+        // A venue ticker whose canonical symbol differs (Variational US500-PERP = SPY): say where to look.
+        const hint = (await import("../exchanges/variational/public.js")).canonicalHintFor(symbol);
         if (isJson())
-            return printJson(jsonOk({ symbol: symbol.toUpperCase(), available: false }));
+            return printJson(jsonOk({ symbol: symbol.toUpperCase(), available: false, ...(hint !== null ? { hint } : {}) }));
         console.log(chalk.gray(`  ${symbol.toUpperCase()} not found on at least 2 exchanges.\n`));
+        if (hint !== null)
+            console.log(chalk.yellow(`  Hint: ${hint}\n`));
         return;
     }
     if (isJson())
@@ -594,7 +512,7 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                     }
                     const sz = Math.abs(Number(pos.size));
                     const nu = sz * mk;
-                    const fh = fd ? fd.fundingHours : null; /* market basis first (§10.1) */
+                    const fh = fd ? fd.fundingHours : null; /* market basis first */
                     const hr = fh !== null ? fr / fh : toHourlyRate(fr, exchange);
                     const ap = annualizeHourlyRate(hr);
                     const hp = estimateHourlyFundingFromHourly(hr, nu, pos.side);

package/dist/commands/bot.js

@@ -419,7 +419,7 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
         }
         console.log();
     });
-    // ── quarantine (design §12.3): positions the bot refuses to touch until a human clears them ──
+    // ── quarantine: positions the bot refuses to touch until a human clears them ──
     bot
         .command("quarantine")
         .description("List quarantined symbols (unknown / unverified order outcome or unhedged leg) — blocked for every bot strategy, arb exec and arb auto (~/.perp/bot-quarantine.json)")

package/dist/commands/builder.js

@@ -283,7 +283,7 @@ export function registerWalletBuilderCommands(wallet, isJson, getAdapterForExcha
         .action(async (venueArg, _opts, cmd) => {
         await withJsonErrors(isJson(), async () => {
             const network = networkOf(cmd);
-            const venues = venueArg !== undefined ? [getVenue(venueArg).id] : [...builderFeeVenues(), ...["lighter", "lighter-rh", "arcus"]];
+            const venues = venueArg !== undefined ? [getVenue(venueArg).id] : [...builderFeeVenues(), ...["lighter", "lighter-rh", "arcus", "risex", "txflow", "variational", "grvt", "extended"]];
             const rows = [];
             for (const v of venues) {
                 const configured = builderTargetOf(loadSettings().builder, v) !== null;