@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/venues/hyperliquid/hl-private.js

@@ -0,0 +1,357 @@
+// Hyperliquid signed-action client — the HL mirror of `ccxt/binance-private.ts`.
+//
+// CONTRACTS THIS FILE INHERITS FROM THE BINANCE SIDE (non-negotiable — the shared
+// adapter-contract suite runs against both):
+//   ★ null ≠ empty. EVERY read returns `null` on a FAILED fetch, never `[]`.
+//     `[]` means "the exchange said: nothing". Callers make destructive decisions
+//     (cancel a bracket, close a position, trust a snapshot) on that difference.
+//   ★ Reads are pre-gated (`assertNotLimited`), order/cancel paths are NOT (an
+//     exit must never be blocked by our own pacer) but every path arms the gate
+//     via `noteError`.
+//
+// HYPERLIQUID-SPECIFIC LANDMINES (all verified live on testnet 2026-07-12):
+//   ★ ccxt AUTO-MONETIZES an authed HL client — `initializeClient()` enrolls
+//     CCXT's own builder fee (1bp/order) + referral code on the first signed call.
+//     `options.{builderFee:false, refSet:true}` disables both. A test pins this.
+//   ★ Market orders REQUIRE a reference price (ccxt derives the slippage cap from
+//     it) — `createOrder(sym,'market',side,size)` with no price THROWS client-side.
+//     There is no native market order on HL: it is an IOC limit at a bounded price.
+//   ★ Signed actions carry a NONCE (epoch ms) and HL keeps only the 100 highest
+//     per signer. Two actions signed in the same millisecond can collide → every
+//     signed action goes through a monotonic-nonce MUTEX (one in-flight at a time,
+//     strictly increasing ms). This is why `submitOrders` batches a bracket pair
+//     into ONE action rather than firing two.
+//   ★ Agent (API) wallets can only TRADE. `usdClassTransfer`/withdraw are
+//     user-signed actions and fail with "Must deposit before performing actions"
+//     when signed by an agent. We never call them.
+import { createRequire } from 'node:module';
+import { logger } from '../../logger.js';
+import { toCcxtSymbol } from '../symbols.js';
+import { assertNotLimited, noteError, noteSuccess, exchangeIpWeight, updateAddressBudget, } from './hl-rate-gate.js';
+import { isValidHlCloid } from './hl-cloid.js';
+// ccxt via CJS require — OpenClaw's ESM loader yields the wrong module shape
+// (same rationale as binance-private.ts / hl-public.ts).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let ccxtCjs;
+try {
+    const _require = createRequire(import.meta.url);
+    ccxtCjs = _require('ccxt');
+}
+catch {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ccxtCjs = require('ccxt');
+}
+const TAG = 'hl-private';
+/** The CCXT options that MUST be present on every authed HL client. Exported so
+ *  `hl-private.test.ts` can assert them — if a future ccxt bump changes the
+ *  option names, the test fails rather than the users paying a silent 1bp. */
+export const HL_REQUIRED_OPTIONS = {
+    builderFee: false,
+    refSet: true,
+};
+/**
+ * Serializes every signed action behind a monotonic nonce.
+ *
+ * HL keeps the 100 highest nonces per signer and rejects repeats; two actions
+ * signed inside the same millisecond can therefore collide and one is silently
+ * lost. Rather than hand-rolling nonces (ccxt owns that), we guarantee that no
+ * two signed actions are ever *issued* in the same millisecond from this process:
+ * each waits for the previous to settle AND for the clock to advance.
+ */
+class NonceMutex {
+    chain = Promise.resolve();
+    lastIssuedMs = 0;
+    run(fn) {
+        const next = this.chain.then(async () => {
+            const now = Date.now();
+            if (now <= this.lastIssuedMs) {
+                // Same-ms collision guard: wait out the millisecond.
+                await new Promise((r) => setTimeout(r, this.lastIssuedMs - now + 1));
+            }
+            this.lastIssuedMs = Date.now();
+            return fn();
+        });
+        // Keep the chain alive even when a link rejects (otherwise one failed action
+        // would poison every later one).
+        this.chain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}
+export class HyperliquidPrivateApi {
+    creds;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    exchange;
+    mutex = new NonceMutex();
+    marketsLoaded = false;
+    constructor(creds) {
+        this.creds = creds;
+        if (!creds.walletAddress || !creds.agentPrivateKey) {
+            throw new Error('HyperliquidPrivateApi requires walletAddress + agentPrivateKey');
+        }
+        this.exchange = new ccxtCjs.hyperliquid({
+            walletAddress: creds.walletAddress,
+            privateKey: creds.agentPrivateKey,
+            options: { ...HL_REQUIRED_OPTIONS },
+            enableRateLimit: true,
+        });
+        if (creds.testnet) {
+            this.exchange.setSandboxMode(true);
+            const url = JSON.stringify(this.exchange.urls?.api ?? '');
+            if (!url.includes('testnet')) {
+                throw new Error(`HL testnet requested but sandbox URL is not testnet: ${url.slice(0, 80)}`);
+            }
+        }
+        logger.info(TAG, `Hyperliquid private API initialized (${creds.testnet ? 'TESTNET' : 'MAINNET'}, master ${creds.walletAddress.slice(0, 8)}…)`);
+    }
+    /** Exposed for the options-pin test + diagnostics. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getExchange() {
+        return this.exchange;
+    }
+    async loadMarkets() {
+        try {
+            assertNotLimited('meta');
+            await this.exchange.loadMarkets();
+            noteSuccess('meta');
+            this.marketsLoaded = true;
+            return true;
+        }
+        catch (err) {
+            noteError(err, 'loadMarkets');
+            logger.error(TAG, `loadMarkets failed: ${msg(err)}`);
+            return false;
+        }
+    }
+    // ---- Reads (null on failure — NEVER []) ----
+    /** Positions for the MASTER account. `null` = fetch failed (state unknown);
+     *  `[]` = the exchange confirmed flat. */
+    async fetchPositions(symbol) {
+        try {
+            assertNotLimited('clearinghouseState');
+            const symbols = symbol ? [toCcxtSymbol('hyperliquid', symbol)] : undefined;
+            const raw = await this.exchange.fetchPositions(symbols);
+            noteSuccess('clearinghouseState');
+            if (!Array.isArray(raw))
+                return null;
+            return raw.filter((p) => Math.abs(Number(p.contracts ?? 0)) > 0);
+        }
+        catch (err) {
+            noteError(err, 'fetchPositions');
+            logger.error(TAG, `fetchPositions failed: ${msg(err)}`);
+            return null;
+        }
+    }
+    /** Open orders INCLUDING trigger/TPSL legs. CCXT's HL `fetchOpenOrders`
+     *  defaults to `frontendOpenOrders`, which is the only endpoint that returns
+     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints. */
+    async fetchOpenOrders(symbol) {
+        try {
+            assertNotLimited('frontendOpenOrders');
+            const s = symbol ? toCcxtSymbol('hyperliquid', symbol) : undefined;
+            const raw = await this.exchange.fetchOpenOrders(s);
+            noteSuccess('frontendOpenOrders');
+            return Array.isArray(raw) ? raw : null;
+        }
+        catch (err) {
+            noteError(err, 'fetchOpenOrders');
+            logger.error(TAG, `fetchOpenOrders failed: ${msg(err)}`);
+            return null;
+        }
+    }
+    async fetchBalance() {
+        try {
+            assertNotLimited('clearinghouseState');
+            const raw = await this.exchange.fetchBalance();
+            noteSuccess('clearinghouseState');
+            return raw ?? null;
+        }
+        catch (err) {
+            noteError(err, 'fetchBalance');
+            logger.error(TAG, `fetchBalance failed: ${msg(err)}`);
+            return null;
+        }
+    }
+    /** Per-order status — the liveness resolver's REST tier (Tier 2 of the
+     *  3-tier rule). Weight 2. `null` = lookup FAILED (unknown), which callers
+     *  must treat as "do not act", NOT as "gone". */
+    async fetchOrder(orderId, symbol) {
+        try {
+            assertNotLimited('orderStatus');
+            const s = symbol ? toCcxtSymbol('hyperliquid', symbol) : undefined;
+            const raw = await this.exchange.fetchOrder(orderId, s);
+            noteSuccess('orderStatus');
+            return raw ?? null;
+        }
+        catch (err) {
+            noteError(err, 'fetchOrder');
+            logger.warn(TAG, `fetchOrder(${orderId}) failed: ${msg(err)}`);
+            return null;
+        }
+    }
+    /** Own fills. WS is the authoritative ingress (plan + the audit-trail rule);
+     *  this is the gap-fill/truth-check path. NOTE: only the 10,000 most recent
+     *  fills exist server-side — deep history is NOT queryable on HL, which is why
+     *  the `trades` table must be WS-first. */
+    async fetchMyTrades(symbol, since, limit = 100) {
+        try {
+            assertNotLimited('userFills');
+            const s = symbol ? toCcxtSymbol('hyperliquid', symbol) : undefined;
+            const raw = await this.exchange.fetchMyTrades(s, since, limit);
+            noteSuccess('userFills');
+            return Array.isArray(raw) ? raw : null;
+        }
+        catch (err) {
+            noteError(err, 'fetchMyTrades');
+            logger.error(TAG, `fetchMyTrades failed: ${msg(err)}`);
+            return null;
+        }
+    }
+    /** Refresh the ADDRESS action budget (the starvation guard). Weight 20 — call
+     *  every ~5 min, never per-heartbeat. */
+    async refreshAddressBudget() {
+        try {
+            assertNotLimited('userRateLimit');
+            const res = await this.rawInfo({ type: 'userRateLimit', user: this.creds.walletAddress });
+            noteSuccess('userRateLimit');
+            const used = Number(res?.nRequestsUsed);
+            const cap = Number(res?.nRequestsCap);
+            if (Number.isFinite(used) && Number.isFinite(cap)) {
+                updateAddressBudget({ nRequestsUsed: used, nRequestsCap: cap });
+            }
+        }
+        catch (err) {
+            noteError(err, 'userRateLimit');
+            logger.warn(TAG, `refreshAddressBudget failed: ${msg(err)}`);
+        }
+    }
+    /** Raw `POST /info` — for the handful of reads CCXT doesn't expose
+     *  (userRateLimit, userNonFundingLedgerUpdates, portfolio). Never used for
+     *  signed actions. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async rawInfo(body) {
+        const base = this.creds.testnet
+            ? 'https://api.hyperliquid-testnet.xyz'
+            : 'https://api.hyperliquid.xyz';
+        const res = await fetch(`${base}/info`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok)
+            throw new Error(`POST /info ${String(body.type)} → ${res.status}`);
+        return res.json();
+    }
+    // ---- Signed actions (NEVER pre-gated; always nonce-serialized) ----
+    /** Submit one order. Market orders are IOC-limit emulated — `price` is
+     *  MANDATORY (ccxt throws without it) and the caller must already have applied
+     *  the slippage bound + HL rounding (hl-precision). */
+    async submitOrder(req) {
+        if (req.cloid && !isValidHlCloid(req.cloid)) {
+            throw new Error(`Invalid HL cloid ${req.cloid} — must be 0x + 32 hex chars`);
+        }
+        return this.mutex.run(async () => {
+            try {
+                const params = this.buildParams(req);
+                const order = await this.exchange.createOrder(toCcxtSymbol('hyperliquid', req.symbol), req.type === 'market' ? 'market' : 'limit', req.side, req.amount, req.price, // ★ always passed — ccxt needs it even for 'market'
+                params);
+                noteSuccess('exchange', { ipWeight: exchangeIpWeight(1), addressActions: 1 });
+                return order ?? null;
+            }
+            catch (err) {
+                noteError(err, 'submitOrder');
+                // Order paths RETHROW (the caller must see a rejection) — unlike reads,
+                // which collapse to null.
+                throw err;
+            }
+        });
+    }
+    /** Submit N orders as ONE signed action (one nonce, one `/exchange` call).
+     *  This is how a bracket pair (SL+TP) is placed: atomic-ish, and it costs 1 IP
+     *  weight unit but N address actions. */
+    async submitOrders(reqs) {
+        if (reqs.length === 0)
+            return [];
+        for (const r of reqs) {
+            if (r.cloid && !isValidHlCloid(r.cloid)) {
+                throw new Error(`Invalid HL cloid ${r.cloid} — must be 0x + 32 hex chars`);
+            }
+        }
+        return this.mutex.run(async () => {
+            try {
+                const ccxtReqs = reqs.map((r) => ({
+                    symbol: toCcxtSymbol('hyperliquid', r.symbol),
+                    type: r.type === 'market' ? 'market' : 'limit',
+                    side: r.side,
+                    amount: r.amount,
+                    price: r.price,
+                    params: this.buildParams(r),
+                }));
+                const orders = await this.exchange.createOrders(ccxtReqs);
+                noteSuccess('exchange', {
+                    ipWeight: exchangeIpWeight(reqs.length),
+                    addressActions: reqs.length, // ★ batches cost n against the ADDRESS budget
+                });
+                return Array.isArray(orders) ? orders : null;
+            }
+            catch (err) {
+                noteError(err, 'submitOrders');
+                throw err;
+            }
+        });
+    }
+    async cancelOrder(orderId, symbol) {
+        return this.mutex.run(async () => {
+            try {
+                const res = await this.exchange.cancelOrder(orderId, toCcxtSymbol('hyperliquid', symbol));
+                noteSuccess('exchange', { ipWeight: exchangeIpWeight(1), addressActions: 1 });
+                return res ?? null;
+            }
+            catch (err) {
+                noteError(err, 'cancelOrder');
+                throw err;
+            }
+        });
+    }
+    /** Cancel by cloid — the bracket path's cancel (we always know our own cloid,
+     *  and it survives a restart because it is derived, not stored). */
+    async cancelOrderByCloid(cloid, symbol) {
+        return this.mutex.run(async () => {
+            try {
+                const res = await this.exchange.cancelOrder(cloid, toCcxtSymbol('hyperliquid', symbol), { clientOrderId: cloid });
+                noteSuccess('exchange', { ipWeight: exchangeIpWeight(1), addressActions: 1 });
+                return res ?? null;
+            }
+            catch (err) {
+                noteError(err, 'cancelOrderByCloid');
+                throw err;
+            }
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    buildParams(req) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const params = {};
+        if (req.reduceOnly)
+            params.reduceOnly = true;
+        if (req.postOnly)
+            params.postOnly = true; // → ALO
+        if (req.cloid)
+            params.clientOrderId = req.cloid;
+        if (req.trigger) {
+            // HL trigger orders fire on MARK price only (no workingType choice).
+            params.triggerPrice = req.trigger.triggerPrice;
+            if (req.trigger.tpsl === 'tp')
+                params.takeProfitPrice = req.trigger.triggerPrice;
+            else
+                params.stopLossPrice = req.trigger.triggerPrice;
+        }
+        return params;
+    }
+    get isMarketsLoaded() {
+        return this.marketsLoaded;
+    }
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/venues/hyperliquid/hl-public.d.ts

@@ -15,6 +15,9 @@ export declare class HyperliquidPublicApi implements PublicMarketDataApi {
     /** One upstream fetchTickers call serves every symbol within the TTL. */
     private tickersCache;
     private tickersInflight;
+    /** Coin → mid from one weight-2 allMids call (fetchTicker's price source). */
+    private midsCache;
+    private midsInflight;
     constructor(opts?: HyperliquidPublicApiOptions);
     private baseUrl;
     /** Canonical/ccxt symbol → this venue's ccxt symbol, or null (logged) when
@@ -24,11 +27,24 @@ export declare class HyperliquidPublicApi implements PublicMarketDataApi {
     /** Fetch-all-tickers with a short TTL + inflight dedup. Returns a map keyed
      *  by ccxt symbol, or null on failure. */
     private getTickers;
+    /** Coin → mid price from one weight-2 `allMids` call (TTL-cached, inflight-
+     *  deduped; docs: hyperliquid.gitbook.io → Info endpoint → "Retrieve mids
+     *  for all coins"). Null on ANY failure — callers fall back to the full
+     *  snapshot path. Spot entries (`@<idx>` keys) parse fine and are simply
+     *  never looked up (we key by perp coin name). */
+    private getMids;
+    /** Fire-and-forget full-snapshot refresh once it ages past
+     *  FULL_SNAPSHOT_REFRESH_MS — fetchTicker must never block on the heavy
+     *  fetchTickers call when a fresh mid is available. getTickers' own
+     *  inflight dedup + error handling make this safe to kick repeatedly. */
+    private maybeRefreshSnapshot;
     fetchTickerRaw(symbol: string): Promise<Record<string, any> | null>;
-    /** Ticker from the cached all-assets snapshot. Hyperliquid's asset contexts
-     *  carry mark/mid rather than a trade-tape bid/ask; absent fields fall back
-     *  to `last` with zero modeled spread — the paper fill engine models
-     *  slippage itself (same convention as IntelPublicApi). */
+    /** Price from the weight-2 allMids fast path; volume/change context from
+     *  the last full snapshot (background-refreshed). Hyperliquid's asset
+     *  contexts carry mark/mid rather than a trade-tape bid/ask; absent fields
+     *  fall back to `last` with zero modeled spread — the paper fill engine
+     *  models slippage itself (same convention as IntelPublicApi). Falls back
+     *  to the original blocking full-snapshot path when allMids fails. */
     fetchTicker(symbol: string): Promise<CcxtTicker | null>;
     fetchFundingRate(symbol: string): Promise<Record<string, any> | null>;
     fetchOpenInterest(symbol: string): Promise<Record<string, any> | null>;
@@ -49,4 +65,15 @@ export declare class HyperliquidPublicApi implements PublicMarketDataApi {
         outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
         driftMs: number | null;
     }>;
+    /** `meta` — the asset universe (szDecimals, maxLeverage, positional assetIndex).
+     *  Keyless info read, weight 20. Feeds HyperliquidInfoCache. Returns null on any
+     *  failure (never a partial universe — a half-loaded rules table would silently
+     *  reject orders). */
+    fetchMeta(): Promise<any | null>;
+    /** ★ MARK price — the price HL trigger orders fire on (there is no workingType
+     *  choice on this venue). Stop-distance validation and every trigger MUST use
+     *  this, never `last`: the mark is a CEX-composite median that can diverge from
+     *  HL's own last trade. Sourced from `metaAndAssetCtxs` (one weight-20 call
+     *  covers every asset). Returns null on failure — never a stale guess. */
+    fetchMarkPrice(symbol: string): Promise<number | null>;
 }

package/venues/hyperliquid/hl-public.js

@@ -9,12 +9,18 @@
 //     api.hyperliquid-testnet.xyz). CCXT@4.5.37 wraps everything we need.
 //   - `exchangeStatus` (weight 2) returns `{specialStatuses, time}` — the
 //     reachability probe AND a clock-drift source in one call.
-//   - metaAndAssetCtxs-class info requests are weight 20 and return data for
-//     ALL assets at once → fetchTicker is served from one cached fetchTickers
-//     upstream call (TTL below), so N symbols cost the same as one. The full
-//     address/IP rate gate is a Phase 3 concern (live cadences); paper-mode
-//     cadence here is bounded by the cache: ≤ (60s/TTL) weight-20 calls/min
-//     (~300/1200 IP budget at the 4s default).
+//   - `allMids` (weight 2) returns the mid price for EVERY coin in one call —
+//     the docs' recommended price read (plan §3: ccxt fetchTicker is
+//     'emulated' — prefer allMids). fetchTicker serves its PRICE from one
+//     TTL-cached allMids call; volume/change context rides the last full
+//     fetchTickers snapshot, refreshed in the background at most every
+//     FULL_SNAPSHOT_REFRESH_MS. Why the split: ccxt@4.5.37's hyperliquid
+//     fetchTickers() literally calls fetchMarkets() — the full perp+spot
+//     meta/ctx pipeline — measured ~13s on the first HL soak box, which
+//     starved every 10s-timeout skill-poller call 100% of the time. allMids
+//     measured ~1.4s on the same box. The full address/IP rate gate is a
+//     Phase 3 concern (live cadences); paper-mode cadence here is bounded by
+//     the caches: ≤ (60s/TTL) weight-2 calls/min + ≤ weight-20 every 5 min.
 //   - CCXT auto-monetization landmine (plan §3.8): initializeClient() only
 //     fires on AUTHENTICATED clients, and this class is keyless — but we pin
 //     `builderFee:false, refSet:true` in options anyway so a future
@@ -25,8 +31,8 @@
 // never throw to consumers. Binance-shaped symbols (…/USDT) are a caller bug
 // on this venue — logged clearly, null returned (never silently translated).
 import { createRequire } from 'node:module';
-import { toCcxtSymbol } from '@reefclaw/shared';
 import { logger } from '../../logger.js';
+import { toCcxtSymbol, toHyperliquidCoin } from '../symbols.js';
 const TAG = 'hl-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // (same pattern as binance-public.ts / binance-private.ts).
@@ -44,6 +50,11 @@ catch {
 const HL_MAINNET_API = 'https://api.hyperliquid.xyz';
 const HL_TESTNET_API = 'https://api.hyperliquid-testnet.xyz';
 const DEFAULT_TICKER_TTL_MS = 4_000;
+/** How stale the full fetchTickers snapshot (volume/change context) may get
+ *  before fetchTicker kicks a background refresh. Deliberately long: the
+ *  snapshot's ccxt call re-runs the whole fetchMarkets pipeline (weight ~60,
+ *  ~13s on a slow host) and nothing price-critical reads these fields. */
+const FULL_SNAPSHOT_REFRESH_MS = 300_000;
 function resolveTickerTtlMs() {
     const raw = Number(process.env.RC_HL_TICKER_TTL_MS);
     if (!Number.isFinite(raw) || raw < 500)
@@ -59,6 +70,9 @@ export class HyperliquidPublicApi {
     /** One upstream fetchTickers call serves every symbol within the TTL. */
     tickersCache = null;
     tickersInflight = null;
+    /** Coin → mid from one weight-2 allMids call (fetchTicker's price source). */
+    midsCache = null;
+    midsInflight = null;
     constructor(opts = {}) {
         this.testnet = opts.testnet === true;
         this.fetchImpl = opts.fetchImpl ?? fetch;
@@ -127,6 +141,56 @@ export class HyperliquidPublicApi {
         })();
         return this.tickersInflight;
     }
+    /** Coin → mid price from one weight-2 `allMids` call (TTL-cached, inflight-
+     *  deduped; docs: hyperliquid.gitbook.io → Info endpoint → "Retrieve mids
+     *  for all coins"). Null on ANY failure — callers fall back to the full
+     *  snapshot path. Spot entries (`@<idx>` keys) parse fine and are simply
+     *  never looked up (we key by perp coin name). */
+    async getMids() {
+        const now = Date.now();
+        if (this.midsCache && now - this.midsCache.at < this.tickerTtlMs) {
+            return this.midsCache.byCoin;
+        }
+        if (this.midsInflight)
+            return this.midsInflight;
+        this.midsInflight = (async () => {
+            try {
+                const raw = await this.exchange.publicPostInfo({ type: 'allMids' });
+                const byCoin = new Map();
+                for (const [coin, mid] of Object.entries(raw ?? {})) {
+                    const n = Number(mid);
+                    if (Number.isFinite(n) && n > 0)
+                        byCoin.set(coin, n);
+                }
+                if (byCoin.size === 0) {
+                    logger.warn(TAG, 'allMids returned no parseable mids');
+                    return null;
+                }
+                this.midsCache = { at: Date.now(), byCoin };
+                return byCoin;
+            }
+            catch (err) {
+                logger.error(TAG, `allMids failed: ${err instanceof Error ? err.message : String(err)}`);
+                return null;
+            }
+            finally {
+                this.midsInflight = null;
+            }
+        })();
+        return this.midsInflight;
+    }
+    /** Fire-and-forget full-snapshot refresh once it ages past
+     *  FULL_SNAPSHOT_REFRESH_MS — fetchTicker must never block on the heavy
+     *  fetchTickers call when a fresh mid is available. getTickers' own
+     *  inflight dedup + error handling make this safe to kick repeatedly. */
+    maybeRefreshSnapshot() {
+        const at = this.tickersCache?.at ?? 0;
+        if (Date.now() - at < FULL_SNAPSHOT_REFRESH_MS)
+            return;
+        if (this.tickersInflight)
+            return;
+        void this.getTickers();
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async fetchTickerRaw(symbol) {
         const vs = this.venueSymbol(symbol, 'fetchTickerRaw');
@@ -135,14 +199,36 @@ export class HyperliquidPublicApi {
         const tickers = await this.getTickers();
         return tickers?.get(vs) ?? null;
     }
-    /** Ticker from the cached all-assets snapshot. Hyperliquid's asset contexts
-     *  carry mark/mid rather than a trade-tape bid/ask; absent fields fall back
-     *  to `last` with zero modeled spread — the paper fill engine models
-     *  slippage itself (same convention as IntelPublicApi). */
+    /** Price from the weight-2 allMids fast path; volume/change context from
+     *  the last full snapshot (background-refreshed). Hyperliquid's asset
+     *  contexts carry mark/mid rather than a trade-tape bid/ask; absent fields
+     *  fall back to `last` with zero modeled spread — the paper fill engine
+     *  models slippage itself (same convention as IntelPublicApi). Falls back
+     *  to the original blocking full-snapshot path when allMids fails. */
     async fetchTicker(symbol) {
         const vs = this.venueSymbol(symbol, 'fetchTicker');
         if (!vs)
             return null;
+        const coin = toHyperliquidCoin(symbol);
+        const mids = await this.getMids();
+        const mid = mids?.get(coin);
+        if (mid !== undefined) {
+            this.maybeRefreshSnapshot();
+            const base = this.tickersCache?.bySymbol.get(vs);
+            const timestamp = this.midsCache?.at ?? Date.now();
+            return {
+                symbol,
+                last: mid,
+                bid: mid,
+                ask: mid,
+                baseVolume: Number(base?.baseVolume ?? 0) || 0,
+                quoteVolume: Number(base?.quoteVolume ?? 0) || 0,
+                change: Number(base?.change ?? 0) || 0,
+                percentage: Number(base?.percentage ?? 0) || 0,
+                timestamp,
+                datetime: new Date(timestamp).toISOString(),
+            };
+        }
         const tickers = await this.getTickers();
         const raw = tickers?.get(vs);
         if (!raw) {
@@ -155,7 +241,14 @@ export class HyperliquidPublicApi {
             logger.warn(TAG, `fetchTicker(${symbol}) — no usable price on ticker`);
             return null;
         }
-        const timestamp = Number.isFinite(raw.timestamp) ? Number(raw.timestamp) : Date.now();
+        // Timestamp honesty (issue #202): this fallback serves the background-
+        // refreshed FULL SNAPSHOT price, which can be minutes old. When the raw
+        // ticker carries no timestamp, stamp the snapshot's fetch time — never
+        // Date.now(), which would disguise a stale price as fresh and defeat the
+        // paper engine's stale-quote fill guard.
+        const timestamp = Number.isFinite(raw.timestamp)
+            ? Number(raw.timestamp)
+            : this.tickersCache?.at ?? Date.now();
         return {
             // Key on the symbol the CALLER used so per-symbol maps line up.
             symbol,
@@ -282,4 +375,62 @@ export class HyperliquidPublicApi {
             clearTimeout(tid);
         }
     }
+    /** `meta` — the asset universe (szDecimals, maxLeverage, positional assetIndex).
+     *  Keyless info read, weight 20. Feeds HyperliquidInfoCache. Returns null on any
+     *  failure (never a partial universe — a half-loaded rules table would silently
+     *  reject orders). */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchMeta() {
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl()}/info`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ type: 'meta' }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!res.ok) {
+                logger.warn(TAG, `fetchMeta: HTTP ${res.status}`);
+                return null;
+            }
+            return await res.json();
+        }
+        catch (err) {
+            logger.warn(TAG, `fetchMeta failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** ★ MARK price — the price HL trigger orders fire on (there is no workingType
+     *  choice on this venue). Stop-distance validation and every trigger MUST use
+     *  this, never `last`: the mark is a CEX-composite median that can diverge from
+     *  HL's own last trade. Sourced from `metaAndAssetCtxs` (one weight-20 call
+     *  covers every asset). Returns null on failure — never a stale guess. */
+    async fetchMarkPrice(symbol) {
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl()}/info`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ type: 'metaAndAssetCtxs' }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!res.ok) {
+                logger.warn(TAG, `fetchMarkPrice: HTTP ${res.status}`);
+                return null;
+            }
+            const body = (await res.json());
+            const universe = body?.[0]?.universe ?? [];
+            const ctxs = body?.[1] ?? [];
+            const coin = toHyperliquidCoin(symbol);
+            const idx = universe.findIndex((u) => u?.name === coin);
+            if (idx < 0) {
+                logger.warn(TAG, `fetchMarkPrice: ${coin} not in meta.universe`);
+                return null;
+            }
+            const mark = Number(ctxs[idx]?.markPx);
+            return Number.isFinite(mark) && mark > 0 ? mark : null;
+        }
+        catch (err) {
+            logger.warn(TAG, `fetchMarkPrice failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
 }