perp-cli 0.12.17 → 0.14.0

package/dist/funding/legacy-public.js

@@ -0,0 +1,369 @@
+/**
+ * Public market data for the legacy venues without a native `getVenueMarkets`
+ * (pacifica, hyperliquid core, aster) — design §10.6. Lighter uses
+ * exchanges/lighter-public.ts.
+ *
+ * Network-aware: the REST base comes from `legacyPublicBaseUrl(venue, net)`,
+ * never from the mutable `*_API_URL` globals. A network without a known public
+ * API throws NOT_IMPLEMENTED.
+ *
+ * FUNDING BASIS / SETTLEMENT
+ *   pacifica, hyperliquid: the venue definition (fundingBasisOf / settlementIntervalOf).
+ *   aster: per symbol from GET /fapi/v3/fundingInfo `fundingIntervalHours`
+ *     (live 2026-09-30: 1h/2h/4h/8h mixed). One quoted rate covers one interval,
+ *     so basis hours == settlement hours. A symbol missing from fundingInfo is
+ *     excluded with a warning (its period would be a guess).
+ *
+ * ASSET CLASS
+ *   hyperliquid core: crypto (HIP-3 dexes are not served here).
+ *   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).
+ *
+ * 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 { 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";
+// ── Classification ──
+const AMBIGUOUS = new Set(["SPX"]);
+/** Pacifica non-crypto perps (live /info 2026-09-30). BP / CHIP: ticker collides with a listed equity/ETF. */
+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",
+    META: "equity",
+    DRAM: "etf", URNM: "etf",
+    XAU: "commodity", XAG: "commodity", CL: "commodity", COPPER: "commodity", NATGAS: "commodity",
+    PLATINUM: "commodity",
+    USDJPY: "fx", EURUSD: "fx",
+    SP500: "index",
+};
+const PACIFICA_AMBIGUOUS = new Set(["BP", "CHIP"]);
+function classifyPacifica(symbol) {
+    const up = symbol.toUpperCase();
+    if (AMBIGUOUS.has(up) || PACIFICA_AMBIGUOUS.has(up))
+        return null;
+    return PACIFICA_NON_CRYPTO[up] ?? "crypto"; // crypto-centric venue: non-crypto is listed explicitly
+}
+function classifyHyperliquid(symbol) {
+    return AMBIGUOUS.has(symbol.toUpperCase()) ? null : "crypto";
+}
+function classifyAster(symbol, subTypes) {
+    if (AMBIGUOUS.has(symbol.toUpperCase()))
+        return null;
+    if (subTypes.includes("pre-launch"))
+        return "preIpo";
+    if (subTypes.includes("ETF"))
+        return "etf";
+    if (subTypes.includes("STOCK"))
+        return "equity";
+    if (subTypes.includes("Commodities"))
+        return "commodity";
+    return "crypto";
+}
+function warnExcluded(venue, what, symbols) {
+    if (symbols.length > 0) {
+        console.warn(`[${venue}] excluded ${symbols.length} ${what}: ${symbols.join(", ")}`);
+    }
+}
+// ── HTTP ──
+async function getJson(venue, url, label, init) {
+    const res = await fetch(url, { ...init, signal: AbortSignal.timeout(15_000) });
+    await assertOk(res, `${venue} ${label}`);
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} ${label}: invalid JSON`, { body: text.slice(0, 500) });
+    }
+}
+function arrayField(venue, label, v) {
+    if (!Array.isArray(v))
+        throw new PerpError("EXCHANGE_ERROR", `${venue} ${label}: expected an array`);
+    return v;
+}
+function numStr(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    if (typeof v === "string" && v.length > 0 && Number.isFinite(Number(v)))
+        return v;
+    return null;
+}
+/** A funding rate field: a JSON number without float noise (venueRateString), a numeric string verbatim; else null. */
+function rateStr(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return venueRateString(v);
+    return numStr(v);
+}
+function positiveNumStr(v) {
+    const s = numStr(v);
+    return s !== null && Number(s) > 0 ? s : null;
+}
+function stepFromDecimals(d) {
+    return d === 0 ? "1" : `0.${"0".repeat(d - 1)}1`;
+}
+// ── Pacifica ──
+async function pacificaRows(net) {
+    const base = legacyPublicBaseUrl("pacifica", net);
+    const [infoJson, pricesJson] = await Promise.all([
+        getJson("pacifica", `${base}/info`, "info"),
+        getJson("pacifica", `${base}/info/prices`, "info/prices"),
+    ]);
+    const info = arrayField("pacifica", "info", infoJson.data);
+    const prices = arrayField("pacifica", "info/prices", pricesJson.data);
+    const priceBySymbol = new Map(prices.map(p => [String(p.symbol), p]));
+    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.
+        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")
+            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) {
+            unpriced.push(symbol);
+            continue;
+        }
+        const maxLeverage = Number(m.max_leverage);
+        out.push({
+            market: {
+                venue: "pacifica",
+                venueSymbol: symbol,
+                symbol,
+                canonical: canonicalFor("pacifica", symbol, assetClass),
+                assetClass,
+                settle: "USDC",
+                quoteAsset: null,
+                markPrice: mark,
+                indexPrice: positiveNumStr(p.oracle),
+                fundingRate: rateStr(p.next_funding),
+                fundingRateBasis: basis,
+                settlementIntervalHours: settlement,
+                openInterest: numStr(p.open_interest),
+                volume24h: numStr(p.volume_24h),
+                tickSize: positiveNumStr(m.tick_size),
+                stepSize: positiveNumStr(m.lot_size),
+                minSize: null,
+                minNotional: positiveNumStr(m.min_order_size),
+                maxLeverage: Number.isFinite(maxLeverage) && maxLeverage > 0 ? maxLeverage : null,
+                marginTiers: null,
+                session: null,
+                tradable: true,
+            },
+            nextFundingTime: null, // Pacifica publishes no next-funding timestamp
+        });
+    }
+    warnExcluded("pacifica", "unclassified/ambiguous market(s)", unclassified);
+    warnExcluded("pacifica", "market(s) without a mark price", unpriced);
+    return out;
+}
+// ── Hyperliquid core ──
+async function hyperliquidRows(net) {
+    const base = legacyPublicBaseUrl("hyperliquid", net);
+    const json = await getJson("hyperliquid", `${base}/info`, "info metaAndAssetCtxs", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ type: "metaAndAssetCtxs" }),
+    });
+    if (!Array.isArray(json) || json.length < 2) {
+        throw new PerpError("EXCHANGE_ERROR", "hyperliquid metaAndAssetCtxs: expected [meta, assetCtxs]");
+    }
+    const universe = arrayField("hyperliquid", "meta.universe", json[0].universe);
+    const ctxs = arrayField("hyperliquid", "assetCtxs", json[1]);
+    if (ctxs.length !== universe.length) {
+        throw new PerpError("EXCHANGE_ERROR", `hyperliquid metaAndAssetCtxs: ${universe.length} assets vs ${ctxs.length} contexts`);
+    }
+    const basis = fundingBasisOf("hyperliquid");
+    const settlement = settlementIntervalOf("hyperliquid");
+    const out = [];
+    const unclassified = [];
+    const unpriced = [];
+    universe.forEach((a, i) => {
+        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);
+            return;
+        }
+        const szDecimals = Number(a.szDecimals);
+        const maxLeverage = Number(a.maxLeverage);
+        out.push({
+            market: {
+                venue: "hyperliquid",
+                venueSymbol: symbol,
+                symbol,
+                canonical: canonicalFor("hyperliquid", symbol, assetClass),
+                assetClass,
+                settle: "USDC",
+                quoteAsset: null,
+                markPrice: mark,
+                indexPrice: positiveNumStr(ctx.oraclePx),
+                fundingRate: rateStr(ctx.funding),
+                fundingRateBasis: basis,
+                settlementIntervalHours: settlement,
+                openInterest: numStr(ctx.openInterest),
+                volume24h: numStr(ctx.dayNtlVlm),
+                tickSize: null, // HL prices use a significant-figure rule, not a fixed tick
+                stepSize: Number.isInteger(szDecimals) && szDecimals >= 0 ? stepFromDecimals(szDecimals) : null,
+                minSize: null,
+                minNotional: HL_MIN_ORDER_VALUE_USD,
+                maxLeverage: Number.isFinite(maxLeverage) && maxLeverage > 0 ? maxLeverage : null,
+                marginTiers: null,
+                session: null,
+                tradable: a.isDelisted !== true,
+            },
+            nextFundingTime: null, // not published in metaAndAssetCtxs
+        });
+    });
+    warnExcluded("hyperliquid", "unclassified/ambiguous market(s)", unclassified);
+    warnExcluded("hyperliquid", "market(s) without a mark price", unpriced);
+    return out;
+}
+// ── Aster ──
+function asterFilter(filters, type, field) {
+    if (!Array.isArray(filters))
+        return null;
+    const f = filters.find(x => x.filterType === type);
+    return f ? positiveNumStr(f[field]) : null;
+}
+async function asterRows(net) {
+    const base = legacyPublicBaseUrl("aster", net);
+    const [infoJson, premiumJson, tickerJson, fundingInfoJson] = await Promise.all([
+        getJson("aster", `${base}/fapi/v1/exchangeInfo`, "exchangeInfo"),
+        getJson("aster", `${base}/fapi/v1/premiumIndex`, "premiumIndex"),
+        getJson("aster", `${base}/fapi/v1/ticker/24hr`, "ticker/24hr"),
+        getJson("aster", `${base}/fapi/v3/fundingInfo`, "fundingInfo"),
+    ]);
+    const symbols = arrayField("aster", "exchangeInfo.symbols", infoJson.symbols);
+    const premiumBySymbol = new Map(arrayField("aster", "premiumIndex", premiumJson).map(p => [String(p.symbol), p]));
+    const tickerBySymbol = new Map(arrayField("aster", "ticker/24hr", tickerJson).map(t => [String(t.symbol), t]));
+    const intervalBySymbol = new Map();
+    for (const f of arrayField("aster", "fundingInfo", fundingInfoJson)) {
+        const h = Number(f.fundingIntervalHours);
+        if (Number.isFinite(h) && h > 0)
+            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")
+            continue;
+        const venueSymbol = String(s.symbol);
+        const symbol = 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 p = premiumBySymbol.get(venueSymbol);
+        const mark = p ? positiveNumStr(p.markPrice) : null;
+        if (!p || mark === null) {
+            unpriced.push(venueSymbol);
+            continue;
+        }
+        const hours = intervalBySymbol.get(venueSymbol);
+        if (hours === undefined) {
+            noInterval.push(venueSymbol);
+            continue;
+        }
+        if (typeof s.marginAsset !== "string" || s.marginAsset.length === 0) {
+            throw new PerpError("EXCHANGE_ERROR", `aster exchangeInfo: ${venueSymbol} has no marginAsset`);
+        }
+        const next = Number(p.nextFundingTime);
+        const t = tickerBySymbol.get(venueSymbol);
+        out.push({
+            market: {
+                venue: "aster",
+                venueSymbol,
+                symbol,
+                canonical: canonicalFor("aster", symbol, assetClass),
+                assetClass,
+                settle: s.marginAsset,
+                quoteAsset: s.quoteAsset,
+                markPrice: mark,
+                indexPrice: positiveNumStr(p.indexPrice),
+                fundingRate: rateStr(p.lastFundingRate),
+                fundingRateBasis: { kind: "perHours", hours },
+                settlementIntervalHours: hours,
+                openInterest: null, // per-symbol endpoint only
+                volume24h: t ? numStr(t.quoteVolume) : null,
+                tickSize: asterFilter(s.filters, "PRICE_FILTER", "tickSize"),
+                stepSize: asterFilter(s.filters, "LOT_SIZE", "stepSize"),
+                minSize: asterFilter(s.filters, "LOT_SIZE", "minQty"),
+                minNotional: asterFilter(s.filters, "MIN_NOTIONAL", "notional"),
+                maxLeverage: null, // leverage brackets require a signed call
+                marginTiers: null,
+                session: null,
+                tradable: s.status === "TRADING",
+            },
+            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;
+}
+// ── VenuePublicData ──
+function rowsFor(venue, net) {
+    switch (venue) {
+        case "pacifica": return pacificaRows(net);
+        case "hyperliquid": return hyperliquidRows(net);
+        case "aster": return asterRows(net);
+    }
+}
+export function legacyPublicData(venue) {
+    return {
+        async fetchMarkets(net) {
+            return (await rowsFor(venue, net)).map(r => r.market);
+        },
+        async fetchFundingRates(net) {
+            const out = [];
+            for (const { market: m, nextFundingTime } of await rowsFor(venue, net)) {
+                if (!m.tradable || m.fundingRate === null)
+                    continue;
+                out.push({
+                    venue: m.venue,
+                    venueSymbol: m.venueSymbol,
+                    symbol: m.symbol,
+                    canonical: m.canonical,
+                    rate: m.fundingRate,
+                    basis: m.fundingRateBasis,
+                    markPrice: m.markPrice,
+                    nextFundingTime,
+                });
+            }
+            return out;
+        },
+    };
+}

package/dist/funding/normalize.d.ts

@@ -1,26 +1,36 @@
 /**
- * Funding rate normalization.
+ * Funding rate normalization (design §10.1, §10.13 #1).
  *
- * Exchange funding rate periods:
- * - Hyperliquid: per 1 HOUR (settles every 1h)
- * - Pacifica: per 1 HOUR (settles every 1h)
- * - Lighter: per 8 HOURS (API returns 8h rate, settles every 1h)
+ * The number of hours one quoted rate covers (the funding BASIS) comes from the
+ * venue definition — `VenueDefinition.fundingRateBasis`, read through
+ * `fundingBasisOf(ref)`. Settlement timing is a separate concept (arb/utils.ts).
  *
- * HIP-3 deployed dexes on Hyperliquid use 8h funding periods.
- *
- * To compare rates across exchanges, we normalize everything to
- * a per-hour basis, then annualize from there.
+ * A venue ref is a venue id/alias, or "hl:<dex>" for Hyperliquid HIP-3 dexes
+ * (those resolve to the Hyperliquid core basis — current behavior preserved).
+ * Unknown refs throw UNKNOWN_VENUE; per-market venues
+ * have no single hours value — use the market's basis with the `*ByBasis`
+ * variants below.
+ */
+import { type FundingRateBasis } from "../exchanges/venue-types.js";
+/**
+ * Funding basis of a venue ref. Unknown refs (e.g. a stale value in persisted
+ * arb/bot state) surface as UNKNOWN_VENUE with remediation instead of an
+ * anonymous crash deep inside a strategy loop.
  */
+export declare function venueFundingBasis(ref: string): FundingRateBasis;
 /**
- * Get funding period in hours for an exchange.
- * HIP-3 deployed dexes (not in the map) default to 1h (API returns hourly).
- * HL and PAC are 1h, Lighter API returns 8h rates.
+ * Hours one quoted funding rate covers for a venue ref.
+ * Throws INVALID_PARAMS for per-market or annualized venues — use the market's basis.
  */
-export declare function getFundingHours(exchange: string): number;
-/** Convert a raw funding rate to per-hour rate */
-export declare function toHourlyRate(rate: number, exchange: string): number;
+export declare function getFundingHours(ref: string): number;
+/** Convert a raw quoted rate to a per-hour rate using an explicit (market) basis. */
+export declare function toHourlyRateByBasis(rate: number, basis: FundingRateBasis): number;
+/** Convert a raw funding rate to per-hour rate using the venue's basis. */
+export declare function toHourlyRate(rate: number, ref: string): number;
 /** Annualize a raw rate from a specific exchange */
 export declare function annualizeRate(rate: number, exchange: string): number;
+/** Annualize a raw rate quoted on an explicit (market) basis */
+export declare function annualizeRateByBasis(rate: number, basis: FundingRateBasis): number;
 /** Annualize an already-normalized hourly rate (no exchange conversion needed) */
 export declare function annualizeHourlyRate(hourlyRate: number): number;
 /**
@@ -39,9 +49,11 @@ export declare function computeSignedAnnualSpread(shortRate: number, shortExchan
 /**
  * Estimate hourly funding payment for a position.
  * @param rate - raw funding rate from the exchange
- * @param exchange - exchange name
+ * @param exchange - venue ref
  * @param positionUsd - position notional in USD
  * @param side - "long" or "short" (longs pay positive rate, shorts receive)
  * @returns hourly payment in USD (positive = you pay, negative = you receive)
  */
 export declare function estimateHourlyFunding(rate: number, exchange: string, positionUsd: number, side: "long" | "short"): number;
+/** Same as estimateHourlyFunding, from an already-normalized hourly rate. */
+export declare function estimateHourlyFundingFromHourly(hourlyRate: number, positionUsd: number, side: "long" | "short"): number;

package/dist/funding/normalize.js

@@ -1,42 +1,71 @@
 /**
- * Funding rate normalization.
+ * Funding rate normalization (design §10.1, §10.13 #1).
  *
- * Exchange funding rate periods:
- * - Hyperliquid: per 1 HOUR (settles every 1h)
- * - Pacifica: per 1 HOUR (settles every 1h)
- * - Lighter: per 8 HOURS (API returns 8h rate, settles every 1h)
+ * The number of hours one quoted rate covers (the funding BASIS) comes from the
+ * venue definition — `VenueDefinition.fundingRateBasis`, read through
+ * `fundingBasisOf(ref)`. Settlement timing is a separate concept (arb/utils.ts).
  *
- * HIP-3 deployed dexes on Hyperliquid use 8h funding periods.
- *
- * To compare rates across exchanges, we normalize everything to
- * a per-hour basis, then annualize from there.
+ * A venue ref is a venue id/alias, or "hl:<dex>" for Hyperliquid HIP-3 dexes
+ * (those resolve to the Hyperliquid core basis — current behavior preserved).
+ * Unknown refs throw UNKNOWN_VENUE; per-market venues
+ * have no single hours value — use the market's basis with the `*ByBasis`
+ * variants below.
  */
+import { PerpError } from "../errors.js";
+import { fundingBasisOf, parseVenueRef } from "../exchanges/venue.js";
+import { rateToHourly } from "../exchanges/venue-types.js";
+import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 /** Funding periods per year by convention */
 const HOURLY_PERIODS = 24 * 365; // 8760
-/** How many hours each exchange's rate covers */
-const EXCHANGE_FUNDING_HOURS = {
-    hyperliquid: 1,
-    pacifica: 1,
-    lighter: 8,
-    aster: 8,
-};
 /**
- * Get funding period in hours for an exchange.
- * HIP-3 deployed dexes (not in the map) default to 1h (API returns hourly).
- * HL and PAC are 1h, Lighter API returns 8h rates.
+ * Funding basis of a venue ref. Unknown refs (e.g. a stale value in persisted
+ * arb/bot state) surface as UNKNOWN_VENUE with remediation instead of an
+ * anonymous crash deep inside a strategy loop.
+ */
+export function venueFundingBasis(ref) {
+    ensureVenuesRegistered();
+    try {
+        parseVenueRef(ref);
+    }
+    catch (err) {
+        if (err instanceof PerpError && err.structured.code === "UNKNOWN_VENUE") {
+            throw new PerpError("UNKNOWN_VENUE", `Cannot normalize funding for unknown venue reference "${ref}"`, {
+                remediation: "Use a registered venue id (or hl:<dex> for HIP-3). If the value came from persisted state "
+                    + "(~/.perp/arb-state.json or a bot state file), fix or remove that entry.",
+            });
+        }
+        throw err;
+    }
+    return fundingBasisOf(ref);
+}
+/**
+ * Hours one quoted funding rate covers for a venue ref.
+ * Throws INVALID_PARAMS for per-market or annualized venues — use the market's basis.
  */
-export function getFundingHours(exchange) {
-    return EXCHANGE_FUNDING_HOURS[exchange.toLowerCase()] ?? 1;
+export function getFundingHours(ref) {
+    const basis = venueFundingBasis(ref);
+    if (basis.kind !== "perHours") {
+        throw new PerpError("INVALID_PARAMS", `Funding basis of "${ref}" is annualized, not a number of hours`, {
+            remediation: "Use the market's fundingRateBasis with toHourlyRateByBasis()",
+        });
+    }
+    return basis.hours;
 }
-/** Convert a raw funding rate to per-hour rate */
-export function toHourlyRate(rate, exchange) {
-    const hours = EXCHANGE_FUNDING_HOURS[exchange.toLowerCase()] ?? 1;
-    return rate / hours;
+/** Convert a raw quoted rate to a per-hour rate using an explicit (market) basis. */
+export function toHourlyRateByBasis(rate, basis) {
+    return rateToHourly(rate, basis);
+}
+/** Convert a raw funding rate to per-hour rate using the venue's basis. */
+export function toHourlyRate(rate, ref) {
+    return rateToHourly(rate, venueFundingBasis(ref));
 }
 /** Annualize a raw rate from a specific exchange */
 export function annualizeRate(rate, exchange) {
-    const hourlyRate = toHourlyRate(rate, exchange);
-    return hourlyRate * HOURLY_PERIODS * 100; // as percentage
+    return annualizeHourlyRate(toHourlyRate(rate, exchange));
+}
+/** Annualize a raw rate quoted on an explicit (market) basis */
+export function annualizeRateByBasis(rate, basis) {
+    return annualizeHourlyRate(toHourlyRateByBasis(rate, basis));
 }
 /** Annualize an already-normalized hourly rate (no exchange conversion needed) */
 export function annualizeHourlyRate(hourlyRate) {
@@ -66,13 +95,16 @@ export function computeSignedAnnualSpread(shortRate, shortExchange, longRate, lo
 /**
  * Estimate hourly funding payment for a position.
  * @param rate - raw funding rate from the exchange
- * @param exchange - exchange name
+ * @param exchange - venue ref
  * @param positionUsd - position notional in USD
  * @param side - "long" or "short" (longs pay positive rate, shorts receive)
  * @returns hourly payment in USD (positive = you pay, negative = you receive)
  */
 export function estimateHourlyFunding(rate, exchange, positionUsd, side) {
-    const hourlyRate = toHourlyRate(rate, exchange);
+    return estimateHourlyFundingFromHourly(toHourlyRate(rate, exchange), positionUsd, side);
+}
+/** Same as estimateHourlyFunding, from an already-normalized hourly rate. */
+export function estimateHourlyFundingFromHourly(hourlyRate, positionUsd, side) {
     // Long pays positive funding, short receives positive funding
     const multiplier = side === "long" ? 1 : -1;
     return hourlyRate * positionUsd * multiplier;

package/dist/funding/rates.d.ts

@@ -1,22 +1,36 @@
 /**
- * Real-time 3-DEX funding rate comparison.
+ * Real-time cross-venue funding rate comparison.
  *
- * Fetches funding rates from Pacifica, Hyperliquid, and Lighter in parallel,
- * normalizes them to comparable hourly rates, and identifies arbitrage
- * opportunities across exchanges.
+ * Fans out over every venue with the "marketData" role (design §10.6) 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).
+ *
+ * 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 FundingRateBasis, type Network, type VenueId } from "../exchanges/venue-types.js";
 export interface ExchangeFundingRate {
-    exchange: "pacifica" | "hyperliquid" | "lighter" | "aster";
+    exchange: VenueId;
+    /** Venue display symbol (e.g. "kPEPE", "BTC"). */
     symbol: string;
+    /** Cross-venue matching key (canonical-symbols.ts). */
+    canonical: string;
     fundingRate: number;
+    basis: FundingRateBasis;
     hourlyRate: number;
     annualizedPct: number;
     markPrice: number;
-    nextFundingTime?: number;
-    historicalAvg?: HistoricalAverages;
+    nextFundingTime: number | null;
+    historicalAvg: HistoricalAverages | null;
+    /** false = the venue's funding rate is unverified (VenueDefinition.fundingVerified) — shown only on explicit request. */
+    fundingVerified: boolean;
 }
 export interface SymbolFundingComparison {
+    /** Canonical symbol shared by every row. */
     symbol: string;
     rates: ExchangeFundingRate[];
     maxSpreadAnnual: number;
@@ -29,20 +43,38 @@ export interface FundingRateSnapshot {
     timestamp: string;
     symbols: SymbolFundingComparison[];
     exchangeStatus: Record<string, "ok" | "error">;
+    /** Error message per venue whose status is "error" (§10.13 #3). */
+    exchangeErrors: Record<string, string>;
 }
 export declare const TOP_SYMBOLS: string[];
 /**
- * Fetch funding rates from all 3 DEXs in parallel, normalize, and compare.
+ * Fetch every venue in `venues` concurrently; failures land in status/errors.
+ * Venues whose funding is unverified (VenueDefinition.fundingVerified false — QFEX until its
+ * rate unit is confirmed) are DROPPED unless `includeUnverified`: every consumer that ranks,
+ * alerts on or trades funding spreads (arb scan, MCP, alerts, dashboard, portfolio) leaves it
+ * false. Only explicit, labelled reads pass true (`arb scan --include-unverified`).
+ */
+export declare function fetchVenuesRates(venues: VenueDefinition[], net: Network, includeUnverified: boolean): Promise<{
+    rates: ExchangeFundingRate[];
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
+}>;
+/**
+ * Fetch funding rates from every market-data venue in parallel, normalize, and compare.
  * Returns rates sorted by max spread (descending).
+ * @param opts.network defaults to the network the CLI selected (setSharedApiNetwork)
  */
 export declare function fetchAllFundingRates(opts?: {
     symbols?: string[];
     minSpread?: number;
+    network?: Network;
+    /** Also fetch venues whose funding rate is unverified (default false — see fetchVenuesRates). */
+    includeUnverified?: boolean;
 }): Promise<FundingRateSnapshot>;
 /**
- * Fetch rates for a single symbol across all exchanges.
+ * Fetch rates for a single (canonical) symbol across all exchanges.
  */
-export declare function fetchSymbolFundingRates(symbol: string): Promise<SymbolFundingComparison | null>;
+export declare function fetchSymbolFundingRates(symbol: string, includeUnverified?: boolean): Promise<SymbolFundingComparison | null>;
 export interface SpotPerpSpread {
     symbol: string;
     /** Perp exchange with the highest absolute funding rate */
@@ -65,7 +97,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 spot exchange (HL or LT).
+ * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
@@ -75,7 +107,10 @@ export interface SpotPerpSpread {
 export declare function fetchSpotPerpSpreads(opts?: {
     symbols?: string[];
     minSpread?: number;
+    network?: Network;
 }): Promise<{
     timestamp: string;
     spreads: SpotPerpSpread[];
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
 }>;