perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/grvt/public.js

@@ -0,0 +1,438 @@
+/**
+ * GRVT public market data — official Market Data REST API (api-docs.grvt.io/market_data_api/).
+ *
+ * Sources (all `POST https://market-data.grvt.io/full/v1/…`, no key):
+ *   instruments {kind:["PERPETUAL"], is_active:true, limit}  directory: instrument "BTC_USDT_Perp",
+ *        base, quote, kind, settlement_period, tick_size, min_size, min_notional,
+ *        funding_interval_hours (4 or 8, PER INSTRUMENT), asset_class (CRYPTO / EQUITY / COMMODITY),
+ *        status. No leverage and no lot step (base_decimals is the signing multiplier, not a lot).
+ *   ticker {instrument}       one instrument per call (no bulk ticker exists): mark / index / last /
+ *        best bid / best ask prices, open_interest (base), buy/sell_volume_24h_q (quote = USDT),
+ *        funding_rate, next_funding_time (ns).
+ *   margin_rules {instrument} risk_brackets → max_leverage of tier 1 (= maxLeverage) and the tiers.
+ *
+ * Mapping:
+ *  - symbol = `base` ("BTC", "KPEPE"); venueSymbol = instrument ("BTC_USDT_Perp"); canonical via
+ *    canonical-symbols.ts (crypto by ticker + denomination aliases, equity / etf by ticker,
+ *    commodity explicit only). Pre-IPO markets (listed by GRVT as EQUITY) are preIpo → no canonical.
+ *  - funding: `funding_rate` is the venue's INDICATIVE rate for the active interval (the interval
+ *    ending at next_funding_time) — kind "predicted", a moving estimate. Its unit is PERCENT per the
+ *    market's funding interval: settled history (/full/v1/funding, "percentage points") prints the
+ *    same magnitude (BTC 0.01 = HL-style 0.01 %/8 h baseline; ticker 0.0063). The ticker schema says
+ *    "centibeeps", which would make every rate 100× smaller than its own settled prints — not used.
+ *    Converted to a fraction per interval by an exact × 0.01; basis perHours = funding_interval_hours.
+ *  - volume24h = buy + sell 24 h quote volume (the docs' "24 hour volume"), exact decimal sum.
+ *  - unknown / absent values are null; a ticker without a mark price, or whose read fails, drops
+ *    that market (warned by name).
+ *  - request budget: the registry path (fetchMarkets / fetchFundingRates) is price-only
+ *    (instruments + one ticker per market, both reused in-process for 15 s); margin_rules (leverage)
+ *    only for `market list` / `info`, file-cached 6 h per network.
+ */
+import { getCached, invalidateCache, setCached } from "../../cache.js";
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { canonicalFor } from "../canonical-symbols.js";
+import { addDecimal, mulDecimal } from "../precision.js";
+import { symbolNotFound } from "../unknown-symbol.js";
+import { networkConfig } from "../venue.js";
+import { grvtVenue } from "../venues/grvt.js";
+import { grvtShapeError, GrvtClient } from "./client.js";
+/** Requests in flight at once for the per-instrument fan-out (ticker / margin_rules). */
+export const GRVT_FANOUT_CONCURRENCY = 8;
+/** In-process reuse of the directory and of each ticker (repeated MCP / dashboard reads). */
+export const GRVT_SHORT_TTL_MS = 15_000;
+/** margin_rules brackets change rarely: file cache (src/cache.ts), per network. */
+export const GRVT_MARGIN_TTL_MS = 6 * 3_600_000;
+/**
+ * GRVT EQUITY markets that may match other venues by ticker identity: exchange-listed shares and
+ * ETFs (or, for Korean / HK listings, the plain company name every venue uses). Reviewed against
+ * the live list 2026-10-19. Any other EQUITY market is explicit-only (canonical null) — a new
+ * pre-IPO or synthetic listing is never matched by a look-alike ticker.
+ */
+const MATCHABLE_EQUITY = new Set([
+    "AAOI", "AAPL", "AMAT", "AMD", "AMZN", "ARM", "ASML", "ASTS", "AVGO", "AXTI", "BABA", "BE", "BMNR", "BX", "COHR", "COIN",
+    "CRCL", "CRDO", "CRM", "CRWD", "CRWV", "CSCO", "DELL", "DIS", "FLNC", "GLW", "GOOGL", "GS", "HANMI", "HD", "HOOD", "HYUNDAI",
+    "IBM", "INTC", "IREN", "JPM", "LGELECTRONICS", "LITE", "LLY", "META", "MINIMAX", "MRNA", "MRVL", "MSFT", "MSTR", "MU", "NAVER",
+    "NBIS", "NFLX", "NOK", "NOW", "NVDA", "NVO", "ONDS", "ORCL", "PLTR", "QCOM", "RKLB", "SAMSUNG", "SKHYNIX", "SMCI", "SNDK",
+    "STRC", "TSLA", "TSM", "UBER", "USAR", "V", "WDC", "WMT",
+]);
+/** Exchange-traded funds among GRVT's EQUITY markets (matchable by ticker, labelled etf). */
+const ETF = new Set([
+    "SPY", "QQQ", "IWM", "EWJ", "EWT", "EWY", "EWZ", "SOXL", "TQQQ", "SQQQ", "UVXY", "URNM", "XLE", "KORU", "KODEX200",
+]);
+/** Pre-IPO private companies GRVT lists as EQUITY (a private valuation, not a listed share). */
+const PRE_IPO = new Set(["ANTHROPIC", "OPENAI", "SPACEX"]);
+/**
+ * Reviewed EQUITY markets that stay explicit-only without a warning: tickers that are not a plain
+ * exchange ticker or are ambiguous across venues (BRKB vs BRK.B, SKHY next to SKHYNIX, SAMSUNGEM,
+ * DRAM, …). Unreviewed tickers are explicit-only too, but warned once per process.
+ */
+const EXPLICIT_ONLY_EQUITY = new Set([
+    "BBX", "BRKB", "CBRS", "DRAM", "KSTR", "PAYP", "QNTX", "SAMSUNGEM", "SKHY", "STXX",
+]);
+const warnedUnreviewed = new Set();
+const DEC = /^-?\d+(\.\d+)?$/;
+function decOrNull(v) {
+    return typeof v === "string" && DEC.test(v) ? v : null;
+}
+function positiveDec(v, what) {
+    if (typeof v !== "string" || !/^\d+(\.\d+)?$/.test(v) || !(Number(v) > 0))
+        throw grvtShapeError(`${what} is not a positive decimal`);
+    return v;
+}
+function assetClassOf(symbol, raw) {
+    switch (raw) {
+        case "CRYPTO": return "crypto";
+        case "COMMODITY": return "commodity";
+        case "EQUITY": return PRE_IPO.has(symbol) ? "preIpo" : ETF.has(symbol) ? "etf" : "equity";
+        default: return null;
+    }
+}
+/**
+ * Cross-venue key: crypto / commodity / preIpo through canonical-symbols.ts; an equity / etf only
+ * when whitelisted (MATCHABLE_EQUITY / ETF), else null — warned once when not reviewed at all.
+ */
+export function grvtCanonicalOf(symbol, assetClass, warn) {
+    if (assetClass !== "equity" && assetClass !== "etf")
+        return canonicalFor("grvt", symbol, assetClass);
+    if (MATCHABLE_EQUITY.has(symbol) || ETF.has(symbol))
+        return canonicalFor("grvt", symbol, assetClass);
+    if (!EXPLICIT_ONLY_EQUITY.has(symbol) && !warnedUnreviewed.has(symbol)) {
+        warnedUnreviewed.add(symbol);
+        warn(`[grvt] ${symbol}: equity market not yet reviewed for cross-venue matching — not matched (canonical null)`);
+    }
+    return null;
+}
+/**
+ * Parse one instruments row. Returns null for a row that is not a listed perpetual (another kind,
+ * an expiring settlement period); shape drift on a perpetual row is EXCHANGE_ERROR.
+ */
+export function toGrvtMarketMeta(raw, warn) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw grvtShapeError("instruments row is not an object");
+    const r = raw;
+    if (r.kind !== "PERPETUAL" || r.settlement_period !== "PERPETUAL")
+        return null;
+    if (typeof r.instrument !== "string" || typeof r.base !== "string" || r.base === "" || typeof r.quote !== "string") {
+        throw grvtShapeError(`instrument row ${String(r.instrument)} has no instrument / base / quote`);
+    }
+    const symbol = r.base.toUpperCase();
+    const assetClass = assetClassOf(symbol, r.asset_class);
+    if (assetClass === null) {
+        warn(`[grvt] skipped ${r.instrument}: unknown asset_class "${String(r.asset_class)}"`);
+        return null;
+    }
+    const fi = r.funding_interval_hours;
+    if (typeof fi !== "number" || !Number.isInteger(fi) || fi <= 0)
+        throw grvtShapeError(`${r.instrument} funding_interval_hours ${String(fi)} is not a positive integer`);
+    return {
+        instrument: r.instrument,
+        symbol,
+        quote: r.quote,
+        tickSize: positiveDec(r.tick_size, `${r.instrument} tick_size`),
+        minSize: positiveDec(r.min_size, `${r.instrument} min_size`),
+        minNotional: decOrNull(r.min_notional),
+        fundingIntervalHours: fi,
+        assetClass,
+        canonical: grvtCanonicalOf(symbol, assetClass, warn),
+        tradable: r.status === "ACTIVE",
+    };
+}
+export async function fetchGrvtDirectory(client, warn) {
+    const rows = await client.result("instruments", { kind: ["PERPETUAL"], is_active: true, limit: 100000 });
+    if (!Array.isArray(rows))
+        throw grvtShapeError("instruments result is not an array");
+    const out = [];
+    const seen = new Set();
+    for (const row of rows) {
+        const m = toGrvtMarketMeta(row, warn);
+        if (m === null)
+            continue;
+        if (seen.has(m.symbol))
+            throw grvtShapeError(`instruments list ${m.symbol} twice`);
+        seen.add(m.symbol);
+        out.push(m);
+    }
+    return out;
+}
+/** Resolve a CLI symbol ("btc", "BTC-PERP", "BTC_USDT_Perp", "BTC-USDT") against the directory. */
+export function resolveGrvtMarket(dir, input) {
+    const up = input.trim().toUpperCase().replace(/-PERP$/, "").replace(/_PERP$/, "").replace(/[-_/]USDT$/, "");
+    const hit = dir.find(m => m.symbol === up);
+    if (hit === undefined)
+        throw symbolNotFound("grvt", input);
+    return hit;
+}
+function nsToMsOrNull(v) {
+    if (typeof v !== "string" || !/^\d+$/.test(v))
+        return null;
+    const ms = Number(BigInt(v) / 1000000n);
+    return ms > 0 ? ms : null;
+}
+export function toGrvtTicker(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw grvtShapeError("ticker result is not an object");
+    const r = raw;
+    const bv = decOrNull(r.buy_volume_24h_q);
+    const sv = decOrNull(r.sell_volume_24h_q);
+    return {
+        markPrice: decOrNull(r.mark_price),
+        indexPrice: decOrNull(r.index_price),
+        lastPrice: decOrNull(r.last_price),
+        bestBid: decOrNull(r.best_bid_price),
+        bestAsk: decOrNull(r.best_ask_price),
+        openInterest: decOrNull(r.open_interest),
+        volume24hQuote: bv !== null && sv !== null ? addDecimal(bv, sv) : null,
+        fundingPct: decOrNull(r.funding_rate),
+        nextFundingTime: nsToMsOrNull(r.next_funding_time),
+    };
+}
+/** Percent → fraction, exactly ("0.0063" → "0.000063"); null stays null (unknown, never 0). */
+export function grvtPercentToFraction(pct) {
+    return pct === null ? null : mulDecimal(pct, "0.01");
+}
+export function grvtFundingBasis(m) {
+    return { kind: "perHours", hours: m.fundingIntervalHours };
+}
+/** risk_brackets → tier-1 max leverage and the notional tiers (ascending); null when unpublished. */
+export function toGrvtLeverage(raw) {
+    const brackets = raw?.risk_brackets;
+    if (!Array.isArray(brackets) || brackets.length === 0)
+        return null;
+    const tiers = [];
+    for (const b of brackets) {
+        const x = b;
+        const floor = decOrNull(x.notional_floor);
+        if (floor === null || typeof x.max_leverage !== "number" || !Number.isInteger(x.max_leverage) || x.max_leverage <= 0)
+            return null;
+        tiers.push({ lowerBound: Number(floor), maxLeverage: x.max_leverage });
+    }
+    tiers.sort((a, b) => a.lowerBound - b.lowerBound);
+    return { maxLeverage: tiers[0].maxLeverage, tiers };
+}
+function isRateLimited(e) {
+    return e instanceof PerpError && e.structured.code === "RATE_LIMITED";
+}
+/**
+ * Run `fn` over `items` with `limit` in flight; each item settles on its own. RATE_LIMITED stops
+ * every worker (nothing new is sent) and is re-thrown — the venue told us to back off.
+ */
+export async function settleEach(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    let rateLimited = null;
+    const worker = async () => {
+        while (rateLimited === null && next < items.length) {
+            const i = next++;
+            try {
+                out[i] = { ok: true, value: await fn(items[i]) };
+            }
+            catch (e) {
+                if (isRateLimited(e)) {
+                    rateLimited = e;
+                    return;
+                }
+                out[i] = { ok: false, error: e };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    if (rateLimited !== null)
+        throw rateLimited;
+    return out;
+}
+function failureList(names, errors) {
+    return names.map((n, i) => `${n} (${extractErrorMessage(errors[i])})`).join(", ");
+}
+export function fetchGrvtTicker(client, instrument) {
+    return client.result("ticker", { instrument }).then(toGrvtTicker);
+}
+export function fetchGrvtLeverage(client, instrument) {
+    return client.post("margin_rules", { instrument }).then(toGrvtLeverage);
+}
+// ── Caches ──
+const dirCache = new Map();
+const tickerCache = new Map();
+const marginCacheKey = (net) => `grvt-margin-rules-${net}`;
+/** Drop every GRVT cache (in-process directory / tickers and the margin-rules file cache). */
+export function clearGrvtCaches() {
+    dirCache.clear();
+    tickerCache.clear();
+    invalidateCache("grvt-");
+}
+/** The directory, reused for GRVT_SHORT_TTL_MS; a failed read is not kept. */
+export function grvtDirectory(client, net, warn) {
+    const hit = dirCache.get(net);
+    if (hit !== undefined && Date.now() - hit.at < GRVT_SHORT_TTL_MS)
+        return hit.value;
+    const value = fetchGrvtDirectory(client, warn);
+    dirCache.set(net, { at: Date.now(), value });
+    value.catch(() => { if (dirCache.get(net)?.value === value)
+        dirCache.delete(net); });
+    return value;
+}
+/** One ticker, reused for GRVT_SHORT_TTL_MS. */
+export async function grvtTicker(client, net, instrument) {
+    const key = `${net}|${instrument}`;
+    const hit = tickerCache.get(key);
+    if (hit !== undefined && Date.now() - hit.at < GRVT_SHORT_TTL_MS)
+        return hit.value;
+    const value = await fetchGrvtTicker(client, instrument);
+    tickerCache.set(key, { at: Date.now(), value });
+    return value;
+}
+function isEntry(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const e = v;
+    return typeof e.fetchedAt === "number" && Number.isFinite(e.fetchedAt) && (e.leverage === null || (typeof e.leverage === "object" && e.leverage !== undefined));
+}
+/**
+ * Leverage per instrument from the margin-rules file cache (JSON: instrument → {fetchedAt, leverage}).
+ * Each entry expires on its own GRVT_MARGIN_TTL_MS after ITS read (rewriting the file never extends
+ * an old entry); expired, malformed and missing instruments are read again. A failed read leaves
+ * that market's leverage unknown (null entry, warned, not cached).
+ */
+export async function grvtLeverageFor(client, net, instruments, warn) {
+    const now = Date.now();
+    const stored = getCached(marginCacheKey(net)) ?? {};
+    const cache = {};
+    for (const [inst, e] of Object.entries(stored)) {
+        if (isEntry(e) && e.fetchedAt <= now && now - e.fetchedAt < GRVT_MARGIN_TTL_MS)
+            cache[inst] = e;
+    }
+    const missing = instruments.filter(i => !(i in cache));
+    if (missing.length > 0) {
+        const settled = await settleEach(missing, GRVT_FANOUT_CONCURRENCY, i => fetchGrvtLeverage(client, i));
+        const failed = [];
+        const errors = [];
+        settled.forEach((r, k) => {
+            if (r.ok)
+                cache[missing[k]] = { fetchedAt: Date.now(), leverage: r.value };
+            else {
+                failed.push(missing[k]);
+                errors.push(r.error);
+            }
+        });
+        if (failed.length > 0)
+            warn(`[grvt] margin rules unreadable for ${failed.length} market(s) — max leverage unknown: ${failureList(failed, errors)}`);
+        // The file outlives every entry in it (each is younger than the TTL); entries expire by fetchedAt.
+        setCached(marginCacheKey(net), cache, GRVT_MARGIN_TTL_MS);
+    }
+    return Object.fromEntries(instruments.map(i => [i, i in cache ? cache[i] : null]));
+}
+export function toGrvtVenueMarket(m, t, entry) {
+    const lev = entry === null ? null : entry.leverage;
+    return {
+        venue: "grvt",
+        venueSymbol: m.instrument,
+        symbol: m.symbol,
+        canonical: m.canonical,
+        assetClass: m.assetClass,
+        settle: "USDT",
+        quoteAsset: m.quote,
+        markPrice: t.markPrice,
+        indexPrice: t.indexPrice,
+        fundingRate: grvtPercentToFraction(t.fundingPct),
+        fundingRateBasis: grvtFundingBasis(m),
+        settlementIntervalHours: m.fundingIntervalHours,
+        openInterest: t.openInterest,
+        volume24h: t.volume24hQuote,
+        tickSize: m.tickSize,
+        // No lot step is published (min_size is the minimum, base_decimals the signing multiplier).
+        stepSize: null,
+        minSize: m.minSize,
+        minNotional: m.minNotional,
+        maxLeverage: lev === null ? null : lev.maxLeverage,
+        marginTiers: lev === null ? null : lev.tiers,
+        leverageAsOf: entry === null ? null : new Date(entry.fetchedAt).toISOString(),
+        // Not mapped: the ticker's `session` ("REGULAR" on every market, 2026-10-19) is not in GRVT's
+        // documented schema and its other values / their meaning (open hours, price bands) are unknown.
+        session: null,
+        tradable: m.tradable,
+        lastPrice: t.lastPrice,
+        bestBid: t.bestBid,
+        bestAsk: t.bestAsk,
+        nextFundingTime: t.nextFundingTime,
+    };
+}
+const DEFAULT_DEPS = { warn: msg => process.stderr.write(`${msg}\n`) };
+export function grvtClient(net) {
+    return new GrvtClient(networkConfig(grvtVenue, net).restUrl, net);
+}
+function priced(meta, t) {
+    return t.markPrice !== null && Number(t.markPrice) > 0 ? { meta, ticker: { ...t, markPrice: t.markPrice } } : null;
+}
+/**
+ * Directory + one ticker per market. A market whose ticker read fails, or has no mark price, is
+ * dropped with a warning naming it; the venue fails only when every ticker read fails (or on
+ * RATE_LIMITED).
+ */
+async function fetchPriced(client, net, deps) {
+    const dir = await grvtDirectory(client, net, deps.warn);
+    const settled = await settleEach(dir, GRVT_FANOUT_CONCURRENCY, m => grvtTicker(client, net, m.instrument));
+    const out = [];
+    const unpriced = [];
+    const failed = [];
+    const errors = [];
+    dir.forEach((meta, i) => {
+        const r = settled[i];
+        if (!r.ok) {
+            failed.push(meta.symbol);
+            errors.push(r.error);
+            return;
+        }
+        const p = priced(meta, r.value);
+        if (p === null)
+            unpriced.push(meta.symbol);
+        else
+            out.push(p);
+    });
+    if (dir.length > 0 && failed.length === dir.length)
+        throw errors[0];
+    if (failed.length > 0)
+        deps.warn(`[grvt] ${failed.length} market(s) whose ticker could not be read are not shown: ${failureList(failed, errors)}`);
+    if (unpriced.length > 0)
+        deps.warn(`[grvt] ${unpriced.length} market(s) without a mark price are not shown: ${unpriced.join(", ")}`);
+    return out;
+}
+export async function fetchGrvtMarkets(net, opts, deps = DEFAULT_DEPS) {
+    const client = grvtClient(net);
+    const rows = await fetchPriced(client, net, deps);
+    const lev = opts.leverage ? await grvtLeverageFor(client, net, rows.map(p => p.meta.instrument), deps.warn) : null;
+    return rows.map(p => toGrvtVenueMarket(p.meta, p.ticker, lev === null ? null : lev[p.meta.instrument]));
+}
+/** One market: directory (cached) + its ticker + its margin rules — no fan-out. */
+export async function fetchGrvtMarket(net, symbol, deps = DEFAULT_DEPS) {
+    const client = grvtClient(net);
+    const meta = resolveGrvtMarket(await grvtDirectory(client, net, deps.warn), symbol);
+    const p = priced(meta, await grvtTicker(client, net, meta.instrument));
+    if (p === null)
+        throw grvtShapeError(`${meta.instrument} ticker has no mark price`);
+    const lev = await grvtLeverageFor(client, net, [meta.instrument], deps.warn);
+    return toGrvtVenueMarket(p.meta, p.ticker, lev[meta.instrument]);
+}
+/** Funding rows (tickers only — no margin_rules): fraction per the market's own interval. */
+export async function fetchGrvtFundingRates(net, deps = DEFAULT_DEPS) {
+    const out = [];
+    for (const { meta, ticker } of await fetchPriced(grvtClient(net), net, deps)) {
+        const rate = grvtPercentToFraction(ticker.fundingPct);
+        if (rate === null)
+            continue;
+        out.push({
+            venue: "grvt",
+            venueSymbol: meta.instrument,
+            symbol: meta.symbol,
+            canonical: meta.canonical,
+            rate,
+            basis: grvtFundingBasis(meta),
+            markPrice: ticker.markPrice,
+            nextFundingTime: ticker.nextFundingTime,
+        });
+    }
+    return out;
+}
+/** The registry's public data path (MCP get_prices / get_markets, market://prices, arb, dashboards): price-only. */
+export const grvtPublicData = {
+    fetchMarkets: net => fetchGrvtMarkets(net, { leverage: false }),
+    fetchFundingRates: net => fetchGrvtFundingRates(net),
+};

package/dist/exchanges/hyperliquid-outcome.d.ts

@@ -15,6 +15,8 @@
  */
 import type { OutcomeAdapter, OutcomeMarketInfo, OutcomeOrderbook, OutcomePosition, OutcomeView, OutcomeViewUnderlying } from "./outcome-interface.js";
 import type { HyperliquidAdapter } from "./hyperliquid.js";
+/** Bid–ask width (probability points) above which a side's mid-implied probability is flagged. */
+export declare const OUTCOME_WIDE_SPREAD = 0.2;
 export declare class HyperliquidOutcomeAdapter implements OutcomeAdapter {
     readonly name = "hyperliquid";
     private _hl;

package/dist/exchanges/hyperliquid-outcome.js

@@ -22,6 +22,16 @@ const MIN_ORDER_QUOTE = 10;
 const MAX_SIDE = 9;
 /** Asset id offset spans `[100_000_000, 200_000_000)`, so encoding < 100M. */
 const MAX_ENCODING = 99_999_999;
+/** A numeric description field; a malformed one is left unset (unknown) with a warning, never NaN. */
+function finiteOrWarn(val, key, description) {
+    const n = val.trim() === "" ? NaN : Number(val);
+    if (Number.isFinite(n))
+        return n;
+    process.stderr.write(`[hyperliquid] outcome description ${key} "${val}" is not a number — target price unknown (${description.slice(0, 120)})\n`);
+    return undefined;
+}
+/** Bid–ask width (probability points) above which a side's mid-implied probability is flagged. */
+export const OUTCOME_WIDE_SPREAD = 0.2;
 export class HyperliquidOutcomeAdapter {
     name = "hyperliquid";
     _hl;
@@ -76,9 +86,17 @@ export class HyperliquidOutcomeAdapter {
             else if (key === "expiry")
                 out.expiryMs = HyperliquidOutcomeAdapter._parseExpiry(val);
             else if (key === "targetPrice")
-                out.targetPrice = Number(val);
+                out.targetPrice = finiteOrWarn(val, key, description);
             else if (key === "period")
                 out.period = val;
+            // Template outcomes (name "template:binaryPrice", live 2026-10-19):
+            // "perp:ZEC|priceDescription:…|seconds:90|threshold:1057|time:20261023-0800".
+            else if (key === "perp" && out.underlying === undefined)
+                out.underlying = val;
+            else if (key === "threshold" && out.targetPrice === undefined)
+                out.targetPrice = finiteOrWarn(val, key, description);
+            else if (key === "time" && out.expiryMs === undefined)
+                out.expiryMs = HyperliquidOutcomeAdapter._parseExpiry(val);
         }
         return out;
     }
@@ -315,6 +333,9 @@ export class HyperliquidOutcomeAdapter {
             });
         }
         const parsed = HyperliquidOutcomeAdapter.parseDescription(meta.description);
+        // A template binary-price outcome is a price binary (Yes = underlying ≥ threshold at `time`).
+        if (parsed.class === undefined && meta.name === "template:binaryPrice")
+            parsed.class = "priceBinary";
         // Fetch books for every side in parallel + allMids once for mids and
         // the underlying symbol's mark price.
         const allMidsPromise = this._infoPost({ type: "allMids" });
@@ -336,6 +357,13 @@ export class HyperliquidOutcomeAdapter {
                 bestBid: trimmed.bestBid,
                 bestAsk: trimmed.bestAsk,
                 impliedProb: mid !== undefined ? Number(mid) : undefined,
+                // Template side names ("template:Yes") without the prefix; `name` stays as published.
+                label: spec.name.replace(/^template:/, ""),
+                // The mid of a book wider than OUTCOME_WIDE_SPREAD (e.g. 0.0257 / 0.9899) says little
+                // about the probability: flagged, never dropped.
+                wideSpread: trimmed.bestBid !== undefined && trimmed.bestAsk !== undefined
+                    ? Number(trimmed.bestAsk) - Number(trimmed.bestBid) > OUTCOME_WIDE_SPREAD
+                    : null,
             };
         });
         const midSum = HyperliquidOutcomeAdapter._computeMidSum(sides);

