perp-cli 0.14.2 → 0.15.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-spot.d.ts

@@ -74,7 +74,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

@@ -182,7 +182,7 @@ export class HyperliquidSpotAdapter {
         // 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.
+        // Unified HL accounts: spot USDC IS the perp margin — 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) => ({
@@ -204,7 +204,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 +213,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 +254,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 +388,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);
     }

package/dist/exchanges/hyperliquid.d.ts

@@ -1,4 +1,4 @@
-import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
@@ -6,15 +6,15 @@ import { type BuilderApproval, type BuilderDecision, type BuilderFeeGate, type B
 /** HL native time-in-force values. */
 export type HlTif = "Gtc" | "Ioc" | "Alo";
 /**
- * Map a TIF input to HL's native value (design §13.3). Accepts the common names
+ * Map a TIF input to HL's native value. Accepts the common names
  * GTC/IOC/ALO and the native spellings case-insensitively. FOK is not offered by
- * HL (no FOK emulation, §13.3) → CAPABILITY_UNSUPPORTED; anything else likewise.
+ * HL (no FOK emulation) → CAPABILITY_UNSUPPORTED; anything else likewise.
  */
 export declare function hlTif(raw: string): HlTif;
 /** HL lot step implied by szDecimals ("1" for 0, "0.001" for 3) — sizes are floored to it (floorSize). */
 export declare function hlSizeStep(szDecimals: number): string;
 /**
- * Slippage-bounded IOC protection price (design §13.2, §13.10 #5).
+ * Slippage-bounded IOC protection price.
  *
  * `reference` × (1 ± bps/10000), then aligned TOWARD CROSSING (buy → up, sell →
  * down) on HL's price grid: at most 5 significant figures and at most
@@ -29,8 +29,8 @@ export declare function hlProtectionPrice(reference: number, side: "buy" | "sell
     appliedBps: number;
 };
 /**
- * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid (design §10.10:
- * an off-grid limit price is refused, never rounded — rounding to nearest can move a buy price UP).
+ * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid:
+ * an off-grid limit price is refused, never rounded — rounding to nearest can move a buy price UP.
  * HL docs (trading/tick-and-lot-size): "Prices can have up to 5 significant figures, but no more
  * than MAX_DECIMALS - szDecimals decimal places where MAX_DECIMALS is 6 for perps and 8 for spot.
  * Integer prices are always allowed, regardless of the number of significant figures."
@@ -59,7 +59,7 @@ export declare function hlAlignPriceToGrid(price: string, szDecimals: number, ma
 export declare function assertHlAppliedBps(appliedBps: number, what: string): Promise<void>;
 /**
  * Definite IOC outcome of a raw HL `order` response (shared contract with the
- * perp-order lane, design §13.10 #4). Reads `response.data.statuses[0]`:
+ * perp-order lane). Reads `response.data.statuses[0]`:
  * - `{ filled: { totalSz } }` with a plain decimal totalSz → that size, final;
  * - `{ error }` that is HL's IOC no-match cancel ("could not immediately match")
  *   → the venue explicitly cancelled the IOC with nothing filled → "0", final;
@@ -269,7 +269,17 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     /** Lot step of a market from the loaded `meta` szDecimals (precision.lotStepOf) — no metaAndAssetCtxs / allMids read per order. */
     lotStepOf(symbol: string): string;
     getAssetIndex(symbol: string): Promise<number>;
+    /** SYMBOL_NOT_FOUND for a coin the venue does not list (on this adapter's dex), with the listing command. */
+    private _unknownSymbol;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
+    /** Display names of the delisted assets seen by the last getMarkets() (meta isDelisted). */
+    private _delisted;
+    /**
+     * Why `symbol` is not in getMarkets(): it is delisted (message), or null when it is not a
+     * delisted asset. Read after getMarkets(). `market info` uses it to say "delisted" rather than
+     * "not found" — the asset map still resolves it for orders / positions / history.
+     */
+    delistedMessage(symbol: string): string | null;
     getOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
@@ -367,11 +377,11 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      */
     private _validateOrderFill;
     /**
-     * Market order = slippage-bounded IOC limit (design §13.2, §13.10 #1/#5) for
+     * Market order = slippage-bounded IOC limit for
      * native perps and HIP-3 dexes alike. Replaces the SDK's marketOpen/marketClose
      * (hidden built-in slippage) and the former HIP-3 5% constant.
      *
-     * Reference price (the single declared source, §13.10 #5): the l2Book mid
+     * Reference price (the single declared source): the l2Book mid
      * (best bid + best ask) / 2 of this coin — see referencePrice(). No runtime
      * substitute (mark, allMids, last trade): a missing side → PRICE_STALE before
      * anything is sent. Protection = reference ± opts.slippage.bps, aligned toward
@@ -483,7 +493,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     cancelOrder(symbol: string, orderId: string): Promise<unknown>;
     cancelAllOrders(symbol?: string): Promise<unknown[]>;
     /**
-     * Amend (design §13.4, §13.10 #10) via HL native batchModify. `size` = the NEW
+     * Amend via HL native batchModify. `size` = the NEW
      * open (unfilled) size — native-modify semantics, not the original total. The
      * order's own tif (Gtc/Alo) and reduceOnly are read from frontendOpenOrders
      * and preserved; nothing is hardcoded.
@@ -494,7 +504,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
         limitPrice?: string;
         reduceOnly?: boolean;
     }): Promise<unknown>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     /**
      * Order history: POST /info {type:"historicalOrders"} ("Retrieve a user's historical orders",
@@ -538,7 +548,7 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * Place a trigger order (stop loss / take profit).
      * Python SDK: order() with trigger type {"trigger": {triggerPx, isMarket, tpsl: "tp"|"sl"}}
      *
-     * Pricing (design §13.10 #3):
+     * Pricing:
      * - isMarket (default): HL native market trigger; `p` = trigger ± 10 % (the venue's documented
      *   market TP/SL slippage tolerance, HL_MARKET_TPSL_SLIPPAGE_BPS), aligned toward crossing.
      * - limit trigger with an explicit `limitPrice`: that price, rounded to HL's grid.
@@ -665,10 +675,6 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
      * adapter creation. Throws on a venue rejection (SSOT Rule #2).
      */
     setReferrer(code: string): Promise<unknown>;
-    /**
-     * Get funding history for a symbol.
-     */
-    getFundingHistoryRaw(symbol: string, startTime: number, endTime?: number): Promise<any>;
     /**
      * Get user trade fills.
      */