perp-cli 0.14.3 → 0.16.0

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

@@ -1,5 +1,6 @@
 import { printJson, jsonOk, jsonError, makeTable, formatUsd } from "../utils.js";
 import { getHistoricalRates } from "../funding-history.js";
+import { HyperliquidAdapter, hlEarliestCandleStart } from "../exchanges/hyperliquid.js";
 import chalk from "chalk";
 export function registerBacktestCommands(program, isJson) {
     const backtest = program.command("backtest").description("Backtest trading strategies on historical data");
@@ -32,10 +33,13 @@ export function registerBacktestCommands(program, isJson) {
         const ratesA = getHistoricalRates(sym, exchA, startTime, endTime);
         const ratesB = getHistoricalRates(sym, exchB, startTime, endTime);
         if (ratesA.length === 0 && ratesB.length === 0) {
+            // The funding history is written by `arb scan --rates` (saveFundingSnapshot; verified venues
+            // only). There is no `perp funding snapshot` command (0.15.0 named one).
+            const collect = `perp arb scan --rates --symbol ${sym}`;
             if (isJson())
-                return printJson(jsonError("NO_DATA", `No historical funding data for ${sym}. Run 'perp funding snapshot' first to collect data.`));
+                return printJson(jsonError("NO_DATA", `No historical funding data for ${sym}. Run '${collect}' periodically to collect data first.`));
             console.log(chalk.yellow(`\n  No historical funding data for ${sym} on ${exchA}/${exchB}.`));
-            console.log(chalk.yellow(`  Run 'perp funding snapshot' periodically to collect data first.\n`));
+            console.log(chalk.yellow(`  Run '${collect}' periodically to collect data first.\n`));
             return;
         }
         // Build time-aligned rate pairs
@@ -180,31 +184,25 @@ export function registerBacktestCommands(program, isJson) {
             console.error(chalk.red("Error: Need at least 2 grid lines"));
             process.exit(1);
         }
+        // Hyperliquid serves only the most recent 5000 candles per interval (docs "Candle snapshot");
+        // with 1h candles a --days above ~208 cannot be read. The start is clamped to the available
+        // window (one hour inside it) and the result says so — never presented as the full period.
+        const DAY_MS = 24 * 60 * 60 * 1000;
         const endTime = Date.now();
-        const startTime = endTime - days * 24 * 60 * 60 * 1000;
-        // Fetch historical klines from Hyperliquid
+        const requestedStart = endTime - days * DAY_MS;
+        const earliest = hlEarliestCandleStart("1h", endTime) + 60 * 60 * 1000;
+        const truncated = requestedStart < earliest;
+        const startTime = truncated ? earliest : requestedStart;
+        const dataFrom = startTime;
+        const coveredDays = (endTime - startTime) / DAY_MS;
+        // Fetch historical klines from Hyperliquid (adapter: symbol resolution, interval / window checks)
         if (!isJson()) {
             console.log(chalk.gray(`\n  Fetching ${days}d of 1h klines for ${sym}...`));
         }
         let klines;
         try {
-            const resp = await fetch("https://api.hyperliquid.xyz/info", {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    type: "candleSnapshot",
-                    req: {
-                        coin: sym,
-                        interval: "1h",
-                        startTime,
-                        endTime,
-                    },
-                }),
-            });
-            if (!resp.ok)
-                throw new Error(`HTTP ${resp.status}`);
-            const data = await resp.json();
-            klines = data.map(k => ({ t: k.t, o: k.o, h: k.h, l: k.l, c: k.c }));
+            const rows = await new HyperliquidAdapter(undefined, false).getKlines(sym, "1h", startTime, endTime);
+            klines = rows.map(k => ({ t: k.time, o: k.open, h: k.high, l: k.low, c: k.close }));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -291,6 +289,8 @@ export function registerBacktestCommands(program, isJson) {
             symbol: sym,
             period: `${days} days`,
             klines: klines.length,
+            dataFrom: new Date(dataFrom).toISOString(),
+            truncated,
             priceRange,
             gridRange: `$${formatUsd(String(lowerPrice))} - $${formatUsd(String(upperPrice))}`,
             grids,
@@ -307,6 +307,8 @@ export function registerBacktestCommands(program, isJson) {
             return printJson(jsonOk(summary));
         console.log(chalk.cyan.bold(`\n  Grid Backtest — ${sym}\n`));
         console.log(`  Period:         ${days} days (${klines.length} candles)`);
+        if (truncated)
+            console.log(chalk.yellow(`  Truncated:      Hyperliquid serves only the most recent 5000 1h candles — start clamped to ${new Date(dataFrom).toISOString()} (${coveredDays.toFixed(1)} of ${days} days)`));
         console.log(`  Price range:    ${priceRange}`);
         console.log(`  Grid range:     $${formatUsd(String(lowerPrice))} - $${formatUsd(String(upperPrice))}`);
         console.log(`  Grid lines:     ${grids} (step: $${step.toFixed(2)})`);

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;