perp-cli 0.14.3 → 0.16.0

package/dist/funding/legacy-public.js

@@ -1,6 +1,6 @@
 /**
  * Public market data for the legacy venues without a native `getVenueMarkets`
- * (pacifica, hyperliquid core, aster) — design §10.6. Lighter uses
+ * (pacifica, hyperliquid core, aster). Lighter uses
  * exchanges/lighter-public.ts.
  *
  * Network-aware: the REST base comes from `legacyPublicBaseUrl(venue, net)`,
@@ -19,23 +19,26 @@
  *   pacifica: crypto-centric; PACIFICA_NON_CRYPTO lists every non-crypto perp
  *     listed on 2026-09-30.
  *   aster: exchangeInfo `underlyingSubType` (STOCK / ETF / Commodities / pre-launch).
- *   AMBIGUOUS tickers are excluded with a warning so they cannot produce a false
- *   cross-venue match (SPX = the SPX6900 token, whose ticker equals the S&P 500
- *   canonical key).
+ *   Ambiguous tickers (UNCLASSIFIED_TICKERS, src/ws/unclassified.ts — SPX = the SPX6900
+ *   token, whose ticker equals the S&P 500 canonical key) are listed as "unclassified"
+ *   (canonical null) so they cannot produce a false cross-venue match.
  *
  * Fields a venue does not publish on this path are null (HL has no fixed tick
  * size; Aster leverage brackets need a signed call; Aster OI is per-symbol only).
  */
 import { HL_MIN_ORDER_VALUE_USD } from "../constants.js";
+import { isPacificaPerpetual } from "../ws/pacifica-instrument.js";
+import { asterCliSymbol, asterMatchable, isAsterListedPerpetual } from "../ws/aster-market.js";
+import { isUnclassifiedTicker } from "../ws/unclassified.js";
 import { PerpError } from "../errors.js";
 import { venueRateString } from "../utils/numeric.js";
 import { assertOk } from "../api/public/_http.js";
 import { legacyPublicBaseUrl } from "../api/public/urls.js";
 import { canonicalFor } from "../exchanges/canonical-symbols.js";
 import { fundingBasisOf, settlementIntervalOf } from "../exchanges/venue.js";
+import { nextTopOfHourMs } from "../exchanges/venue-types.js";
 // ── Classification ──
