perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/hyperliquid.js

@@ -1,5 +1,6 @@
+import { assertCandleInterval } from "./interface.js";
 import { LocalEvmSigner } from "../signer/index.js";
-import { DEFINITE_ORDER_FAILURE_CODES, PerpError, classifyError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
+import { DEFINITE_ORDER_FAILURE_CODES, PerpError, classifyError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure, noAccountKeyError } from "../errors.js";
 import { parseFiniteVenueNumber, venueRateField } from "../utils/numeric.js";
 import { alignProtectionPrice, floorSize, formatComputedPrice, slippagePrice, subDecimal } from "./precision.js";
 import { unsupported } from "./trading-v2.js";
@@ -9,9 +10,9 @@ import { rateLimitedError } from "./rate-limiter.js";
 import { fetchAndCache, withCache, TTL_ACCOUNT } from "../cache.js";
 import { approvalFromMax, builderGateOf, hlFeeTenthsBps, NO_BUILDER, requireFeeBps } from "./builder-fee.js";
 /**
- * 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 function hlTif(raw) {
     const t = raw.trim().toUpperCase();
@@ -31,7 +32,7 @@ export function hlSizeStep(szDecimals) {
     return szDecimals <= 0 ? "1" : `0.${"0".repeat(szDecimals - 1)}1`;
 }
 /**
- * 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
@@ -56,8 +57,8 @@ export function hlProtectionPrice(reference, side, bps, szDecimals, maxDecimals)
     return { protectionPrice, appliedBps };
 }
 /**
- * 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."
@@ -140,7 +141,7 @@ export async function assertHlAppliedBps(appliedBps, what) {
 }
 /**
  * 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;
@@ -270,6 +271,18 @@ export const HL_ABSTRACTION_TTL_MS = 60_000;
 export function hlAbstractionCachePrefix(network) {
     return `mode:hl:${network}:abstraction:`;
 }
+/**
+ * Margin tiers of a universe entry. Docs "Margin tiers": "For IDs less than 50, there is a single
+ * tier with max leverage equal to the ID" — those tables are not in `marginTables`, so the
+ * implicit tier is emitted instead of null. Unknown ids ≥ 50 → null.
+ */
+export function hlMarginTiersOf(marginTableId, tierMap) {
+    const id = Number(marginTableId);
+    const tiers = tierMap.get(id);
+    if (tiers !== undefined)
+        return tiers;
+    return Number.isInteger(id) && id > 0 && id < 50 ? [{ lowerBound: 0, maxLeverage: id }] : null;
+}
 /** Venue margin restriction of a universe entry: strictIsolated (no margin removal) / noCross; null = unrestricted. */
 export function hlMarginModeOf(asset) {
     if (asset.marginMode === "strictIsolated")
@@ -343,6 +356,32 @@ export function hlL1ActionRejection(type, e) {
 const HL_FUNDING_PAGE = 500;
 /** 7 days of hourly funding = 168 rows per coin; 20 pages = 10 000 rows (~60 coins). */
 const HL_FUNDING_MAX_PAGES = 20;
+/**
+ * candleSnapshot intervals (docs "Candle snapshot": "Supported intervals") with their nominal
+ * length. Anything else is answered 422 "Failed to deserialize" (live 2026-10-19, "7m"), so it is
+ * refused as INVALID_PARAMS before sending. "1M" buckets are 30 days, not calendar months
+ * (live: consecutive 1M opens 30 d apart); "1w" buckets open on Thursday 00:00 UTC.
+ */
+export const HL_CANDLE_INTERVAL_MS = {
+    "1m": 60_000, "3m": 180_000, "5m": 300_000, "15m": 900_000, "30m": 1_800_000,
+    "1h": 3_600_000, "2h": 7_200_000, "4h": 14_400_000, "8h": 28_800_000, "12h": 43_200_000,
+    "1d": 86_400_000, "3d": 259_200_000, "1w": 604_800_000, "1M": 2_592_000_000,
+};
+/** Docs "Candle snapshot": "Only the most recent 5000 candles are available". */
+export const HL_CANDLE_CAP = 5000;
+/** Earliest candleSnapshot start (unix ms) for `interval` at `now`: now − 5000 × interval. Unknown interval → NaN. */
+export function hlEarliestCandleStart(interval, now = Date.now()) {
+    return now - HL_CANDLE_CAP * (HL_CANDLE_INTERVAL_MS[interval] ?? Number.NaN);
+}
+/** recentTrades returns the last 10 trades, with no count parameter (live 2026-10-19). */
+export const HL_RECENT_TRADES_CAP = 10;
+/** l2Book returns at most 20 levels per side (docs l2Book; live 2026-10-19). */
+export const HL_BOOK_LEVELS_CAP = 20;
+/** Time-range info responses carry at most 500 elements (docs "Info endpoint" pagination note). */
+const HL_INFO_PAGE = 500;
+/** Largest `market funding --limit` (hourly rows ≈ 208 days) and the page guard of one read. */
+export const HL_FUNDING_HISTORY_MAX_LIMIT = 5000;
+const HL_FUNDING_HISTORY_MAX_PAGES = 20;
 /** A required field of an HL info row as a string; missing / empty → EXCHANGE_ERROR. */
 function hlField(row, key, endpoint) {
     const v = row[key];
@@ -362,6 +401,203 @@ function hlSide(v, endpoint) {
         return "sell";
     throw new PerpError("EXCHANGE_ERROR", `Hyperliquid ${endpoint} row with unknown side ${JSON.stringify(v)}`, { exchange: "hyperliquid" });
 }
+/**
+ * Open positions of one clearinghouseState (info `clearinghouseState` {user[, dex]}): rows with
+ * szi 0 dropped. The ONE mapper of the keyed `getPositions` and the public-address read
+ * (`account positions --address`); `symbolOf` names the row (keyed: the adapter's display name,
+ * public: the plain coin — "BTC", HIP-3 "xyz:GOLD").
+ */
+export function hlPositionRows(state, symbolOf) {
+    const positions = (state?.assetPositions ?? []);
+    return positions
+        .filter((p) => {
+        const pos = (p.position ?? p);
+        return parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid") !== 0;
+    })
+        .map((p) => {
+        const pos = (p.position ?? p);
+        const szi = parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid");
+        const positionValue = pos.positionValue !== undefined && pos.positionValue !== null
+            ? parseFiniteVenueNumber(pos.positionValue, "position.positionValue", "hyperliquid")
+            : 0;
+        return {
+            symbol: symbolOf(String(pos.coin ?? "")),
+            side: szi > 0 ? "long" : "short",
+            size: String(Math.abs(szi)),
+            entryPrice: String(pos.entryPx ?? "0"),
+            // clearinghouseState has no per-position mark: positionValue / |szi| is computed, so it is
+            // formatted (no "2727.2000000000003").
+            markPrice: szi !== 0 && positionValue !== 0
+                ? formatComputedPrice(positionValue / Math.abs(szi))
+                : String(pos.markPx ?? "0"),
+            liquidationPrice: pos.liquidationPx != null ? String(pos.liquidationPx) : null,
+            unrealizedPnl: String(pos.unrealizedPnl ?? "0"),
+            leverage: parseFiniteVenueNumber(pos.leverage?.value, "position.leverage.value", "hyperliquid", { defaultValue: 1 }),
+        };
+    });
+}
+/**
+ * info `userAbstraction` answer → mode. Per SSOT Rule #2: an unrecognized venue response throws —
+ * no silent default.
+ */
+export function hlAbstractionModeOf(raw) {
+    if (raw === "unifiedAccount")
+        return "unified";
+    if (raw === "portfolioMargin")
+        return "portfolio";
+    if (raw === "disabled")
+        return "standard";
+    if (raw === "default")
+        return "default";
+    // "dexAbstraction" is HL's discontinued fourth mode, still returned for some users. It is
+    // NOT unified: "USDC balances default to perps balance, all other collateral defaults to
+    // spot balance" (docs trading/account-abstraction-modes). Handled explicitly in hlBalanceOf().
+    if (raw === "dexAbstraction")
+        return "dexAbstraction";
+    throw new PerpError("INVALID_PARAMS", `UNKNOWN_ACCOUNT_MODE: HL returned unrecognized userAbstraction mode: ${JSON.stringify(raw)}`, { remediation: "Check app.hyperliquid.xyz Settings → Account Mode" });
+}
+/**
+ * Portfolio-margin collateral rows: the venue returns an `ltv` on exactly the eligible collateral
+ * tokens (live 2026-10-26: USDC, HYPE, USDT0 carry it, memecoins do not; unified-mode rows never
+ * do), plus the dex's collateral token itself.
+ */
+export function hlIsPortfolioCollateral(row, collateralToken) {
+    return Number(row.token) === collateralToken || Object.prototype.hasOwnProperty.call(row, "ltv");
+}
+/**
+ * USDC price of each spot token (index → price) from info `spotMetaAndAssetCtxs`: the mark of its
+ * USDC-quoted pair (quote token 0); several pairs for one token → the one with the larger 24h
+ * notional. USDC itself is 1. Malformed payload → EXCHANGE_ERROR (never a guessed price).
+ */
+export function hlSpotUsdPricesOf(raw) {
+    const arr = raw;
+    const universe = Array.isArray(arr) ? arr[0]?.universe : undefined;
+    const ctxs = Array.isArray(arr) ? arr[1] : undefined;
+    if (!Array.isArray(universe) || !Array.isArray(ctxs)) {
+        throw new PerpError("EXCHANGE_ERROR", "Hyperliquid spotMetaAndAssetCtxs: expected [meta, ctxs]", { exchange: "hyperliquid" });
+    }
+    const best = new Map();
+    for (const pair of universe) {
+        const tokens = pair.tokens;
+        if (!Array.isArray(tokens) || tokens[1] !== 0 || typeof pair.index !== "number")
+            continue;
+        const ctx = ctxs[pair.index];
+        const price = Number(ctx?.markPx);
+        if (!Number.isFinite(price) || price <= 0)
+            continue;
+        const vol = Number(ctx?.dayNtlVlm);
+        const base = Number(tokens[0]);
+        const prev = best.get(base);
+        if (prev === undefined || (Number.isFinite(vol) ? vol : 0) > prev.vol)
+            best.set(base, { price, vol: Number.isFinite(vol) ? vol : 0 });
+    }
+    const out = new Map([[0, 1]]);
+    for (const [t, v] of best)
+        out.set(t, v.price);
+    return out;
+}
+export async function hlBalanceOf(state, mode, dex, reads) {
+    const s = state;
+    const notes = [];
+    const margin = (s?.marginSummary ?? {});
+    const cross = (s?.crossMarginSummary ?? {});
+    const marginUsed = parseFiniteVenueNumber(margin.totalMarginUsed ?? cross.totalMarginUsed, "marginSummary.totalMarginUsed", "hyperliquid");
+    // Sum unrealized PnL directly from positions (reliable for both main + dex accounts)
+    const positions = (s?.assetPositions ?? []);
+    let unrealizedPnl = 0;
+    for (const entry of positions) {
+        const pos = (entry.position ?? entry);
+        unrealizedPnl += parseFiniteVenueNumber(pos.unrealizedPnl, "position.unrealizedPnl", "hyperliquid");
+    }
+    let equity;
+    let available;
+    let portfolio = null;
+    // dexAbstraction (discontinued): USDC (token 0) lives in the NATIVE perp balance, any other
+    // collateral token in spot. Native perps → the perp state below. A HIP-3 dex with non-USDC
+    // collateral → its spot row. A USDC-collateral HIP-3 dex is refused: its dex state is not the
+    // balance ("Cross margin on HIP-3 DEXs does not behave intuitively for DEX abstraction users").
+    let spotIsTruth = mode === "unified" || mode === "portfolio";
+    if (mode === "dexAbstraction" && dex) {
+        if (await reads.collateralToken() === 0) {
+            throw new PerpError("NOT_IMPLEMENTED", `Hyperliquid account mode "dexAbstraction" (discontinued by the venue): the USDC balance of HIP-3 dex "${dex}" cannot be read reliably`, {
+                exchange: "hyperliquid",
+                remediation: "Switch the account mode first: perp -e hyperliquid wallet manage account-mode unified (or standard)",
+            });
+        }
+        spotIsTruth = true;
+    }
+    if (spotIsTruth) {
+        const { row, balances, token } = await reads.spotCollateralRow();
+        const coin = row === null ? `token#${token}` : String(row.coin);
+        const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.${coin}.total`, "hyperliquid");
+        const spotHold = parseFiniteVenueNumber(row?.hold, `spotBalance.${coin}.hold`, "hyperliquid");
+        equity = spotTotal;
+        available = spotTotal - spotHold;
+        if (mode === "portfolio") {
+            const prices = await reads.spotUsdPrices();
+            const rows = [];
+            let value = 0;
+            for (const b of balances) {
+                if (!hlIsPortfolioCollateral(b, token))
+                    continue;
+                const c = String(b.coin);
+                const total = parseFiniteVenueNumber(b.total, `spotBalance.${c}.total`, "hyperliquid");
+                if (total === 0)
+                    continue; // an empty row adds nothing (USDT0 0 with a hold: the hold is in available)
+                const isCollateral = Number(b.token) === token;
+                let priceUsd;
+                if (isCollateral)
+                    priceUsd = 1;
+                else {
+                    const p = prices.get(Number(b.token));
+                    if (p === undefined) {
+                        throw new PerpError("PRICE_STALE", `Hyperliquid portfolio margin: no USDC spot price for collateral ${c} (token ${String(b.token)}) — equity unknown`, {
+                            exchange: "hyperliquid", remediation: "Retry shortly; the spot market context read may have failed",
+                        });
+                    }
+                    priceUsd = p;
+                }
+                const valueUsd = total * priceUsd;
+                value += valueUsd;
+                rows.push({
+                    token: c, total: String(b.total), priceUsd: String(priceUsd), valueUsd: String(valueUsd),
+                    ltv: typeof b.ltv === "string" ? b.ltv : null,
+                    borrowed: typeof b.borrowed === "string" ? b.borrowed : null,
+                    supplied: typeof b.supplied === "string" ? b.supplied : null,
+                });
+            }
+            equity = value;
+            const ratio = (await reads.spotCollateralRow()).portfolioMarginRatio;
+            portfolio = { collateral: rows, portfolioMarginRatio: typeof ratio === "string" ? ratio : null };
+            notes.push(`[hl] portfolio margin: equity = Σ collateral total × spot USDC price (${rows.map(r => `${r.token} ${r.total}${r.priceUsd !== "1" ? ` × ${r.priceUsd}` : ""}`).join(" + ")}); non-collateral spot tokens are listed in spot, vault equity is not included\n`);
+        }
+    }
+    else {
+        equity = parseFiniteVenueNumber(margin.accountValue ?? cross.accountValue, "marginSummary.accountValue", "hyperliquid");
+        available = parseFiniteVenueNumber(s?.withdrawable, "withdrawable", "hyperliquid");
+        if (mode === "default" && equity === 0) {
+            // Unset mode: do not assume unified. If the perp side reads 0 while spot holds
+            // the collateral token, say so instead of reporting an empty account silently.
+            const { row, token } = await reads.spotCollateralRow();
+            const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.token#${token}.total`, "hyperliquid");
+            if (spotTotal > 0) {
+                notes.push(`[hl] account mode is unset ("default"): perp equity${dex ? ` on dex ${dex}` : ""} is 0 while spot holds ${spotTotal} ${String(row?.coin)}. ` +
+                    `That spot balance is not perp collateral here. Either switch the account to unified ` +
+                    `(perp wallet manage account-mode unified) or move it: perp -e hyperliquid trade spot-transfer to-perp <amount>\n`);
+            }
+        }
+    }
+    return {
+        balance: {
+            equity: String(equity),
+            available: String(available),
+            marginUsed: String(marginUsed),
+            unrealizedPnl: String(unrealizedPnl),
+            ...(portfolio ?? {}),
+        },
+        notes,
+    };
+}
 export class HyperliquidAdapter {
     name = "hyperliquid";
     chain = "evm";
@@ -375,6 +611,8 @@ export class HyperliquidAdapter {
      * semantics for accounts that have never opted in. Codex v0.12.12 final QA #1.
      */
     isUnifiedAccount = false;
+    /** The account abstraction mode resolved in init() (null until then / without an address). */
+    accountMode = null;
     _address;
     _privateKey;
     _testnet;
@@ -400,6 +638,8 @@ export class HyperliquidAdapter {
      * configured. Set by createHyperliquid — the adapter never reads settings.
      */
     builderFee = null;
+    /** recentTrades' fixed tape size (no paging): `market trades` defaults to min(20, this). */
+    recentTradesCap = HL_RECENT_TRADES_CAP;
     constructor(privateKey, testnet = false) {
         // No SDK: /info reads go through _infoPost, /exchange actions are signed here (hl-signing.ts).
         this._address = "";
@@ -409,9 +649,39 @@ export class HyperliquidAdapter {
     /** Set the HIP-3 deployed perp dex to query/trade on. */
     setDex(dex) {
         this._dex = dex;
-        // Rebuild asset map for the new dex
-        this._assetMap.clear();
-        this._assetMapReverse.clear();
+        // Fresh market state for the new dex — NEW objects, never .clear(): a map shared with another
+        // adapter (prototype copy) must not be emptied under it. Rebuilt lazily (_loadAssetMap).
+        this._assetMap = new Map();
+        this._assetMapReverse = new Map();
+        this._szDecimalsMap = new Map();
+        this._marginModeMap = new Map();
+        this._assetMapError = null;
+        this._marketsCache = null;
+        this._marketsCacheTime = 0;
+        this._delisted = new Set();
+        this._delistedAssets = new Set();
+        this._chsInFlight = null;
+        this._collateralTokenIdx = null;
+    }
+    /**
+     * An independent adapter for HIP-3 dex `dex` ("" = native perps) with this adapter's account
+     * configuration (key / signers / address / network / builder gate) and its OWN market state
+     * (asset maps, markets cache, delisted sets, in-flight reads). Fan-outs over dexes use this:
+     * Object.create(adapter) + setDex() shared the prototype's maps, so setDex cleared the native
+     * adapter's asset map and the dex copies served the native markets cache.
+     */
+    forDex(dex) {
+        const a = new HyperliquidAdapter(this._privateKey || undefined, this._testnet);
+        a._address = this._address;
+        a._evmSigner = this._evmSigner;
+        a._agentSigner = this._agentSigner;
+        a._agentMeta = this._agentMeta;
+        a._useNoAgent = this._useNoAgent;
+        a.isUnifiedAccount = this.isUnifiedAccount;
+        a.accountMode = this.accountMode;
+        a.builderFee = this.builderFee;
+        a.setDex(dex);
+        return a;
     }
     get dex() {
         return this._dex;
@@ -544,6 +814,7 @@ export class HyperliquidAdapter {
         // every caller that branches on the account mode.
         if (this._address) {
             const mode = await this._getAbstractionMode();
+            this.accountMode = mode;
             // dexAbstraction is not unified (USDC stays in the perp balance).
             this.isUnifiedAccount = mode === "unified" || mode === "portfolio";
         }
@@ -562,6 +833,7 @@ export class HyperliquidAdapter {
     /** Load asset index map — supports native and HIP-3 dex. */
     async _loadAssetMap() {
         this._assetMapError = null;
+        this._delistedAssets = new Set();
         try {
             if (this._dex) {
                 // HIP-3 deployed dex: asset indices use global offset scheme
@@ -598,6 +870,10 @@ export class HyperliquidAdapter {
                         this._assetMap.set(fullName, globalIdx);
                         this._assetMap.set(baseName, globalIdx);
                         this._assetMapReverse.set(globalIdx, fullName);
+                        if (asset.isDelisted === true) {
+                            this._delistedAssets.add(fullName);
+                            this._delistedAssets.add(baseName);
+                        }
                         // Cache szDecimals for dex assets (critical for order sizing)
                         if (asset.szDecimals !== undefined) {
                             this._szDecimalsMap.set(fullName, asset.szDecimals);
@@ -620,6 +896,8 @@ export class HyperliquidAdapter {
                         const sym = `${asset.name}-PERP`;
                         this._assetMap.set(sym, idx);
                         this._assetMapReverse.set(idx, sym);
+                        if (asset.isDelisted === true)
+                            this._delistedAssets.add(sym);
                         if (asset.szDecimals !== undefined) {
                             this._szDecimalsMap.set(sym, asset.szDecimals);
                         }
@@ -653,7 +931,7 @@ export class HyperliquidAdapter {
             // A dex-prefixed symbol must name THIS adapter's dex — never rewritten onto another dex.
             const [prefix, base] = sym.split(":");
             if (prefix.toLowerCase() !== this._dex.toLowerCase()) {
-                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid symbol ${symbol} is on dex "${prefix.toLowerCase()}", not ${this._dex ? `this adapter's dex "${this._dex}"` : "the native perp dex"}`, {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid symbol ${prefix.toLowerCase()}:${base} is on dex "${prefix.toLowerCase()}", not ${this._dex ? `this adapter's dex "${this._dex}"` : "the native perp dex"}`, {
                     exchange: "hyperliquid", remediation: `Select the dex: perp -e hyperliquid --dex ${prefix.toLowerCase()} ...`,
                 });
             }
@@ -726,7 +1004,14 @@ export class HyperliquidAdapter {
             }
             return idx;
         }
-        throw new PerpError("SYMBOL_NOT_FOUND", `Unknown asset: ${symbol}`, { exchange: "hyperliquid" });
+        throw this._unknownSymbol(symbol, `Unknown asset: ${symbol}`);
+    }
+    /** SYMBOL_NOT_FOUND for a coin the venue does not list (on this adapter's dex), with the listing command. */
+    _unknownSymbol(symbol, message) {
+        return new PerpError("SYMBOL_NOT_FOUND", message ?? `Hyperliquid has no market ${symbol.toUpperCase()}${this._dex ? ` on dex "${this._dex}"` : ""}`, {
+            exchange: "hyperliquid",
+            remediation: `List markets: perp -e hyperliquid${this._dex ? ` --dex ${this._dex}` : ""} market list`,
+        });
     }
     async getMarkets() {
         if (this._marketsCache && Date.now() - this._marketsCacheTime < HyperliquidAdapter.CACHE_TTL)
@@ -785,32 +1070,109 @@ export class HyperliquidAdapter {
                 this._assetMapReverse.set(i, sym);
             });
         }
-        const result = universe.map((asset, i) => {
+        // Delisted assets (meta `isDelisted: true`; live 2026-10-14: 56 of 234 native perps, all with
+        // funding / dayNtlVlm / openInterest "0.0") are not markets: excluded from the listing and
+        // everything built on it. They stay in the asset map (_loadAssetMap), so an explicit symbol
+        // still resolves for orders / position reads.
+        const delisted = new Set();
+        const result = universe.flatMap((asset, i) => {
+            if (asset.isDelisted === true) {
+                delisted.add(String(asset.name));
+                return [];
+            }
             const ctx = (ctxs[i] ?? {});
             const sym = String(asset.name);
             const szDec = this._szDecimalsMap.get(sym) ?? (asset.szDecimals !== undefined ? Number(asset.szDecimals) : null);
-            return {
-                symbol: sym,
-                markPrice: String(ctx.markPx ?? mids[sym] ?? "0"),
-                indexPrice: ctx.oraclePx != null ? String(ctx.oraclePx) : null,
-                fundingRate: ctx.funding != null ? String(ctx.funding) : null,
-                volume24h: ctx.dayNtlVlm != null ? String(ctx.dayNtlVlm) : null,
-                openInterest: ctx.openInterest != null ? String(ctx.openInterest) : null,
-                maxLeverage: Number(asset.maxLeverage ?? 50),
-                sizeDecimals: szDec,
-                // HL has no separate lot-size field; the step is implied by szDecimals.
-                stepSize: null,
-                // HL funding is uniform (venue definition), not per-market.
-                fundingHours: null,
-                marginTiers: tierMap.get(Number(asset.marginTableId)) ?? null,
-            };
+            return [{
+                    // One symbol shape on every venue: the plain asset ("BTC"; HIP-3 "km:US500"), the
+                    // venue's wire coin in venueSymbol. The internal "<COIN>-PERP" key is not shown.
+                    symbol: sym.replace(/-PERP$/, ""),
+                    // The coin exactly as the venue names it on the wire (native "kPEPE", HIP-3 "xyz:TSLA" —
+                    // lower-case dex prefix); _venueCoin upper-cases its input, so it is not used here.
+                    venueSymbol: sym.replace(/-PERP$/, ""),
+                    markPrice: String(ctx.markPx ?? mids[sym] ?? "0"),
+                    indexPrice: ctx.oraclePx != null ? String(ctx.oraclePx) : null,
+                    fundingRate: ctx.funding != null ? String(ctx.funding) : null,
+                    // metaAndAssetCtxs `funding` = the running hour's rate (WS allDexsAssetCtxs: accruing).
+                    fundingRateKind: ctx.funding != null ? "accruing" : null,
+                    volume24h: ctx.dayNtlVlm != null ? String(ctx.dayNtlVlm) : null,
+                    openInterest: ctx.openInterest != null ? String(ctx.openInterest) : null,
+                    maxLeverage: Number(asset.maxLeverage ?? 50),
+                    sizeDecimals: szDec,
+                    // HL has no separate lot-size field; the step is implied by szDecimals (10^-szDecimals,
+                    // the same value the keyless MCP get_markets path states).
+                    stepSize: szDec !== null && Number.isInteger(szDec) && szDec >= 0 ? (szDec === 0 ? "1" : `0.${"0".repeat(szDec - 1)}1`) : null,
+                    // HL funding is uniform: a fraction per 1 h (venue fundingRateBasis), core and HIP-3.
+                    fundingHours: 1,
+                    marginTiers: hlMarginTiersOf(asset.marginTableId, tierMap),
+                }];
         });
+        this._delisted = delisted;
         this._marketsCache = result;
         this._marketsCacheTime = Date.now();
         return result;
     }
-    async getOrderbook(symbol) {
+    /** Display names of the delisted assets seen by the last getMarkets() (meta isDelisted). */
+    _delisted = new Set();
+    /** Asset-map keys of the delisted assets in `meta` (_loadAssetMap): "MATIC-PERP"; HIP-3 "km:US500" and "US500". */
+    _delistedAssets = new Set();
+    /**
+     * Why `symbol` is not in getMarkets(): it is delisted (message), or null when it is not a
+     * delisted asset. Read after getMarkets() (or once the asset map is loaded). `market info` uses
+     * it to say "delisted" rather than "not found" — the asset map still resolves it for orders /
+     * positions / history. A HIP-3 bare name ("US500" on --dex km) is matched by its venue coin.
+     */
+    delistedMessage(symbol) {
+        const resolved = this.resolveSymbol(symbol.toUpperCase());
+        const coin = this._venueCoin(symbol).replace(/^([^:]+):/, (_m, dex) => `${dex.toLowerCase()}:`); // "KM:US500" → "km:US500"
+        const isDelisted = this._delisted.has(resolved) || this._delisted.has(coin) || this._delistedAssets.has(resolved);
+        if (!isDelisted)
+            return null;
+        return `${this._dex ? coin : resolved.replace(/-PERP$/, "")} is delisted on Hyperliquid (positions / history still readable)`;
+    }
+    /** SYMBOL_NOT_FOUND (details.reason "delisted") for a delisted `symbol`, with a dex-aware remediation; null when listed. */
+    delistedError(symbol) {
+        const msg = this.delistedMessage(symbol);
+        if (msg === null)
+            return null;
+        return new PerpError("SYMBOL_NOT_FOUND", msg, {
+            exchange: "hyperliquid",
+            reason: "delisted",
+            remediation: `List live markets: perp -e hyperliquid${this._dex ? ` --dex ${this._dex}` : ""} market list`,
+        });
+    }
+    /**
+     * Per-symbol MARKET-DATA reads (trades, funding, book, klines): the symbol must resolve
+     * (SYMBOL_NOT_FOUND) and must not be delisted — HL keeps serving a delisted coin's last tape
+     * (MATIC: trades from 2024-09-09) and zero-rate funding rows stamped every hour (live
+     * 2026-10-19), which read as a live market. Orders / positions / history do not call this.
+     */
+    async _listedMarket(symbol) {
+        await this.getAssetIndex(symbol);
+        const err = this.delistedError(symbol);
+        if (err !== null)
+            throw err;
+    }
+    /**
+     * Public order-book read (`market book`, bots, MCP): l2Book serves at most HL_BOOK_LEVELS_CAP
+     * (20) levels per side and cannot be paged, so a `depth` above it is INVALID_PARAMS naming the
+     * cap. Refuses delisted markets (_listedMarket). Order paths use _l2Book (no delisted gate):
+     * a reduce-only close of a delisted asset must still get its reference price.
+     */
+    async getOrderbook(symbol, depth) {
+        if (depth !== undefined && !(Number.isInteger(depth) && depth > 0 && depth <= HL_BOOK_LEVELS_CAP)) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid order book: depth must be an integer 1..${HL_BOOK_LEVELS_CAP} (got ${depth}) — l2Book serves at most ${HL_BOOK_LEVELS_CAP} levels per side`, {
+                exchange: "hyperliquid", remediation: `Use -d ${HL_BOOK_LEVELS_CAP} or less`,
+            });
+        }
+        await this._listedMarket(symbol);
+        return this._l2Book(symbol);
+    }
+    /** l2Book of `symbol` (native or this adapter's dex), no listing gate. Unlisted coin → SYMBOL_NOT_FOUND. */
+    async _l2Book(symbol) {
         let levels;
+        // l2Book answers `null` for a coin the venue does not list (live 2026-10-14, coin "NOPE"):
+        // SYMBOL_NOT_FOUND, never an empty book (which reads as "no liquidity").
         if (this._dex) {
             // HIP-3 dex: full dex-prefixed coin (e.g. "US500" → "km:US500") + dex param
             const book = await this._infoPost({
@@ -818,11 +1180,15 @@ export class HyperliquidAdapter {
                 coin: this._venueCoin(symbol),
                 dex: this._dex,
             });
-            levels = book?.levels ?? [[], []];
+            if (book === null)
+                throw this._unknownSymbol(symbol);
+            levels = book.levels ?? [[], []];
         }
         else {
             const book = await this._infoPost({ type: "l2Book", coin: this._venueCoin(symbol) });
-            levels = book?.levels ?? [[], []];
+            if (book === null)
+                throw this._unknownSymbol(symbol);
+            levels = book.levels ?? [[], []];
         }
         return {
             bids: (levels[0] ?? []).map((l) => [
@@ -851,7 +1217,7 @@ export class HyperliquidAdapter {
     }
     ensureAddress() {
         if (!this._address) {
-            throw new Error("No private key configured — account data unavailable. Run: perp setup");
+            throw noAccountKeyError(this.name);
         }
     }
     /** The in-flight clearinghouseState read: parallel callers (getBalance + getPositions) share one request. */
@@ -894,23 +1260,7 @@ export class HyperliquidAdapter {
     async _getAbstractionMode(opts = {}) {
         this.ensureAddress();
         const key = `${hlAbstractionCachePrefix(this._network)}${this._address.toLowerCase()}`;
-        return (opts.fresh === true ? fetchAndCache : withCache)(key, HL_ABSTRACTION_TTL_MS, async () => {
-            const raw = (await this._infoPost({ type: "userAbstraction", user: this._address }));
-            if (raw === "unifiedAccount")
-                return "unified";
-            if (raw === "portfolioMargin")
-                return "portfolio";
-            if (raw === "disabled")
-                return "standard";
-            if (raw === "default")
-                return "default";
-            // "dexAbstraction" is HL's discontinued fourth mode, still returned for some users. It is
-            // NOT unified: "USDC balances default to perps balance, all other collateral defaults to
-            // spot balance" (docs trading/account-abstraction-modes). Handled explicitly in getBalance().
-            if (raw === "dexAbstraction")
-                return "dexAbstraction";
-            throw new PerpError("INVALID_PARAMS", `UNKNOWN_ACCOUNT_MODE: HL returned unrecognized userAbstraction mode: ${JSON.stringify(raw)}`, { remediation: "Check app.hyperliquid.xyz Settings → Account Mode" });
-        });
+        return (opts.fresh === true ? fetchAndCache : withCache)(key, HL_ABSTRACTION_TTL_MS, async () => hlAbstractionModeOf(await this._infoPost({ type: "userAbstraction", user: this._address })));
     }
     /** Collateral token index of this adapter's perp dex (info `meta{dex}.collateralToken`; 0 = USDC on native perps). */
     _collateralTokenIdx = null;
@@ -941,127 +1291,22 @@ export class HyperliquidAdapter {
         const [spotState, token] = await Promise.all([this._getSpotClearinghouseState(), this._getCollateralToken()]);
         const balances = (spotState?.balances ?? []);
         const row = balances.find((b) => Number(b.token) === token) ?? null;
-        return { row, balances, token };
+        return { row, balances, token, portfolioMarginRatio: spotState?.portfolioMarginRatio };
     }
     async getBalance() {
         const state = await this._getClearinghouseState();
-        const s = state;
-        const margin = (s?.marginSummary ?? {});
-        const cross = (s?.crossMarginSummary ?? {});
-        const marginUsed = parseFiniteVenueNumber(margin.totalMarginUsed ?? cross.totalMarginUsed, "marginSummary.totalMarginUsed", "hyperliquid");
-        // Sum unrealized PnL directly from positions (reliable for both main + dex accounts)
-        const positions = (s?.assetPositions ?? []);
-        let unrealizedPnl = 0;
-        for (const entry of positions) {
-            const pos = (entry.position ?? entry);
-            unrealizedPnl += parseFiniteVenueNumber(pos.unrealizedPnl, "position.unrealizedPnl", "hyperliquid");
-        }
-        let equity;
-        let available;
-        // Branch by the user's account abstraction mode (Rule #2: no silent fallback).
-        // - "unified" / "portfolio": per HL docs, API users see all balances and holds
-        //   in the spot clearinghouse state; the dex's collateral token row (by token
-        //   index from meta{dex}.collateralToken) is the equity. Adding perp margin
-        //   would double-count.
-        // - "standard" / "default": perp clearinghouse (per dex) is the collateral source.
-        //
-        // Portfolio-margin mode: eligible collateral includes HYPE, BTC, USDT besides
-        // USDC. Only the collateral token is counted; a stderr note lists the rest.
         const mode = await this._getAbstractionMode();
-        // dexAbstraction (discontinued): USDC (token 0) lives in the NATIVE perp balance, any other
-        // collateral token in spot. Native perps → the perp state below. A HIP-3 dex with non-USDC
-        // collateral → its spot row. A USDC-collateral HIP-3 dex is refused: its dex state is not the
-        // balance ("Cross margin on HIP-3 DEXs does not behave intuitively for DEX abstraction users").
-        let spotIsTruth = mode === "unified" || mode === "portfolio";
-        if (mode === "dexAbstraction" && this._dex) {
-            if (await this._getCollateralToken() === 0) {
-                throw new PerpError("NOT_IMPLEMENTED", `Hyperliquid account mode "dexAbstraction" (discontinued by the venue): the USDC balance of HIP-3 dex "${this._dex}" cannot be read reliably`, {
-                    exchange: "hyperliquid",
-                    remediation: "Switch the account mode first: perp -e hyperliquid wallet manage account-mode unified (or standard)",
-                });
-            }
-            spotIsTruth = true;
-        }
-        if (spotIsTruth) {
-            const { row, balances, token } = await this._spotCollateralRow();
-            const coin = row === null ? `token#${token}` : String(row.coin);
-            const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.${coin}.total`, "hyperliquid");
-            const spotHold = parseFiniteVenueNumber(row?.hold, `spotBalance.${coin}.hold`, "hyperliquid");
-            equity = spotTotal;
-            available = spotTotal - spotHold;
-            if (mode === "portfolio") {
-                // Eligible collateral per trading/account-abstraction-modes.md ("eligible
-                // assets, which are currently HYPE, BTC, USDC, USDT").
-                const PORTFOLIO_COLLATERAL = ["HYPE", "BTC", "USDT"];
-                const others = balances.filter((b) => {
-                    if (Number(b.token) === token)
-                        return false;
-                    const c = String(b.coin);
-                    // Reject NaN/empty here too — venue payload corruption shouldn't
-                    // silently filter a token in or out.
-                    const total = parseFiniteVenueNumber(b.total, `spotBalance.${c}.total`, "hyperliquid");
-                    if (total <= 0)
-                        return false;
-                    return PORTFOLIO_COLLATERAL.some((p) => c === p || c.startsWith(`${p}-`));
-                });
-                if (others.length > 0) {
-                    const summary = others.map((b) => `${b.coin}=${b.total}`).join(", ");
-                    process.stderr.write(`[hl] portfolio mode: non-${coin} collateral present but not counted in equity (${summary}). ` +
-                        `Equity reflects ${coin} only; full multi-asset accounting pending.\n`);
-                }
-            }
-        }
-        else {
-            equity = parseFiniteVenueNumber(margin.accountValue ?? cross.accountValue, "marginSummary.accountValue", "hyperliquid");
-            available = parseFiniteVenueNumber(s?.withdrawable, "withdrawable", "hyperliquid");
-            if (mode === "default" && equity === 0) {
-                // Unset mode: do not assume unified. If the perp side reads 0 while spot holds
-                // the collateral token, say so instead of reporting an empty account silently.
-                const { row, token } = await this._spotCollateralRow();
-                const spotTotal = parseFiniteVenueNumber(row?.total, `spotBalance.token#${token}.total`, "hyperliquid");
-                if (spotTotal > 0) {
-                    process.stderr.write(`[hl] account mode is unset ("default"): perp equity${this._dex ? ` on dex ${this._dex}` : ""} is 0 while spot holds ${spotTotal} ${String(row?.coin)}. ` +
-                        `That spot balance is not perp collateral here. Either switch the account to unified ` +
-                        `(perp wallet manage account-mode unified) or move it: perp -e hyperliquid trade spot-transfer to-perp <amount>\n`);
-                }
-            }
-        }
-        return {
-            equity: String(equity),
-            available: String(available),
-            marginUsed: String(marginUsed),
-            unrealizedPnl: String(unrealizedPnl),
-        };
+        const { balance, notes } = await hlBalanceOf(state, mode, this._dex, {
+            spotCollateralRow: () => this._spotCollateralRow(),
+            collateralToken: () => this._getCollateralToken(),
+            spotUsdPrices: async () => hlSpotUsdPricesOf(await this._infoPost({ type: "spotMetaAndAssetCtxs" })),
+        });
+        for (const n of notes)
+            process.stderr.write(n);
+        return balance;
     }
     async getPositions() {
-        const state = await this._getClearinghouseState();
-        const positions = (state?.assetPositions ?? []);
-        return positions
-            .filter((p) => {
-            const pos = (p.position ?? p);
-            return parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid") !== 0;
-        })
-            .map((p) => {
-            const pos = (p.position ?? p);
-            const szi = parseFiniteVenueNumber(pos.szi, "position.szi", "hyperliquid");
-            const positionValue = pos.positionValue !== undefined && pos.positionValue !== null
-                ? parseFiniteVenueNumber(pos.positionValue, "position.positionValue", "hyperliquid")
-                : 0;
-            return {
-                symbol: this._displaySymbol(String(pos.coin ?? "")),
-                side: szi > 0 ? "long" : "short",
-                size: String(Math.abs(szi)),
-                entryPrice: String(pos.entryPx ?? "0"),
-                // clearinghouseState has no per-position mark: positionValue / |szi| is computed, so it is
-                // formatted (no "2727.2000000000003").
-                markPrice: szi !== 0 && positionValue !== 0
-                    ? formatComputedPrice(positionValue / Math.abs(szi))
-                    : String(pos.markPx ?? "0"),
-                liquidationPrice: pos.liquidationPx != null ? String(pos.liquidationPx) : null,
-                unrealizedPnl: String(pos.unrealizedPnl ?? "0"),
-                leverage: parseFiniteVenueNumber(pos.leverage?.value, "position.leverage.value", "hyperliquid", { defaultValue: 1 }),
-            };
-        });
+        return hlPositionRows(await this._getClearinghouseState(), (coin) => this._displaySymbol(coin));
     }
     /**
      * The leverage this account applies to `symbol`, position or not — info `activeAssetData`
@@ -1234,11 +1479,11 @@ export class HyperliquidAdapter {
         }
     }
     /**
-     * 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
@@ -1287,10 +1532,11 @@ export class HyperliquidAdapter {
     /**
      * The single declared reference price for market-type protection prices:
      * l2Book mid = (best bid + best ask) / 2. Works for native perps and HIP-3
-     * (getOrderbook passes the dex). Either side missing / non-positive → PRICE_STALE.
+     * (_l2Book passes the dex). Either side missing / non-positive → PRICE_STALE. Not gated on
+     * delisting: a reduce-only market close of a delisted asset is sent (the venue decides).
      */
     async referencePrice(symbol) {
-        const book = await this.getOrderbook(symbol);
+        const book = await this._l2Book(symbol);
         const bid = Number(book.bids[0]?.[0]);
         const ask = Number(book.asks[0]?.[0]);
         if (!(bid > 0) || !(ask > 0) || !Number.isFinite(bid) || !Number.isFinite(ask)) {
@@ -1531,7 +1777,7 @@ export class HyperliquidAdapter {
         return hlAlignPriceToGrid(price, this.getSzDecimals(symbol), 6, side === "buy" ? "down" : "up");
     }
     async limitOrder(symbol, side, price, size, opts) {
-        // TIF aliases (§13.3): GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
+        // TIF aliases: GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
         let action;
         const cloid = opts?.clientOrderId === undefined ? null : HyperliquidAdapter.requireCloid(opts.clientOrderId);
         try { // pre-send (see marketOrder)
@@ -1680,7 +1926,7 @@ export class HyperliquidAdapter {
     }
     // ── Interface methods ──
     /**
-     * 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.
@@ -1769,33 +2015,84 @@ export class HyperliquidAdapter {
             reduceOnly: opts?.reduceOnly ?? true,
         });
     }
-    async getRecentTrades(symbol, limit = 20) {
+    /**
+     * recentTrades: the venue's last HL_RECENT_TRADES_CAP (10) trades — no count parameter, no
+     * paging. `limit` undefined = the venue max (10); an explicit `limit` above 10 is INVALID_PARAMS
+     * naming the cap (never fewer rows than asked, silently). Row `symbol` is the raw venue coin
+     * ("BTC", "km:US500"), as in the WS codec — not the "BTC-PERP" display name of `market list`.
+     */
+    async getRecentTrades(symbol, limit) {
+        const n = limit ?? HL_RECENT_TRADES_CAP;
+        if (!(Number.isInteger(n) && n > 0)) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid trades: limit must be a positive integer (got ${limit})`, { exchange: "hyperliquid" });
+        }
+        if (n > HL_RECENT_TRADES_CAP) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid trades: limit ${n} exceeds the venue cap of ${HL_RECENT_TRADES_CAP} (recentTrades serves only the last ${HL_RECENT_TRADES_CAP} trades, no paging)`, {
+                exchange: "hyperliquid", remediation: `Use --limit ${HL_RECENT_TRADES_CAP} or less`,
+            });
+        }
+        // recentTrades answers HTTP 500 "null" for an unlisted coin (live 2026-10-14), which would read
+        // as a retryable venue error: resolve the coin against the asset map first (SYMBOL_NOT_FOUND).
+        await this._listedMarket(symbol);
         const trades = await this._infoPost({ type: "recentTrades", coin: this._venueCoin(symbol) });
-        return (trades ?? [])
-            .slice(0, limit)
+        if (trades === null)
+            throw this._unknownSymbol(symbol);
+        return trades
+            .slice(0, n)
             .map((t) => ({
             time: Number(t.time ?? 0),
             symbol: String(t.coin ?? symbol.toUpperCase()),
             side: String(t.side) === "B" ? "buy" : "sell",
             price: String(t.px ?? "0"),
             size: String(t.sz ?? ""),
-            fee: "0",
+            fee: null, // the public tape carries no fee
         }));
     }
+    /**
+     * candleSnapshot. Only the most recent HL_CANDLE_CAP (5000) candles of an interval exist (docs)
+     * and older ones cannot be paged to: a `startTime` before hlEarliestCandleStart() is refused
+     * up front (INVALID_PARAMS naming the earliest allowed start) — never a silently shortened
+     * range. `closed` (additive) is false on the in-progress candle (close time `T`, or open +
+     * interval when `T` is absent, still in the future). "1M" = 30-day buckets; "1w" opens
+     * Thursday 00:00 UTC.
+     */
     async getKlines(symbol, interval, startTime, endTime) {
+        const ivMs = HL_CANDLE_INTERVAL_MS[interval];
+        if (ivMs === undefined) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid has no ${JSON.stringify(interval)} candles`, {
+                exchange: "hyperliquid", remediation: `Use one of: ${Object.keys(HL_CANDLE_INTERVAL_MS).join(", ")}`,
+            });
+        }
+        const now = Date.now();
+        const earliest = hlEarliestCandleStart(interval, now);
+        if (startTime < earliest) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid serves only the most recent ${HL_CANDLE_CAP} ${interval} candles: the earliest allowed start is ${new Date(earliest).toISOString()} (${earliest}); requested ${new Date(startTime).toISOString()}`, {
+                exchange: "hyperliquid", remediation: `Use --start ${earliest} or later, or a longer interval`,
+            });
+        }
+        await this._listedMarket(symbol); // unlisted coin: SYMBOL_NOT_FOUND (candleSnapshot answers HTTP 500 "null")
         const candles = await this._infoPost({
             type: "candleSnapshot",
             req: { coin: this._venueCoin(symbol), interval, startTime, endTime },
         });
-        return (candles ?? []).map((c) => ({
-            time: Number(c.t ?? 0),
-            open: String(c.o ?? "0"),
-            high: String(c.h ?? "0"),
-            low: String(c.l ?? "0"),
-            close: String(c.c ?? "0"),
-            volume: String(c.v ?? ""),
-            trades: Number(c.n ?? 0),
-        }));
+        return (candles ?? []).map((c) => {
+            assertCandleInterval(this.name, interval, c.i);
+            const time = Number(c.t ?? 0);
+            const closeAt = Number.isFinite(Number(c.T)) && c.T !== undefined && c.T !== null ? Number(c.T) : time + ivMs;
+            return {
+                time,
+                open: String(c.o ?? "0"),
+                high: String(c.h ?? "0"),
+                low: String(c.l ?? "0"),
+                close: String(c.c ?? "0"),
+                // absent / non-numeric → null (never "")
+                volume: typeof c.v === "string" && c.v.trim() !== "" && Number.isFinite(Number(c.v)) ? c.v
+                    : typeof c.v === "number" && Number.isFinite(c.v) ? String(c.v) : null,
+                quoteVolume: null, // candleSnapshot carries base volume only
+                trades: Number(c.n ?? 0),
+                closed: closeAt < now,
+            };
+        });
     }
     /**
      * Order history: POST /info {type:"historicalOrders"} ("Retrieve a user's historical orders",
@@ -1942,15 +2239,59 @@ export class HyperliquidAdapter {
             return coin.startsWith(`${this._dex}:`);
         return !/[:@#/]/.test(coin);
     }
+    /**
+     * The last `limit` hourly funding settlements. HL funding is hourly, so the window starts
+     * `limit + 1` hours back (one spare hour for a settlement not yet published), and fundingHistory
+     * pages are read forward from the last row's time (docs: at most 500 elements per response;
+     * "use the last returned timestamp as the next startTime") — deduped by time, oldest first.
+     */
     async getFundingHistory(symbol, limit = 10) {
-        const now = Date.now();
-        const history = await this._infoPost({ type: "fundingHistory", coin: this._venueCoin(symbol), startTime: now - 24 * 60 * 60 * 1000 });
-        return (history ?? []).slice(-limit).map((h) => ({
+        if (!(Number.isInteger(limit) && limit > 0)) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid funding history: limit must be a positive integer (got ${limit})`, { exchange: "hyperliquid" });
+        }
+        if (limit > HL_FUNDING_HISTORY_MAX_LIMIT) {
+            throw new PerpError("INVALID_PARAMS", `Hyperliquid funding history: limit ${limit} exceeds ${HL_FUNDING_HISTORY_MAX_LIMIT} hourly rows`, { exchange: "hyperliquid", remediation: `Use --limit ${HL_FUNDING_HISTORY_MAX_LIMIT} or less` });
+        }
+        await this._listedMarket(symbol); // unlisted coin: SYMBOL_NOT_FOUND (fundingHistory answers HTTP 500)
+        const history = await this._fundingHistorySince(this._venueCoin(symbol), Date.now() - (limit + 1) * 60 * 60 * 1000);
+        return history.slice(-limit).map((h) => ({
             time: Number(h.time ?? 0),
             rate: venueRateField(h.fundingRate, "fundingHistory fundingRate", "hyperliquid"),
             price: null,
+            intervalHours: 1,
+            rateKind: "lastSettled",
         }));
     }
+    /** Every fundingHistory row of `coin` since `startTime`, paged forward (500 per response), deduped by time, oldest first. */
+    async _fundingHistorySince(coin, startTime) {
+        const byTime = new Map();
+        let from = startTime;
+        for (let page = 0;; page++) {
+            if (page >= HL_FUNDING_HISTORY_MAX_PAGES) {
+                throw new PerpError("EXCHANGE_ERROR", `Hyperliquid fundingHistory needs more than ${HL_FUNDING_HISTORY_MAX_PAGES} pages — the result would be incomplete`, { exchange: "hyperliquid" });
+            }
+            const rows = await this._infoPost({ type: "fundingHistory", coin, startTime: from });
+            if (!Array.isArray(rows)) {
+                throw new PerpError("EXCHANGE_ERROR", `Hyperliquid fundingHistory returned no list (${JSON.stringify(rows).slice(0, 120)})`, { exchange: "hyperliquid" });
+            }
+            let last = -Infinity;
+            let fresh = 0;
+            for (const h of rows) {
+                const t = Number(h.time);
+                if (!Number.isFinite(t))
+                    throw new PerpError("EXCHANGE_ERROR", `Hyperliquid fundingHistory row without a numeric time: ${JSON.stringify(h).slice(0, 160)}`, { exchange: "hyperliquid" });
+                last = Math.max(last, t);
+                if (!byTime.has(t)) {
+                    byTime.set(t, h);
+                    fresh++;
+                }
+            }
+            if (rows.length < HL_INFO_PAGE || fresh === 0)
+                break;
+            from = last;
+        }
+        return [...byTime.entries()].sort((a, b) => a[0] - b[0]).map(([, h]) => h);
+    }
     // ────────────────────────────────────────────────────────────
     //  Extended methods (from Python SDK / nktkas TS SDK analysis)
     // ────────────────────────────────────────────────────────────
@@ -1958,7 +2299,7 @@ export class HyperliquidAdapter {
      * 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.
@@ -2479,31 +2820,33 @@ export class HyperliquidAdapter {
         return this._sendExchangeAction({ type: "claimRewards" });
     }
     /**
-     * List all available HIP-3 deployed perp dexes.
+     * List the HIP-3 deployed perp dexes: allPerpMetas (universe per dex; index 0 = native perps)
+     * joined by index with perpDexs (name, deployer — live 2026-10-19 both list the dexes in the
+     * same order). `assets` holds the LIVE (non-delisted) assets only; `delistedAssets` the rest and
+     * `delisted` is true when every asset of the dex is delisted (km, flx, hyna, cash, vntl, abcd on
+     * 2026-10-19). Delisted dexes stay listed: accounts may still hold positions there.
      */
     async listDeployedDexes() {
-        const allMetas = await this._infoPost({ type: "allPerpMetas" });
+        const [allMetas, dexList] = await Promise.all([
+            this._infoPost({ type: "allPerpMetas" }),
+            withCache(`mkt:hl:${this._network}:perpDexs`, HL_MARKET_META_TTL_MS, () => this._infoPost({ type: "perpDexs" })),
+        ]);
         if (!Array.isArray(allMetas))
             return [];
         const dexes = [];
-        // allPerpMetas returns an array: [nativePerps, dex1, dex2, ...]
-        // Each entry has { universe, marginTables, collateralToken }
-        // Dex name is derived from the asset prefix (e.g., "xyz:TSLA" → "xyz")
-        // Skip index 0 (native/validator perps — no prefix)
         for (let i = 1; i < allMetas.length; i++) {
-            const meta = allMetas[i];
-            const universe = (meta.universe ?? []);
+            const universe = (allMetas[i]?.universe ?? []);
             if (universe.length === 0)
                 continue;
-            // Extract dex name from the first asset's prefix
             const firstAsset = universe[0].name;
             const colonIdx = firstAsset.indexOf(":");
-            const dexName = colonIdx > 0 ? firstAsset.slice(0, colonIdx) : `dex-${i}`;
-            dexes.push({
-                name: dexName,
-                deployer: "", // not exposed by API
-                assets: universe.map(a => a.name),
-            });
+            const prefix = colonIdx > 0 ? firstAsset.slice(0, colonIdx) : `dex-${i}`;
+            const entry = Array.isArray(dexList) ? dexList[i] : null;
+            // The deployer is read from the perpDexs entry of the same dex (by index, checked by name).
+            const deployer = entry?.name === prefix && typeof entry.deployer === "string" ? entry.deployer : "";
+            const live = universe.filter(a => a.isDelisted !== true).map(a => a.name);
+            const gone = universe.filter(a => a.isDelisted === true).map(a => a.name);
+            dexes.push({ name: prefix, deployer, assets: live, delistedAssets: gone, delisted: live.length === 0 });
         }
         return dexes;
     }
@@ -2574,6 +2917,11 @@ export class HyperliquidAdapter {
             // share an aggregated weight limit of 1200 per minute") → typed RATE_LIMITED.
             if (res.status === 429)
                 throw rateLimitedError("hyperliquid", res.headers.get("retry-after"), `info ${String(body.type)}: ${text}`);
+            // HTTP 422 "Failed to deserialize the JSON body into the target type" = the request is
+            // malformed (bad interval / field type, live 2026-10-19): a caller error, not retryable.
+            if (res.status === 422) {
+                throw new PerpError("INVALID_PARAMS", `Hyperliquid info ${String(body.type)} rejected the request (422): ${text.slice(0, 200)}`, { exchange: "hyperliquid" });
+            }
             throw new PerpError("EXCHANGE_ERROR", `Hyperliquid info ${String(body.type)} failed (${res.status}): ${text.slice(0, 200)}`, { exchange: "hyperliquid" });
         }
         return res.json();