package/dist/exchanges/hyperliquid-spot.d.ts

@@ -9,6 +9,14 @@
 import type { SpotAdapter, SpotMarketInfo, SpotBalance, SpotHoldingPrice, SpotHoldingPricesCapable } from "./spot-interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { HyperliquidAdapter } from "./hyperliquid.js";
+import { type HlAbstractionMode } from "./hyperliquid.js";
+/**
+ * Spot balances from info `spotClearinghouseState` — the one mapper behind the keyed spot adapter
+ * and the keyless `account balance --address`. `shared` (already counted in the perp equity) follows
+ * the account mode: unified → the USDC row; portfolio margin → USDC and every eligible collateral row
+ * (the venue marks those with `ltv`); any other mode, or `null` (a HIP-3 dex scope / mode unknown) → none.
+ */
+export declare function hlSpotBalanceRows(state: Record<string, unknown>, mode: HlAbstractionMode | null): SpotBalance[];
 export declare class HyperliquidSpotAdapter implements SpotAdapter, SpotHoldingPricesCapable {
     readonly name = "hyperliquid";
     private _hl;
@@ -74,7 +82,7 @@ export declare class HyperliquidSpotAdapter implements SpotAdapter, SpotHoldingP
      * `usdClassTransfer`. No signer → NO_SIGNER_AVAILABLE from the adapter.
      */
     private _moveUsdc;
-    /** SpotTransferCapable (§12.4 #4): USDC only; an `err` response is thrown, not returned. */
+    /** SpotTransferCapable: USDC only; an `err` response is thrown, not returned. */
     transferToSpot(amount: string, asset: string): Promise<unknown>;
     transferToPerp(amount: string, asset: string): Promise<unknown>;
     private _checkedTransfer;

package/dist/exchanges/hyperliquid-spot.js

@@ -16,6 +16,24 @@ import { invalidateCache } from "../cache.js";
 function hlRoundSize(size, szDecimals) {
     return floorSize(size, hlSizeStep(szDecimals));
 }
+/**
+ * Spot balances from info `spotClearinghouseState` — the one mapper behind the keyed spot adapter
+ * and the keyless `account balance --address`. `shared` (already counted in the perp equity) follows
+ * the account mode: unified → the USDC row; portfolio margin → USDC and every eligible collateral row
+ * (the venue marks those with `ltv`); any other mode, or `null` (a HIP-3 dex scope / mode unknown) → none.
+ */
+export function hlSpotBalanceRows(state, mode) {
+    const balances = (state?.balances ?? []);
+    return balances.map((b) => ({
+        token: String(b.coin ?? ""),
+        total: String(b.total ?? "0"),
+        available: String(Number(b.total ?? 0) - Number(b.hold ?? 0)),
+        held: String(b.hold ?? "0"),
+        entryNtl: b.entryNtl !== undefined ? String(b.entryNtl) : undefined,
+        shared: (mode === "unified" || mode === "portfolio") && String(b.coin ?? "") === "USDC"
+            || mode === "portfolio" && Object.prototype.hasOwnProperty.call(b, "ltv"),
+    }));
+}
 export class HyperliquidSpotAdapter {
     name = "hyperliquid";
     _hl;
@@ -181,18 +199,8 @@ export class HyperliquidSpotAdapter {
         // in the funding-arb bot (and a misleading empty holdings table).
         // Reuse cached spot clearinghouse state (shared with getBalance() — saves 1 API call).
         const state = await this._hl._getSpotClearinghouseState({ fresh });
-        const balances = (state?.balances ?? []);
-        // Unified HL accounts: spot USDC IS the perp margin (§12.4 #8) — mark it shared.
-        // HIP-3 dex-scoped adapters report dex equity, which never contains spot USDC.
-        const unified = this._hl.isUnifiedAccount === true && this._hl.dex === "";
-        return balances.map((b) => ({
-            token: String(b.coin ?? ""),
-            total: String(b.total ?? "0"),
-            available: String(Number(b.total ?? 0) - Number(b.hold ?? 0)),
-            held: String(b.hold ?? "0"),
-            entryNtl: b.entryNtl !== undefined ? String(b.entryNtl) : undefined,
-            shared: unified && String(b.coin ?? "") === "USDC",
-        }));
+        // HIP-3 dex-scoped adapters report dex equity, which never contains spot balances.
+        return hlSpotBalanceRows(state, this._hl.dex === "" ? this._hl.accountMode : null);
     }
     async spotMarketOrder(symbol, side, size, opts) {
         const what = `spot ${side} ${size} ${symbol}`;
@@ -204,7 +212,7 @@ export class HyperliquidSpotAdapter {
             await this.init();
             const resolved = this._resolveBase(symbol);
             base = resolved.base;
-            // Reference = l2Book mid (the same single declared source as HL perps, §13.10 #5).
+            // Reference = l2Book mid (the same single declared source as HL perps).
             // Either side missing → PRICE_STALE (no one-sided "mid").
             const book = await this.getSpotOrderbook(symbol);
             const bestAsk = Number(book.asks[0]?.[0]);
@@ -213,7 +221,7 @@ export class HyperliquidSpotAdapter {
                 throw new PerpError("PRICE_STALE", `Hyperliquid spot ${base}: no two-sided l2Book to derive the mid reference price`, { exchange: "hyperliquid" });
             }
             const midPrice = (bestAsk + bestBid) / 2;
-            // Protection = mid ± the resolved slippage bound (design §13.2), aligned toward
+            // Protection = mid ± the resolved slippage bound, aligned toward
             // crossing on HL's spot grid (5 sig figs, max 8 − szDecimals decimals).
             const isBuy = side === "buy";
             const szDec = this.getSpotDecimals(base).size;
@@ -254,7 +262,7 @@ export class HyperliquidSpotAdapter {
         await this.init();
         const { base, spotIndex } = this._resolveBase(symbol);
         const assetIndex = 10000 + spotIndex;
-        // TIF aliases (§13.3): GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
+        // TIF aliases: GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
         const tif = hlTif(opts?.tif ?? "GTC");
         const szDec = this.getSpotDecimals(base).size;
         const what = `spot limit ${side} ${size} ${base} @ ${price}`;
@@ -388,7 +396,7 @@ export class HyperliquidSpotAdapter {
             invalidateCache("acct"); // perp and spot balances both moved
         }
     }
-    /** SpotTransferCapable (§12.4 #4): USDC only; an `err` response is thrown, not returned. */
+    /** SpotTransferCapable: USDC only; an `err` response is thrown, not returned. */
     async transferToSpot(amount, asset) {
         return this._checkedTransfer(amount, asset, false);
     }