-const AMBIGUOUS = new Set(["SPX"]);
-/** Pacifica non-crypto perps (live /info 2026-09-30). BP / CHIP: ticker collides with a listed equity/ETF. */
+/** Pacifica non-crypto perps (live /info 2026-09-30). Ambiguous BP / CHIP / SPX: UNCLASSIFIED_TICKERS. */
 const PACIFICA_NON_CRYPTO = {
     NVDA: "equity", TSLA: "equity", GOOGL: "equity", PLTR: "equity", HOOD: "equity", CRCL: "equity",
     SPCX: "equity", SKHYNIX: "equity", SAMSUNG: "equity", MSTR: "equity", MU: "equity", SNDK: "equity",
@@ -46,19 +49,20 @@ const PACIFICA_NON_CRYPTO = {
     USDJPY: "fx", EURUSD: "fx",
     SP500: "index",
 };
-const PACIFICA_AMBIGUOUS = new Set(["BP", "CHIP"]);
+// Ambiguous tickers are listed as "unclassified" (canonical null: never matched across venues),
+// so every listing path (CLI, MCP, public directory) shows the same market set.
 function classifyPacifica(symbol) {
     const up = symbol.toUpperCase();
-    if (AMBIGUOUS.has(up) || PACIFICA_AMBIGUOUS.has(up))
-        return null;
+    if (isUnclassifiedTicker("pacifica", up))
+        return "unclassified";
     return PACIFICA_NON_CRYPTO[up] ?? "crypto"; // crypto-centric venue: non-crypto is listed explicitly
 }
 function classifyHyperliquid(symbol) {
-    return AMBIGUOUS.has(symbol.toUpperCase()) ? null : "crypto";
+    return isUnclassifiedTicker("hyperliquid", symbol) ? "unclassified" : "crypto";
 }
 function classifyAster(symbol, subTypes) {
-    if (AMBIGUOUS.has(symbol.toUpperCase()))
-        return null;
+    if (isUnclassifiedTicker("aster", symbol))
+        return "unclassified";
     if (subTypes.includes("pre-launch"))
         return "preIpo";
     if (subTypes.includes("ETF"))
@@ -75,6 +79,10 @@ function warnExcluded(venue, what, symbols) {
     }
 }
 // ── HTTP ──
+/** One public JSON read with the venue error mapping (rate limits, HTTP status, invalid JSON). */
+export async function legacyPublicJson(venue, url, label, init) {
+    return getJson(venue, url, label, init);
+}
 async function getJson(venue, url, label, init) {
     const res = await fetch(url, { ...init, signal: AbortSignal.timeout(15_000) });
     await assertOk(res, `${venue} ${label}`);
@@ -124,21 +132,16 @@ async function pacificaRows(net) {
     const basis = fundingBasisOf("pacifica");
     const settlement = settlementIntervalOf("pacifica");
     const out = [];
-    const unclassified = [];
     const unpriced = [];
     for (const m of info) {
-        // /info lists spot markets too (e.g. SOL-USDC). A row without the field cannot be classified.
+        // /info lists spot markets too (e.g. SOL-USDC): perps only. A row without the field cannot be classified.
         if (typeof m.instrument_type !== "string") {
             throw new PerpError("EXCHANGE_ERROR", `Pacifica /info row ${String(m.symbol)} has no instrument_type`, { exchange: "pacifica" });
         }
-        if (m.instrument_type === "spot")
+        if (!isPacificaPerpetual(m))
             continue;
         const symbol = String(m.symbol ?? "");
         const assetClass = classifyPacifica(symbol);
-        if (assetClass === null) {
-            unclassified.push(symbol);
-            continue;
-        }
         const p = priceBySymbol.get(symbol);
         const mark = p ? positiveNumStr(p.mark) : null;
         if (!p || mark === null) {
@@ -157,7 +160,9 @@ async function pacificaRows(net) {
                 quoteAsset: null,
                 markPrice: mark,
                 indexPrice: positiveNumStr(p.oracle),
-                fundingRate: rateStr(p.next_funding),
+                // Last settled hourly rate (WS prices `funding`, the CLI row's fundingRate); next_funding
+                // is the predicted one.
+                fundingRate: rateStr(p.funding),
                 fundingRateBasis: basis,
                 settlementIntervalHours: settlement,
                 openInterest: numStr(p.open_interest),
@@ -171,10 +176,9 @@ async function pacificaRows(net) {
                 session: null,
                 tradable: true,
             },
-            nextFundingTime: null, // Pacifica publishes no next-funding timestamp
+            nextFundingTime: nextTopOfHourMs(), // not published; docs: settled at the end of each 1 h interval (on the hour)
         });
     }
-    warnExcluded("pacifica", "unclassified/ambiguous market(s)", unclassified);
     warnExcluded("pacifica", "market(s) without a mark price", unpriced);
     return out;
 }
@@ -197,16 +201,15 @@ async function hyperliquidRows(net) {
     const basis = fundingBasisOf("hyperliquid");
     const settlement = settlementIntervalOf("hyperliquid");
     const out = [];
-    const unclassified = [];
     const unpriced = [];
     universe.forEach((a, i) => {
+        // Delisted assets stay in meta (isDelisted: true) with zeroed funding / volume / OI
+        // (live 2026-10-14: 56 of 234) — not a market: excluded from listings, prices and scans.
+        if (a.isDelisted === true)
+            return;
         const ctx = ctxs[i];
         const symbol = String(a.name ?? "");
         const assetClass = classifyHyperliquid(symbol);
-        if (assetClass === null) {
-            unclassified.push(symbol);
-            return;
-        }
         const mark = positiveNumStr(ctx.markPx);
         if (mark === null) {
             unpriced.push(symbol);
@@ -237,12 +240,11 @@ async function hyperliquidRows(net) {
                 maxLeverage: Number.isFinite(maxLeverage) && maxLeverage > 0 ? maxLeverage : null,
                 marginTiers: null,
                 session: null,
-                tradable: a.isDelisted !== true,
+                tradable: true, // delisted assets are skipped above
             },
-            nextFundingTime: null, // not published in metaAndAssetCtxs
+            nextFundingTime: nextTopOfHourMs(), // not in metaAndAssetCtxs; docs: paid every hour (on the hour)
         });
     });
-    warnExcluded("hyperliquid", "unclassified/ambiguous market(s)", unclassified);
     warnExcluded("hyperliquid", "market(s) without a mark price", unpriced);
     return out;
 }
@@ -271,20 +273,20 @@ async function asterRows(net) {
             intervalBySymbol.set(String(f.symbol), h);
     }
     const out = [];
-    const unclassified = [];
     const unpriced = [];
     const noInterval = [];
     for (const s of symbols) {
-        if (s.contractType !== "PERPETUAL" || s.quoteAsset !== "USDT")
+        // Shared eligibility (SETTLING / PENDING_TRADING rows were listed with tradable false); every
+        // quote, like the CLI adapter and the WS directory.
+        if (!isAsterListedPerpetual(s))
             continue;
         const venueSymbol = String(s.symbol);
-        const symbol = String(s.baseAsset);
+        const symbol = asterCliSymbol({ symbol: venueSymbol, baseAsset: String(s.baseAsset), quoteAsset: s.quoteAsset });
+        const base = String(s.baseAsset);
         const subTypes = Array.isArray(s.underlyingSubType) ? s.underlyingSubType.map(String) : [];
-        const assetClass = classifyAster(symbol, subTypes);
-        if (assetClass === null) {
-            unclassified.push(venueSymbol);
-            continue;
-        }
+        const assetClass = classifyAster(base, subTypes);
+        // A second listing of a base (BTCUSD1 beside BTCUSDT) or a non-USD quote (U): canonical null.
+        const matchable = asterMatchable(s);
         const p = premiumBySymbol.get(venueSymbol);
         const mark = p ? positiveNumStr(p.markPrice) : null;
         if (!p || mark === null) {
@@ -306,10 +308,10 @@ async function asterRows(net) {
                 venue: "aster",
                 venueSymbol,
                 symbol,
-                canonical: canonicalFor("aster", symbol, assetClass),
+                canonical: matchable ? canonicalFor("aster", base, assetClass) : null,
                 assetClass,
                 settle: s.marginAsset,
-                quoteAsset: s.quoteAsset,
+                quoteAsset: typeof s.quoteAsset === "string" && s.quoteAsset !== "" ? s.quoteAsset : null,
                 markPrice: mark,
                 indexPrice: positiveNumStr(p.indexPrice),
                 fundingRate: rateStr(p.lastFundingRate),
@@ -329,7 +331,6 @@ async function asterRows(net) {
             nextFundingTime: Number.isFinite(next) && next > 0 ? next : null,
         });
     }
-    warnExcluded("aster", "unclassified/ambiguous market(s)", unclassified);
     warnExcluded("aster", "market(s) without a mark price", unpriced);
     warnExcluded("aster", "market(s) missing from fundingInfo", noInterval);
     return out;

package/dist/funding/normalize.d.ts

@@ -1,5 +1,5 @@
 /**
- * Funding rate normalization (design §10.1, §10.13 #1).
+ * Funding rate normalization.
  *
  * The number of hours one quoted rate covers (the funding BASIS) comes from the
  * venue definition — `VenueDefinition.fundingRateBasis`, read through

package/dist/funding/normalize.js

@@ -1,5 +1,5 @@
 /**
- * Funding rate normalization (design §10.1, §10.13 #1).
+ * Funding rate normalization.
  *
  * The number of hours one quoted rate covers (the funding BASIS) comes from the
  * venue definition — `VenueDefinition.fundingRateBasis`, read through

package/dist/funding/rates.d.ts

@@ -1,17 +1,18 @@
 /**
  * Real-time cross-venue funding rate comparison.
  *
- * Fans out over every venue with the "marketData" role (design §10.6) using
+ * Fans out over every venue with the "marketData" role using
  * each venue's `publicData.fetchFundingRates(net)`, normalizes every row to a
  * per-hour rate with the row's own basis (Lighter
  * family 8h, Aster per-symbol), and matches markets across venues by
- * `canonical` (null → excluded, §10.9).
+ * `canonical` (null → excluded).
  *
  * A venue that fails is reported in `exchangeStatus` ("error") and
  * `exchangeErrors` (message) — its rows are absent, never silently empty.
  */
 import { type HistoricalAverages } from "./history.js";
 import { type VenueDefinition } from "../exchanges/venue.js";
+import type { FundingRateKind } from "../exchanges/interface.js";
 import { type FundingRateBasis, type Network, type VenueId } from "../exchanges/venue-types.js";
 export interface ExchangeFundingRate {
     exchange: VenueId;
@@ -28,22 +29,65 @@ export interface ExchangeFundingRate {
     historicalAvg: HistoricalAverages | null;
     /** false = the venue's funding rate is unverified (VenueDefinition.fundingVerified) — shown only on explicit request. */
     fundingVerified: boolean;
+    /** How the row was read: "unofficial" = an undocumented venue API (VenueDefinition.apiStatus) — may change without notice. */
+    apiStatus: "official" | "unofficial";
+    /**
+     * Which rate `fundingRate` is (the venue market row's rate — arb compares those, never a
+     * predicted next-period rate unless the venue only publishes that): "lastSettled" | "accruing" |
+     * "predicted", null = not verified (fundingRateKindOf).
+     */
+    rateKind: FundingRateKind | null;
 }
 export interface SymbolFundingComparison {
     /** Canonical symbol shared by every row. */
     symbol: string;
     rates: ExchangeFundingRate[];
+    /**
+     * Ranking is over VERIFIED rows only (VenueDefinition.fundingVerified): an unverified row
+     * (`--include-unverified`) is shown in `rates` but is never the long or short leg nor part of
+     * the spread. Fewer than two verified rows → no ranked pair: longExchange / shortExchange /
+     * maxSpreadAnnual / estHourlyIncomeUsd are null (a display-only row).
+     */
+    maxSpreadAnnual: number | null;
+    longExchange: string | null;
+    shortExchange: string | null;
+    bestMarkPrice: number;
+    estHourlyIncomeUsd: number | null;
+    /**
+     * false = a leg of the long/short pair sits on a venue without the trading role (RISEx while its
+     * trading is gated in this release): the spread is data only — `arb exec` refuses it.
+     */
+    executable: boolean;
+    /**
+     * true = the row's rates are of different kinds (e.g. Lighter lastSettled vs Hyperliquid
+     * accruing) — the perp-ws comparator's `mixedKinds`: the spread compares unlike quantities.
+     */
+    mixedKinds: boolean;
+    /** Venues of the long/short pair that perp-cli cannot trade (read-only); [] when executable. */
+    readOnlyLegs: string[];
+    /**
+     * Venues of the long/short pair whose funding is unverified (VenueDefinition.fundingVerified
+     * false, e.g. QFEX — shown only with --include-unverified, display only); such a pair is never
+     * executable. [] when both legs are verified.
+     */
+    unverifiedLegs: string[];
+}
+/** A comparison with a ranked pair (≥ 2 verified rows): long / short / spread / income are set. */
+export type RankedFundingComparison = SymbolFundingComparison & {
     maxSpreadAnnual: number;
     longExchange: string;
     shortExchange: string;
-    bestMarkPrice: number;
     estHourlyIncomeUsd: number;
-}
+};
+export declare function isRankedComparison(c: SymbolFundingComparison): c is RankedFundingComparison;
 export interface FundingRateSnapshot {
     timestamp: string;
     symbols: SymbolFundingComparison[];
+    /** The minSpread applied (annualized %) and how many ranked pairs it hid (spread below it). */
+    minSpread: number;
+    belowMinSpread: number;
     exchangeStatus: Record<string, "ok" | "error">;
-    /** Error message per venue whose status is "error" (§10.13 #3). */
+    /** Error message per venue whose status is "error". */
     exchangeErrors: Record<string, string>;
 }
 export declare const TOP_SYMBOLS: string[];
@@ -59,6 +103,51 @@ export declare function fetchVenuesRates(venues: VenueDefinition[], net: Network
     exchangeStatus: Record<string, "ok" | "error">;
     exchangeErrors: Record<string, string>;
 }>;
+/**
+ * Same canonical ticker on two venues is not proof of the same asset (e.g. two
+ * unrelated tokens both listed as "PRL"). Within a canonical group, drop any
+ * venue whose mark price deviates more than MAX_PRICE_DEVIATION_PCT from the
+ * group median, with a one-time stderr warning per (symbol, venue).
+ */
+export declare function dropPriceOutliers<T extends {
+    exchange: VenueId;
+    markPrice: number;
+}>(canonical: string, list: T[], tag?: string): T[];
+export interface VenuePrice {
+    exchange: VenueId;
+    /** Venue display symbol. */
+    symbol: string;
+    canonical: string;
+    markPrice: number;
+    apiStatus: "official" | "unofficial";
+}
+export interface PriceGroupSnapshot {
+    /** canonical → venue prices, after the median price-outlier drop (same guard as the funding scan). */
+    groups: Map<string, VenuePrice[]>;
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
+}
+/**
+ * Mark prices of `venues`, grouped by canonical symbol — the grouping and price-outlier guard of
+ * the funding comparison, WITHOUT any funding dependency: read from each venue's market directory
+ * (publicData.fetchMarkets), so a market with a null funding rate or a venue whose funding is
+ * unverified is still priced. Rows without a canonical symbol, not tradable, or without a
+ * positive mark are excluded. A venue that fails is reported in exchangeStatus / exchangeErrors.
+ */
+export declare function fetchCanonicalPriceGroups(venues: VenueDefinition[], opts?: {
+    symbols?: string[];
+    network?: Network;
+    tag?: string;
+}): Promise<PriceGroupSnapshot>;
+/**
+ * Whether a long/short pair can be traded as a funding arb: both legs need the trading role AND
+ * verified funding (an unverified-funding venue is display only — never ranked for trading).
+ */
+export declare function pairExecutability(longExchange: string, shortExchange: string): {
+    executable: boolean;
+    readOnlyLegs: string[];
+    unverifiedLegs: string[];
+};
 /**
  * Fetch funding rates from every market-data venue in parallel, normalize, and compare.
  * Returns rates sorted by max spread (descending).
@@ -97,7 +186,7 @@ export interface SpotPerpSpread {
 /**
  * Fetch spot+perp funding rate spreads.
  * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
- * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
+ * Only includes symbols available on at least one bot spot venue (def.spot).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN

package/dist/funding/rates.js

@@ -1,11 +1,11 @@
 /**
  * Real-time cross-venue funding rate comparison.
  *
- * Fans out over every venue with the "marketData" role (design §10.6) using
+ * Fans out over every venue with the "marketData" role using
  * each venue's `publicData.fetchFundingRates(net)`, normalizes every row to a
  * per-hour rate with the row's own basis (Lighter
  * family 8h, Aster per-symbol), and matches markets across venues by
- * `canonical` (null → excluded, §10.9).
+ * `canonical` (null → excluded).
  *
  * A venue that fails is reported in `exchangeStatus` ("error") and
  * `exchangeErrors` (message) — its rows are absent, never silently empty.
@@ -14,10 +14,15 @@ import { annualizeHourlyRate, estimateHourlyFundingFromHourly } from "./normaliz
 import { getHistoricalAverages } from "./history.js";
 import { SPOT_PERP_TOKEN_MAP, MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
 import { getVenue, listVenuesWithRole, READ_ONLY_CREDENTIALS } from "../exchanges/venue.js";
-import { rateToHourly } from "../exchanges/venue-types.js";
+import { fundingRateKindOf, rateToHourly } from "../exchanges/venue-types.js";
 import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 import { sharedApiNetwork } from "../api/public/urls.js";
 import { PerpError } from "../errors.js";
+import { canonicalQuerySymbol } from "../exchanges/canonical-symbols.js";
+export function isRankedComparison(c) {
+    // estHourlyIncomeUsd is set together with the pair (null exactly when the pair is).
+    return c.longExchange !== null && c.shortExchange !== null && c.maxSpreadAnnual !== null;
+}
 // ── Default top symbols to track ──
 export const TOP_SYMBOLS = [
     "BTC", "ETH", "SOL", "DOGE", "SUI", "AVAX", "LINK", "ARB",
@@ -26,7 +31,11 @@ export const TOP_SYMBOLS = [
 ];
 /** Mark-price source preference for `bestMarkPrice` (most liquid first). */
 const MARK_PRICE_PREFERENCE = [
-    "hyperliquid", "pacifica", "lighter", "aster", "lighter-rh", "ondo", "arcus", "qfex",
+    "hyperliquid", "pacifica", "lighter", "aster", "lighter-rh", "ondo", "arcus", "risex", "qfex", "grvt", "extended",
+    // RFQ venue: the mark is the single maker's (OLP) price.
+    "variational",
+    // Unofficial API: last resort as a mark-price source.
+    "txflow",
 ];
 // ── Per-venue fetch ──
 function errorMessage(e) {
@@ -51,20 +60,24 @@ async function fetchVenueRates(def, net) {
     for (const r of rows) {
         if (r.canonical === null)
             continue; // not matchable across venues
+        // Outside its funding hours (QFEX market_hours) a market has no rate: never ranked, snapshotted
+        // (saveFundingSnapshot) or averaged as a 0.
+        if (r.rate === null || r.marketClosed === true)
+            continue;
         const markRaw = r.markPrice !== null ? r.markPrice : markBySymbol?.get(r.venueSymbol);
         const markPrice = markRaw === undefined ? NaN : Number(markRaw);
         if (!Number.isFinite(markPrice) || markPrice <= 0) {
             unpriced.push(r.symbol);
             continue;
         }
-        out.push(toExchangeRate(r, r.canonical, markPrice, def.fundingVerified));
+        out.push(toExchangeRate({ ...r, rate: r.rate }, r.canonical, markPrice, def.fundingVerified, def.apiStatus.kind));
     }
     if (unpriced.length > 0) {
         console.warn(`[${def.id}] excluded ${unpriced.length} funding row(s) without a mark price: ${unpriced.join(", ")}`);
     }
     return out;
 }
-function toExchangeRate(r, canonical, markPrice, fundingVerified) {
+function toExchangeRate(r, canonical, markPrice, fundingVerified, apiStatus) {
     const fundingRate = Number(r.rate);
     if (!Number.isFinite(fundingRate)) {
         throw new PerpError("EXCHANGE_ERROR", `${r.venue} ${r.symbol}: non-numeric funding rate "${r.rate}"`);
@@ -82,6 +95,8 @@ function toExchangeRate(r, canonical, markPrice, fundingVerified) {
         nextFundingTime: r.nextFundingTime,
         historicalAvg: null,
         fundingVerified,
+        apiStatus,
+        rateKind: fundingRateKindOf(r.venue, r.rate),
     };
 }
 /**
@@ -117,7 +132,7 @@ const _warnedPriceMismatch = new Set();
  * venue whose mark price deviates more than MAX_PRICE_DEVIATION_PCT from the
  * group median, with a one-time stderr warning per (symbol, venue).
  */
-function dropPriceOutliers(canonical, list) {
+export function dropPriceOutliers(canonical, list, tag = "funding") {
     if (list.length < 2)
         return list;
     const sorted = list.map(r => r.markPrice).sort((x, y) => x - y);
@@ -133,12 +148,12 @@ function dropPriceOutliers(canonical, list) {
         const key = `${canonical}:${r.exchange}`;
         if (!_warnedPriceMismatch.has(key)) {
             _warnedPriceMismatch.add(key);
-            process.stderr.write(`[funding] excluded ${r.exchange} ${canonical}: mark ${r.markPrice} deviates ${devPct.toFixed(1)}% from cross-venue median ${mid} (likely a different asset with the same ticker)\n`);
+            process.stderr.write(`[${tag}] excluded ${r.exchange} ${canonical}: mark ${r.markPrice} deviates ${devPct.toFixed(1)}% from cross-venue median ${mid} (likely a different asset with the same ticker)\n`);
         }
         return false;
     });
 }
-function groupByCanonical(rates, symbols) {
+function groupByCanonical(rates, symbols, tag = "funding") {
     const out = new Map();
     for (const r of rates) {
         if (symbols && !symbols.includes(r.canonical))
@@ -150,7 +165,7 @@ function groupByCanonical(rates, symbols) {
             out.set(r.canonical, [r]);
     }
     for (const [canonical, list] of [...out]) {
-        const kept = dropPriceOutliers(canonical, list);
+        const kept = dropPriceOutliers(canonical, list, tag);
         if (kept.length === 0)
             out.delete(canonical); // every venue disagreed — not comparable
         else
@@ -158,6 +173,49 @@ function groupByCanonical(rates, symbols) {
     }
     return out;
 }
+/**
+ * Mark prices of `venues`, grouped by canonical symbol — the grouping and price-outlier guard of
+ * the funding comparison, WITHOUT any funding dependency: read from each venue's market directory
+ * (publicData.fetchMarkets), so a market with a null funding rate or a venue whose funding is
+ * unverified is still priced. Rows without a canonical symbol, not tradable, or without a
+ * positive mark are excluded. A venue that fails is reported in exchangeStatus / exchangeErrors.
+ */
+export async function fetchCanonicalPriceGroups(venues, opts) {
+    ensureVenuesRegistered();
+    const net = opts?.network ?? sharedApiNetwork();
+    const settled = await Promise.allSettled(venues.map(v => v.publicData.fetchMarkets(net, { funding: false })));
+    const exchangeStatus = {};
+    const exchangeErrors = {};
+    const prices = [];
+    settled.forEach((res, i) => {
+        const def = venues[i];
+        if (res.status === "rejected") {
+            exchangeStatus[def.id] = "error";
+            exchangeErrors[def.id] = errorMessage(res.reason);
+            return;
+        }
+        exchangeStatus[def.id] = "ok";
+        for (const m of res.value) {
+            if (m.canonical === null || !m.tradable)
+                continue;
+            const markPrice = Number(m.markPrice);
+            if (!Number.isFinite(markPrice) || markPrice <= 0)
+                continue;
+            prices.push({ exchange: def.id, symbol: m.symbol, canonical: m.canonical, markPrice, apiStatus: def.apiStatus.kind });
+        }
+    });
+    return { groups: groupByCanonical(prices, opts?.symbols, opts?.tag ?? "prices"), exchangeStatus, exchangeErrors };
+}
+/**
+ * Whether a long/short pair can be traded as a funding arb: both legs need the trading role AND
+ * verified funding (an unverified-funding venue is display only — never ranked for trading).
+ */
+export function pairExecutability(longExchange, shortExchange) {
+    const legs = [...new Set([longExchange, shortExchange])];
+    const readOnlyLegs = legs.filter(v => !getVenue(v).roles.includes("trading"));
+    const unverifiedLegs = legs.filter(v => !getVenue(v).fundingVerified);
+    return { executable: readOnlyLegs.length === 0 && unverifiedLegs.length === 0, readOnlyLegs, unverifiedLegs };
+}
 function bestMarkPrice(rates) {
     const rank = (id) => MARK_PRICE_PREFERENCE.indexOf(id);
     return [...rates].sort((a, b) => rank(a.exchange) - rank(b.exchange))[0].markPrice;
@@ -183,14 +241,28 @@ export async function fetchAllFundingRates(opts) {
     }
     const comparisons = [];
     const minSpread = opts?.minSpread ?? 0;
+    let belowMinSpread = 0;
     for (const [symbol, rates] of rateMap) {
         // Need at least 2 exchanges to compare
         if (rates.length < 2)
             continue;
         // Sort by hourly rate (ascending)
         rates.sort((a, b) => a.hourlyRate - b.hourlyRate);
-        const lowest = rates[0];
-        const highest = rates[rates.length - 1];
+        // The long / short legs and the spread come from verified rows only: an unverified rate is
+        // display data (--include-unverified), never ranked. < 2 verified rows → a display-only row.
+        const ranked = rates.filter(r => r.fundingVerified);
+        if (ranked.length < 2) {
+            const unverifiedLegs = [...new Set(rates.filter(r => !r.fundingVerified).map(r => r.exchange))];
+            comparisons.push({
+                symbol, rates, maxSpreadAnnual: null, longExchange: null, shortExchange: null,
+                bestMarkPrice: bestMarkPrice(rates), estHourlyIncomeUsd: null,
+                executable: false, readOnlyLegs: [], unverifiedLegs,
+                mixedKinds: new Set(rates.map(r => r.rateKind)).size > 1,
+            });
+            continue;
+        }
+        const lowest = ranked[0];
+        const highest = ranked[ranked.length - 1];
         // The median filter alone lets a 2-venue group through at up to 2 × MAX_PRICE_DEVIATION_PCT
         // apart (each side deviates half the gap): the CHOSEN pair must itself agree on price.
         const pairGapPct = Math.abs(lowest.markPrice - highest.markPrice) / ((lowest.markPrice + highest.markPrice) / 2) * 100;
@@ -203,8 +275,10 @@ export async function fetchAllFundingRates(opts) {
             continue;
         }
         const maxSpreadAnnual = annualizeHourlyRate(highest.hourlyRate - lowest.hourlyRate);
-        if (maxSpreadAnnual < minSpread)
+        if (maxSpreadAnnual < minSpread) {
+            belowMinSpread++;
             continue;
+        }
         // Estimate hourly income for $1000 notional arb
         const notional = 1000;
         const longIncome = estimateHourlyFundingFromHourly(lowest.hourlyRate, notional, "long");
@@ -218,13 +292,17 @@ export async function fetchAllFundingRates(opts) {
             shortExchange: highest.exchange, // short where funding is highest
             bestMarkPrice: bestMarkPrice(rates),
             estHourlyIncomeUsd,
+            ...pairExecutability(lowest.exchange, highest.exchange),
+            mixedKinds: new Set(rates.map(r => r.rateKind)).size > 1,
         });
     }
-    // Sort by spread descending
-    comparisons.sort((a, b) => b.maxSpreadAnnual - a.maxSpreadAnnual);
+    // Sort by spread descending; display-only rows (no ranked pair) last
+    comparisons.sort((a, b) => (b.maxSpreadAnnual ?? -Infinity) - (a.maxSpreadAnnual ?? -Infinity));
     return {
         timestamp: new Date().toISOString(),
         symbols: comparisons,
+        minSpread,
+        belowMinSpread,
         exchangeStatus,
         exchangeErrors,
     };
@@ -233,13 +311,15 @@ export async function fetchAllFundingRates(opts) {
  * Fetch rates for a single (canonical) symbol across all exchanges.
  */
 export async function fetchSymbolFundingRates(symbol, includeUnverified = false) {
-    const snapshot = await fetchAllFundingRates({ symbols: [symbol.toUpperCase()], includeUnverified });
+    // The comparison groups by canonical key: a venue ticker / denomination alias (kPEPE) is
+    // looked up under its canonical symbol (1000PEPE), never as-is.
+    const snapshot = await fetchAllFundingRates({ symbols: [canonicalQuerySymbol(symbol)], includeUnverified });
     return snapshot.symbols[0] ?? null;
 }
 /**
  * Fetch spot+perp funding rate spreads.
  * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
- * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
+ * Only includes symbols available on at least one bot spot venue (def.spot).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
@@ -247,8 +327,8 @@ export async function fetchSymbolFundingRates(symbol, includeUnverified = false)
  *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
  */
 export async function fetchSpotPerpSpreads(opts) {
-    // Spot legs come from the venue definitions (def.spot, §12): only bot/arb spot venues
-    // (separate/runtime account + transfer, §12.4 #3). Perp legs: those venues + pacifica.
+    // Spot legs come from the venue definitions (def.spot): only bot/arb spot venues
+    // (separate/runtime account + transfer). Perp legs: those venues + pacifica.
     ensureVenuesRegistered();
     const net = opts?.network ?? sharedApiNetwork();
     const { listBotSpotVenues, requireSpotAdapter, defaultSpotQuote } = await import("../exchanges/spot-factory.js");