perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/hyperliquid-outcome.js

@@ -0,0 +1,646 @@
+/**
+ * Hyperliquid Outcome Adapter (HIP-4).
+ *
+ * Composes with HyperliquidAdapter for signing. Asset id encoding:
+ *   100,000,000 + (10 * outcome + side)
+ *
+ * Coin name conventions:
+ *   - l2Book/candle/allMids: `#<encoding>` (e.g., `#10`)
+ *   - spotClearinghouseState balance: `+<encoding>` (e.g., `+10`)
+ *
+ * Outcome trades draw collateral from the spot balance of the outcome's own quote token —
+ * `outcomeMeta.outcomes[].quoteToken` (live 2026-10-12: "USDC" on every listed outcome; a USDH-only
+ * balance was refused by the venue "Insufficient spot balance asset=100014881"). Min order value:
+ * 10 quote tokens (docs error-responses MinTradeSpotNtl "Order must have minimum value of 10 {quote_token}.").
+ */
+import { PerpError } from "../errors.js";
+const OUTCOME_ASSET_OFFSET = 100_000_000;
+/** docs error-responses MinTradeSpotNtl: "Order must have minimum value of 10 {quote_token}." */
+const MIN_ORDER_QUOTE = 10;
+/** Outcome encoding `10*outcome + side` keeps side as the units digit, so
+ *  side must be 0..9 to avoid overflow into the next outcome's id space. */
+const MAX_SIDE = 9;
+/** Asset id offset spans `[100_000_000, 200_000_000)`, so encoding < 100M. */
+const MAX_ENCODING = 99_999_999;
+export class HyperliquidOutcomeAdapter {
+    name = "hyperliquid";
+    _hl;
+    _outcomeMeta = null;
+    _initialized = false;
+    constructor(hlAdapter) {
+        this._hl = hlAdapter;
+    }
+    async init() {
+        if (this._initialized)
+            return;
+        await this._loadOutcomeMeta();
+        this._initialized = true;
+    }
+    static encoding(outcome, side) {
+        return 10 * outcome + side;
+    }
+    static assetId(outcome, side) {
+        return OUTCOME_ASSET_OFFSET + HyperliquidOutcomeAdapter.encoding(outcome, side);
+    }
+    static mintCoin(outcome, side) {
+        return `#${HyperliquidOutcomeAdapter.encoding(outcome, side)}`;
+    }
+    static balanceCoin(outcome, side) {
+        return `+${HyperliquidOutcomeAdapter.encoding(outcome, side)}`;
+    }
+    /**
+     * Decode a balance coin name like `+10` back to (outcome, side).
+     * Returns null if the name does not match the outcome scheme.
+     */
+    static decodeBalanceCoin(coin) {
+        if (!coin.startsWith("+"))
+            return null;
+        const enc = Number(coin.slice(1));
+        if (!Number.isFinite(enc) || enc < 0)
+            return null;
+        return { outcome: Math.floor(enc / 10), side: enc % 10 };
+    }
+    static parseDescription(description) {
+        const parts = description.split("|");
+        const out = {};
+        for (const p of parts) {
+            const idx = p.indexOf(":");
+            if (idx < 0)
+                continue;
+            const key = p.slice(0, idx).trim();
+            const val = p.slice(idx + 1).trim();
+            if (key === "class")
+                out.class = val;
+            else if (key === "underlying")
+                out.underlying = val;
+            else if (key === "expiry")
+                out.expiryMs = HyperliquidOutcomeAdapter._parseExpiry(val);
+            else if (key === "targetPrice")
+                out.targetPrice = Number(val);
+            else if (key === "period")
+                out.period = val;
+        }
+        return out;
+    }
+    /**
+     * Compute the underlying mark-price view (gap / inTheMoney) for an outcome
+     * from a parsed description and the live allMids map.
+     *
+     * Pure helper — extracted from getView so the settlement-status logic is
+     * directly unit-testable.
+     *
+     * - HL `allMids` keys perps by bare symbol (e.g. "BTC"). HIP-3 perps use
+     *   "@dexIdx:SYMBOL" but those aren't referenced in HIP-4 outcomes yet.
+     * - For `class:priceBinary` the convention is Yes = "underlying >= target".
+     *   When `class` is missing or non-binary, `inTheMoney` stays null rather
+     *   than guessing (Rule #2 — no silent classification fallback).
+     * - Returns null when there is no underlying field to look up.
+     */
+    static _computeUnderlying(parsed, allMids) {
+        if (!parsed.underlying)
+            return null;
+        const sym = parsed.underlying.toUpperCase();
+        const markPrice = allMids[sym];
+        const target = parsed.targetPrice;
+        let gap;
+        let gapPct;
+        let inTheMoney = null;
+        if (markPrice !== undefined && target !== undefined) {
+            gap = Number(markPrice) - target;
+            gapPct = (gap / target) * 100;
+            if (parsed.class === "priceBinary" && Number.isFinite(gap)) {
+                inTheMoney = gap >= 0 ? "yes" : "no";
+            }
+        }
+        return {
+            symbol: sym,
+            source: sym,
+            markPrice,
+            targetPrice: target,
+            gap,
+            gapPct,
+            inTheMoney,
+        };
+    }
+    /**
+     * Sum of `impliedProb` across sides — for fair binary markets the sum
+     * should converge to ~1.0. Deviation hints at arbitrage or stale mids.
+     *
+     * Returns undefined when any side is missing impliedProb OR when any
+     * impliedProb is non-finite (NaN, Infinity). This means "we don't have a
+     * trustworthy view of the symmetry right now" rather than emitting NaN
+     * downstream (Rule #2 — no silent garbage propagation).
+     */
+    static _computeMidSum(sides) {
+        if (sides.length === 0)
+            return undefined;
+        for (const s of sides) {
+            if (s.impliedProb === undefined)
+                return undefined;
+            if (!Number.isFinite(s.impliedProb))
+                return undefined;
+        }
+        return sides.reduce((acc, s) => acc + (s.impliedProb ?? 0), 0);
+    }
+    /**
+     * Compute the time-status pair (`serverTime`, `msToExpiry`) for a view.
+     * Pure helper — takes `nowMs` as an argument so callers can inject a
+     * deterministic clock under test.
+     *
+     * `msToExpiry` is the raw signed delta `expiryMs - nowMs`:
+     *   positive  = unexpired
+     *   zero      = at expiry
+     *   negative  = already settled (caller decides UX)
+     *   undefined = unknown expiry
+     *
+     * Does NOT clamp negatives or treat them as "expired" — that
+     * classification is the caller's job (Rule #2 — no silent classification
+     * fallback in a low-level helper).
+     */
+    static _computeTimeStatus(expiryMs, nowMs) {
+        return {
+            serverTime: nowMs,
+            msToExpiry: expiryMs !== undefined ? expiryMs - nowMs : undefined,
+        };
+    }
+    /**
+     * Pure arithmetic gate for the (outcome, side) pair.
+     *
+     * Rejects NaN / non-integer / negative values immediately so the
+     * encoding formula `10 * outcome + side` never produces a garbage
+     * asset id silently. Does NOT consult outcomeMeta — that lookup is in
+     * the instance-level `_validateOutcomeSide` which composes this
+     * helper with the live registry check.
+     *
+     * Boundary: outcome=9_999_999, side=9 → encoding=99_999_999 = MAX_ENCODING (valid).
+     *           outcome=10_000_000, side=0 → encoding=100_000_000 > MAX_ENCODING (rejected).
+     */
+    static _assertOutcomeRange(outcome, side) {
+        if (!Number.isInteger(outcome) || outcome < 0) {
+            throw new PerpError("INVALID_PARAMS", `Outcome id must be a non-negative integer, got: ${outcome}`, { exchange: "hyperliquid" });
+        }
+        if (!Number.isInteger(side) || side < 0 || side > MAX_SIDE) {
+            throw new PerpError("INVALID_PARAMS", `Side must be an integer 0..${MAX_SIDE} (encoding scheme is single digit), got: ${side}`, { exchange: "hyperliquid" });
+        }
+        const encoding = HyperliquidOutcomeAdapter.encoding(outcome, side);
+        if (encoding > MAX_ENCODING) {
+            throw new PerpError("INVALID_PARAMS", `Encoding ${encoding} overflows the outcome asset block (max ${MAX_ENCODING})`, { exchange: "hyperliquid" });
+        }
+    }
+    /**
+     * Trim a raw orderbook to `depth` levels and surface best bid/ask.
+     *
+     * Throws (rather than silently coercing) when:
+     *  - `book.bids` or `book.asks` is missing/non-array (venue payload
+     *    malformed — Rule #2: don't fabricate an empty book)
+     *  - `depth` is not a non-negative integer (NaN, negative, Infinity,
+     *    fractional are all caller bugs that previously silently produced
+     *    `slice(0, NaN) === []` or `slice(0, -1)` = "all but last")
+     */
+    static _trimBook(book, depth) {
+        if (!book || !Array.isArray(book.bids) || !Array.isArray(book.asks)) {
+            throw new PerpError("EXCHANGE_ERROR", "Outcome orderbook response is missing bids/asks array", { exchange: "hyperliquid" });
+        }
+        if (!Number.isInteger(depth) || depth < 0) {
+            throw new PerpError("INVALID_PARAMS", `Depth must be a non-negative integer, got: ${depth}`, { exchange: "hyperliquid" });
+        }
+        const bids = book.bids.slice(0, depth);
+        const asks = book.asks.slice(0, depth);
+        return {
+            bids,
+            asks,
+            bestBid: bids[0]?.[0],
+            bestAsk: asks[0]?.[0],
+        };
+    }
+    /** Parse "20260504-0600" → ms-epoch (UTC). Returns undefined for malformed. */
+    static _parseExpiry(s) {
+        const m = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})$/.exec(s);
+        if (!m)
+            return undefined;
+        const [, y, mo, d, h, mi] = m;
+        const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi));
+        return Number.isFinite(ms) ? ms : undefined;
+    }
+    async _loadOutcomeMeta() {
+        const meta = await this._infoPost({ type: "outcomeMeta" });
+        if (!meta || typeof meta !== "object" || !("outcomes" in meta)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid outcomeMeta returned unexpected shape: ${JSON.stringify(meta).slice(0, 200)}`, { exchange: "hyperliquid" });
+        }
+        this._outcomeMeta = meta;
+    }
+    async getMarkets() {
+        await this.init();
+        if (!this._outcomeMeta)
+            return [];
+        const allMids = await this._infoPost({ type: "allMids" });
+        return this._outcomeMeta.outcomes.map((o) => {
+            const parsed = HyperliquidOutcomeAdapter.parseDescription(o.description);
+            const sides = o.sideSpecs.map((s, i) => {
+                const encoding = HyperliquidOutcomeAdapter.encoding(o.outcome, i);
+                return {
+                    side: i,
+                    name: s.name,
+                    encoding,
+                    assetId: OUTCOME_ASSET_OFFSET + encoding,
+                    mid: allMids[`#${encoding}`],
+                };
+            });
+            return {
+                outcome: o.outcome,
+                quoteToken: this.quoteTokenOf(o.outcome),
+                name: o.name,
+                description: o.description,
+                ...parsed,
+                sides,
+            };
+        });
+    }
+    async getPositions() {
+        await this.init();
+        // Bypass HL adapter's cached spot state — outcome positions change at
+        // every fill, and the spot cache TTL would surface stale data.
+        const userAddress = await this._resolveUserAddress();
+        const state = await this._infoPost({ type: "spotClearinghouseState", user: userAddress });
+        const balances = (state?.balances ?? []);
+        const allMidsPromise = this._infoPost({ type: "allMids" });
+        const positions = [];
+        for (const b of balances) {
+            const coin = String(b.coin ?? "");
+            const decoded = HyperliquidOutcomeAdapter.decodeBalanceCoin(coin);
+            if (!decoded)
+                continue;
+            const total = String(b.total ?? "0");
+            if (Number(total) === 0)
+                continue;
+            const sideName = this._lookupSideName(decoded.outcome, decoded.side);
+            positions.push({
+                outcome: decoded.outcome,
+                side: decoded.side,
+                sideName,
+                encoding: HyperliquidOutcomeAdapter.encoding(decoded.outcome, decoded.side),
+                size: total,
+                entryNotional: String(b.entryNtl ?? "0"),
+            });
+        }
+        if (positions.length === 0)
+            return [];
+        const allMids = await allMidsPromise;
+        for (const p of positions) {
+            const mark = allMids[`#${p.encoding}`];
+            if (mark) {
+                p.markPrice = mark;
+                p.unrealizedPnl = String(Number(mark) * Number(p.size) - Number(p.entryNotional));
+            }
+        }
+        return positions;
+    }
+    /**
+     * Assemble a combined view of one outcome: all sides' books in parallel,
+     * the underlying mark price (HL perp mid for `description.underlying`),
+     * gap vs targetPrice, time-to-expiry, and per-side implied probability.
+     *
+     * Outcome markets have a symmetric (Yes / No) structure where the prices
+     * sum to ~$1; this view exposes both sides in a single round-trip and
+     * also surfaces the directional context for binary markets — what BTC
+     * mark price would settle the contract right now.
+     */
+    async getView(outcome, depth = 10) {
+        await this.init();
+        const meta = this._outcomeMeta?.outcomes.find((o) => o.outcome === outcome);
+        if (!meta) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Unknown outcome id: ${outcome}`, {
+                exchange: "hyperliquid",
+                remediation: "Run: perp outcome list",
+            });
+        }
+        const parsed = HyperliquidOutcomeAdapter.parseDescription(meta.description);
+        // Fetch books for every side in parallel + allMids once for mids and
+        // the underlying symbol's mark price.
+        const allMidsPromise = this._infoPost({ type: "allMids" });
+        const bookPromises = meta.sideSpecs.map((_, i) => this.getOrderbook(outcome, i));
+        const [allMids, ...books] = await Promise.all([allMidsPromise, ...bookPromises]);
+        // Trim each book to `depth` levels and compute best bid/ask + implied prob.
+        const sides = meta.sideSpecs.map((spec, i) => {
+            const encoding = HyperliquidOutcomeAdapter.encoding(outcome, i);
+            const trimmed = HyperliquidOutcomeAdapter._trimBook(books[i], depth);
+            const mid = allMids[`#${encoding}`];
+            return {
+                side: i,
+                name: spec.name,
+                encoding,
+                assetId: OUTCOME_ASSET_OFFSET + encoding,
+                mid,
+                bids: trimmed.bids,
+                asks: trimmed.asks,
+                bestBid: trimmed.bestBid,
+                bestAsk: trimmed.bestAsk,
+                impliedProb: mid !== undefined ? Number(mid) : undefined,
+            };
+        });
+        const midSum = HyperliquidOutcomeAdapter._computeMidSum(sides);
+        // Underlying: HL perp mid for the parsed underlying symbol.
+        const underlying = HyperliquidOutcomeAdapter._computeUnderlying(parsed, allMids);
+        const { serverTime, msToExpiry } = HyperliquidOutcomeAdapter._computeTimeStatus(parsed.expiryMs, Date.now());
+        return {
+            outcome,
+            name: meta.name,
+            description: meta.description,
+            class: parsed.class,
+            expiryMs: parsed.expiryMs,
+            msToExpiry,
+            period: parsed.period,
+            underlying,
+            sides,
+            midSum,
+            serverTime,
+        };
+    }
+    async getOrderbook(outcome, side) {
+        await this.init();
+        this._validateOutcomeSide(outcome, side);
+        const coin = HyperliquidOutcomeAdapter.mintCoin(outcome, side);
+        const book = await this._infoPost({ type: "l2Book", coin });
+        // Rule #2: do NOT fabricate an empty book when the venue payload is
+        // malformed. Caller (typically getView) has its own gates downstream
+        // but a missing `levels` here is a venue contract break, not "no
+        // resting orders".
+        if (!book ||
+            !Array.isArray(book.levels) ||
+            !Array.isArray(book.levels[0]) ||
+            !Array.isArray(book.levels[1])) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid l2Book returned malformed payload for ${coin}: missing or non-array \`levels\``, { exchange: "hyperliquid" });
+        }
+        const levels = book.levels;
+        // Rule #2: `Number("abc") ?? 0` would silently coerce a non-numeric
+        // venue time to 0 (1970 epoch). 0 is a legitimate "no time given"
+        // value when book.time is undefined, but a NaN should not be hidden.
+        //
+        // Strict policy (qa/2026-05-16): empty string is corruption too —
+        // `Number("") === 0` would land in the same fake-1970-epoch bucket
+        // as the previous silent path. Treat "" the same as a non-numeric
+        // string, distinct from the legitimate undefined/null "no time given".
+        // The SDK types `book.time` as `number | undefined`, but the wire
+        // payload can return a string at runtime — we widen to unknown so the
+        // runtime guard against an empty string is meaningful (the SDK type
+        // would otherwise narrow it out).
+        const timeRaw = book.time;
+        if (timeRaw === "") {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid l2Book returned empty string for time on ${coin}`, { exchange: "hyperliquid" });
+        }
+        const time = timeRaw === undefined || timeRaw === null ? 0 : Number(timeRaw);
+        if (!Number.isFinite(time)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid l2Book returned non-finite time for ${coin}: ${timeRaw}`, { exchange: "hyperliquid" });
+        }
+        return {
+            outcome,
+            side,
+            time,
+            bids: levels[0].map((l) => [String(l.px ?? "0"), String(l.sz ?? "0")]),
+            asks: levels[1].map((l) => [String(l.px ?? "0"), String(l.sz ?? "0")]),
+        };
+    }
+    async placeOrder(opts) {
+        await this.init();
+        this._validateOutcomeSide(opts.outcome, opts.side);
+        const quote = this.quoteTokenOf(opts.outcome);
+        const notional = Number(opts.price) * Number(opts.size);
+        if (!Number.isFinite(notional) || notional < MIN_ORDER_QUOTE) {
+            throw new PerpError("INVALID_PARAMS", `Outcome order value must be at least ${MIN_ORDER_QUOTE} ${quote} (got price=${opts.price} * size=${opts.size} = ${notional.toFixed(4)})`, {
+                exchange: "hyperliquid",
+                remediation: `Increase price or size so price*size >= ${MIN_ORDER_QUOTE}`,
+            });
+        }
+        // Pre-check the quote-token spot balance (only on buy — sell consumes outcome shares).
+        if (opts.isBuy) {
+            const available = await this._getSpotAvailable(quote);
+            if (available < notional) {
+                throw new PerpError("INSUFFICIENT_BALANCE", `Insufficient ${quote} for outcome buy: need ${notional.toFixed(4)} ${quote}, have ${available.toFixed(4)} (spot)`, {
+                    exchange: "hyperliquid",
+                    remediation: `Outcome ${opts.outcome} is quoted in ${quote}: hold ${quote} on Hyperliquid spot (perp-to-spot transfer or a spot swap)`,
+                });
+            }
+        }
+        const assetId = HyperliquidOutcomeAdapter.assetId(opts.outcome, opts.side);
+        const tif = opts.tif ?? "Gtc";
+        const action = {
+            type: "order",
+            orders: [{
+                    a: assetId,
+                    b: opts.isBuy,
+                    p: this._trimZeros(opts.price),
+                    s: this._trimZeros(opts.size),
+                    r: false,
+                    t: { limit: { tif } },
+                }],
+            grouping: "na",
+        };
+        const result = await this._hl.exchangeAction(action);
+        HyperliquidOutcomeAdapter._assertOrderStatusOk(result);
+        await this._invalidateAccountCache();
+        return result;
+    }
+    async cancelOrder(outcome, side, oid) {
+        await this.init();
+        this._validateOutcomeSide(outcome, side);
+        const assetId = HyperliquidOutcomeAdapter.assetId(outcome, side);
+        const result = await this._hl.exchangeAction({
+            type: "cancel",
+            cancels: [{ a: assetId, o: oid }],
+        });
+        HyperliquidOutcomeAdapter._assertCancelStatusOk(result);
+        await this._invalidateAccountCache();
+        return result;
+    }
+    /**
+     * Throw if the venue rejected the order embedded inside a top-level
+     * `status:"ok"` response (HL pattern). Returns silently for resting/filled.
+     */
+    static _assertOrderStatusOk(result) {
+        const r = result;
+        const statuses = r?.response?.data?.statuses;
+        if (!Array.isArray(statuses) || statuses.length === 0) {
+            throw new PerpError("EXCHANGE_ERROR", `Outcome order: empty status response (${JSON.stringify(result).slice(0, 200)})`, { exchange: "hyperliquid" });
+        }
+        const st = statuses[0];
+        if (st.error) {
+            // A per-entry error inside status "ok" is the venue's definite refusal of THIS order (nothing
+            // placed) — never a retryable EXCHANGE_ERROR. Live 2026-10-12: "Insufficient spot balance asset=100014881".
+            const msg = String(st.error);
+            const insufficient = /insufficient/i.test(msg);
+            throw new PerpError(insufficient ? "INSUFFICIENT_BALANCE" : "ORDER_REJECTED", `Outcome order rejected: ${msg}`, {
+                exchange: "hyperliquid", venueError: msg,
+                ...(insufficient ? { remediation: "Check the outcome's quote token balance on Hyperliquid spot: perp outcome list (quote per outcome)" } : {}),
+            });
+        }
+    }
+    static _assertCancelStatusOk(result) {
+        const r = result;
+        const statuses = r?.response?.data?.statuses;
+        if (!Array.isArray(statuses) || statuses.length === 0) {
+            throw new PerpError("EXCHANGE_ERROR", `Outcome cancel: empty status response`, { exchange: "hyperliquid" });
+        }
+        const st = statuses[0];
+        if (typeof st === "object" && st !== null && "error" in st) {
+            const msg = String(st.error);
+            throw new PerpError("ORDER_REJECTED", `Outcome cancel rejected: ${msg}`, { exchange: "hyperliquid", venueError: msg });
+        }
+    }
+    async getOpenOrders() {
+        await this.init();
+        const orders = await this._hl.getOpenOrders();
+        return orders.filter((o) => typeof o.symbol === "string" && o.symbol.startsWith("#"));
+    }
+    // ── Private ──────────────────────────────────────────────────────────────
+    /**
+     * The outcome's quote token from outcomeMeta (`quoteToken`, e.g. "USDC"). Unknown outcome →
+     * SYMBOL_NOT_FOUND; missing / non-string quoteToken → EXCHANGE_ERROR (never an assumed token).
+     */
+    quoteTokenOf(outcome) {
+        const o = this._outcomeMeta?.outcomes.find((x) => x.outcome === outcome);
+        if (!o) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Unknown outcome id: ${outcome}`, { exchange: "hyperliquid", remediation: "Run: perp outcome list" });
+        }
+        if (typeof o.quoteToken !== "string" || o.quoteToken.trim() === "") {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid outcomeMeta outcome ${outcome} has no quoteToken (got ${JSON.stringify(o.quoteToken ?? null)}) — its collateral token is unknown`, { exchange: "hyperliquid" });
+        }
+        return o.quoteToken;
+    }
+    /**
+     * The outcome / side behind an outcome coin ("#14881" = outcome 1488, side 1) with its names from
+     * outcomeMeta; null when the coin is not an outcome coin or the outcome is not listed.
+     */
+    describeCoin(coin) {
+        if (!/^[#+]\d+$/.test(coin))
+            return null;
+        const enc = Number(coin.slice(1));
+        const outcome = Math.floor(enc / 10);
+        const side = enc % 10;
+        const o = this._outcomeMeta?.outcomes.find((x) => x.outcome === outcome);
+        const sideName = o?.sideSpecs[side]?.name;
+        if (!o || sideName === undefined)
+            return null;
+        return { outcome, side, name: o.name, sideName };
+    }
+    /**
+     * Price of held outcome balance coins (`+<encoding>`, spotClearinghouseState) in the outcome's quote
+     * token: the side's mid `allMids["#<encoding>"]` (docs info-endpoint "Retrieve mids for all coins";
+     * live 2026-10-13 mainnet allMids "#14880": "0.100405", "#14881": "0.899595"). HIP-4 docs: a side
+     * token settles to `settleFraction` (Yes) / `1 - settleFraction` (No) quote tokens and the Yes/No
+     * books are merged (buy Yes at p = sell No at 1 - p), so the mid is the token's value in its quote.
+     * `quoteToken` null = the outcome / side is not in outcomeMeta (outcomeMeta is re-read once when a
+     * coin's outcome is missing — outcomes are deployed after init) or has no quoteToken; `mid` null = no
+     * positive mid. Coins that are not `+<digits>` are not returned. A malformed allMids → EXCHANGE_ERROR.
+     */
+    async getBalanceCoinPrices(coins) {
+        await this.init();
+        const held = coins.filter((c) => /^\+\d+$/.test(c)).map((coin) => {
+            const enc = Number(coin.slice(1));
+            return { coin, outcome: Math.floor(enc / 10), side: enc % 10, enc };
+        });
+        if (held.length === 0)
+            return [];
+        const find = (outcome) => this._outcomeMeta?.outcomes.find((x) => x.outcome === outcome);
+        if (held.some((h) => find(h.outcome) === undefined))
+            await this._loadOutcomeMeta();
+        const allMids = await this._infoPost({ type: "allMids" });
+        if (allMids === null || typeof allMids !== "object" || Array.isArray(allMids)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid allMids returned unexpected shape: ${JSON.stringify(allMids).slice(0, 200)}`, { exchange: "hyperliquid" });
+        }
+        const mids = allMids;
+        return held.map((h) => {
+            const o = find(h.outcome);
+            const quoteToken = o !== undefined && h.side < o.sideSpecs.length && typeof o.quoteToken === "string" && o.quoteToken.trim() !== ""
+                ? o.quoteToken : null;
+            const raw = mids[`#${h.enc}`];
+            const mid = typeof raw === "string" && Number(raw) > 0 ? raw : null;
+            return { coin: h.coin, quoteToken, mid };
+        });
+    }
+    _lookupSideName(outcome, side) {
+        const o = this._outcomeMeta?.outcomes.find((x) => x.outcome === outcome);
+        return o?.sideSpecs[side]?.name ?? `side${side}`;
+    }
+    _validateOutcomeSide(outcome, side) {
+        HyperliquidOutcomeAdapter._assertOutcomeRange(outcome, side);
+        const o = this._outcomeMeta?.outcomes.find((x) => x.outcome === outcome);
+        if (!o) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Unknown outcome id: ${outcome}`, {
+                exchange: "hyperliquid",
+                remediation: "Run: perp outcome list",
+            });
+        }
+        if (side >= o.sideSpecs.length) {
+            throw new PerpError("INVALID_PARAMS", `Invalid side ${side} for outcome ${outcome} (valid: 0..${o.sideSpecs.length - 1})`, {
+                exchange: "hyperliquid",
+                remediation: "Run: perp outcome list",
+            });
+        }
+    }
+    /**
+     * Resolve the master EVM address for spot-clearinghouse queries.
+     * `HyperliquidAdapter._address` is populated only when a master/PK signer
+     * is configured. Agent-only setups (no master pk in OWS) leave it empty
+     * even though the agent meta knows the user's EVM address. Fall through
+     * to the agent registry rather than treating empty as zero balance —
+     * Rule #2: no silent fallback.
+     */
+    async _resolveUserAddress() {
+        if (this._hl.address)
+            return this._hl.address;
+        const { getAgent } = await import("../agent-wallet/store.js");
+        const agent = getAgent("hyperliquid");
+        if (agent?.userEvmAddress)
+            return agent.userEvmAddress;
+        throw new PerpError("NO_SIGNER_AVAILABLE", "Hyperliquid user address not resolved — cannot query the spot balance state", { exchange: "hyperliquid", remediation: "Configure an OWS master wallet or register an HL agent" });
+    }
+    /**
+     * Available spot balance of `coin` (total − hold, spotClearinghouseState). A coin the account does
+     * not hold is not listed → 0 held. No balances list, or an unreadable total / hold → EXCHANGE_ERROR.
+     */
+    async _getSpotAvailable(coin) {
+        const userAddress = await this._resolveUserAddress();
+        const state = await this._infoPost({ type: "spotClearinghouseState", user: userAddress });
+        if (!Array.isArray(state?.balances)) {
+            throw new PerpError("EXCHANGE_ERROR", "Hyperliquid spotClearinghouseState has no balances list", { exchange: "hyperliquid" });
+        }
+        const row = state.balances.find((b) => String(b.coin) === coin);
+        if (!row)
+            return 0;
+        const total = Number(row.total);
+        const hold = Number(row.hold);
+        if (!Number.isFinite(total) || !Number.isFinite(hold)) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid spot ${coin} balance unreadable (total ${JSON.stringify(row.total)}, hold ${JSON.stringify(row.hold)})`, { exchange: "hyperliquid" });
+        }
+        return Math.max(0, total - hold);
+    }
+    async _invalidateAccountCache() {
+        try {
+            const { invalidateCache } = await import("../cache.js");
+            invalidateCache("acct");
+        }
+        catch {
+            // Cache module unavailable in test contexts; ignore.
+        }
+    }
+    _trimZeros(s) {
+        if (!s.includes("."))
+            return s;
+        const n = s.replace(/\.?0+$/, "");
+        return n === "" || n === "-0" ? "0" : n;
+    }
+    async _infoPost(body) {
+        const baseUrl = this._hl.isTestnet
+            ? "https://api.hyperliquid-testnet.xyz"
+            : "https://api.hyperliquid.xyz";
+        const res = await fetch(`${baseUrl}/info`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid /info HTTP ${res.status} for ${JSON.stringify(body)}`, { exchange: "hyperliquid", status: res.status });
+        }
+        return res.json();
+    }
+}