@reefclaw/openclaw-plugin 0.1.5 → 0.1.6

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) {
@@ -282,4 +368,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;
+        }
+    }
 }

package/venues/hyperliquid/hl-rate-gate.d.ts

@@ -0,0 +1,57 @@
+/** Info-request weights, from the docs (§3.3). Anything unlisted defaults to 20 —
+ *  the conservative side. `/exchange` actions are `1 + floor(batch/40)`. */
+export declare const HL_INFO_WEIGHTS: Record<string, number>;
+export declare class HyperliquidRateLimitedError extends Error {
+    constructor(message: string);
+}
+/** Thrown by the proactive pacer BEFORE a call goes out. Subclass so every
+ *  existing `catch (HyperliquidRateLimitedError)` absorbs it — the same
+ *  relationship `BinanceWeightPacedError` has to `BinanceBannedError`. */
+export declare class HyperliquidPacedError extends HyperliquidRateLimitedError {
+    constructor(message: string);
+}
+/** Current 60s IP-weight estimate. */
+export declare function currentIpWeight(now?: number): number;
+/** Weight for an info context (defaults to the conservative 20). */
+export declare function infoWeight(ctx: string): number;
+/** `/exchange` IP weight for a batch of n actions: 1 + floor(n/40). */
+export declare function exchangeIpWeight(batchLen: number): number;
+/** FIRST LINE of every gated read's try-block.
+ *
+ *  Throws when:
+ *   - a 429 backoff is active (hard stop — like an active Binance ban), or
+ *   - the IP weight window is over its soft ceiling (proactive pacing), or
+ *   - the address budget is below the floor AND this context is shed-able.
+ *
+ *  Order/cancel/close paths must NOT call this — they arm the gate via
+ *  `noteError` only, so a limit can never block an exit. */
+export declare function assertNotLimited(ctx: string): void;
+/** Record a successful call's cost. `addressActions` is 0 for pure info reads
+ *  (they cost IP weight only) and n for an `/exchange` batch of n actions. */
+export declare function noteSuccess(ctx: string, cost?: {
+    ipWeight?: number;
+    addressActions?: number;
+}): void;
+/** Arm the gate from a caught error. Called in EVERY catch — including on the
+ *  order/cancel paths that are never pre-gated (so a burst of rejects still
+ *  backs the gate off). */
+export declare function noteError(err: unknown, ctx?: string): void;
+/** HL surfaces rate limiting as HTTP 429 and/or a text body; match on shape, not
+ *  on a venue flag, so the skill-side breaker can reuse this predicate. */
+export declare function isRateLimitError(err: unknown): boolean;
+/** Feed the address budget from info `userRateLimit` (`nRequestsCap −
+ *  nRequestsUsed`). Poll it every ~5 min — it costs weight 20. */
+export declare function updateAddressBudget(args: {
+    nRequestsUsed: number;
+    nRequestsCap: number;
+}): void;
+/** Snapshot for tests + the readiness/diagnostic surfaces. */
+export declare function getGateState(): {
+    ipWeight60s: number;
+    weightCeiling: number;
+    addressRemaining?: number;
+    limited: boolean;
+    limitedForMs: number;
+};
+/** Test-only reset. */
+export declare function __resetGateForTests(): void;

package/venues/hyperliquid/hl-rate-gate.js

@@ -0,0 +1,220 @@
+// Hyperliquid rate gate — the HL analog of `ccxt/binance-ban-gate.ts` (plan §5.6).
+//
+// SAME SHAPE as the Binance gate (process-wide singleton; `assertNotLimited(ctx)`
+// first line in the try, `noteError(err)` in the catch, `noteSuccess()` after a
+// clean call; order/cancel paths are NEVER pre-gated but DO arm the gate).
+// DIFFERENT MODEL inside — read twice before tuning:
+//
+//   Binance: per-IP weight window; abuse ⇒ a 418 BAN that EXTENDS on every further
+//            request. The danger is a poller hammering through a ban.
+//   HL:      TWO independent budgets.
+//            (1) IP weight: 1200/min (no response header to reconcile against —
+//                the local estimate IS the authority; calibrate in shadow).
+//            (2) ★ ADDRESS action budget: 10,000 initial + 1 per 1 USDC of
+//                cumulative traded volume. Exhausted ⇒ 1 request / 10 s. A
+//                low-volume, chatty heartbeat agent STARVES ITSELF — the exact
+//                opposite failure mode from Binance, and the one Binance-tuned
+//                intuition will miss.
+//
+// Batches count as **1** for the IP window but **n** for the address budget, so
+// every `note*` call takes both numbers — brackets (2 legs, one batch) are counted
+// honestly.
+import { logger } from '../../logger.js';
+const TAG = 'hl-rate-gate';
+/** Documented IP limit is 1200 weight/min; we pace against a soft ceiling so a
+ *  burst never reaches the real one. Env override for calibration. */
+const DEFAULT_WEIGHT_CEILING = 900;
+/** Below this many remaining address actions we start shedding SHED_FIRST reads
+ *  and warn loudly (the remedy is operator-level: trade volume accrues budget, or
+ *  `reserveRequestWeight` purchases more — never automatic). */
+const DEFAULT_ADDRESS_FLOOR = 2000;
+const WINDOW_MS = 60_000;
+/** 429 backoff ladder (mirrors the Binance gate's shape; HL has no
+ *  418-with-timestamp analog, so there is no stated window to parse). */
+const BACKOFF_LADDER_MS = [5_000, 15_000, 45_000, 90_000, 120_000];
+/** Info-request weights, from the docs (§3.3). Anything unlisted defaults to 20 —
+ *  the conservative side. `/exchange` actions are `1 + floor(batch/40)`. */
+export const HL_INFO_WEIGHTS = {
+    l2Book: 2,
+    allMids: 2,
+    clearinghouseState: 2,
+    orderStatus: 2,
+    exchangeStatus: 2,
+    spotClearinghouseState: 2,
+    userRole: 60,
+    // everything else (meta, metaAndAssetCtxs, userFills, frontendOpenOrders,
+    // userFunding, userNonFundingLedgerUpdates, candleSnapshot, userRateLimit …)
+    default: 20,
+};
+/** Read contexts that are safe to SHED when the address budget runs low — they are
+ *  refreshable/derivable, unlike the safety-floor reads (positions, open orders,
+ *  order status) which must always pass. */
+const SHED_FIRST = new Set([
+    'candleSnapshot',
+    'metaAndAssetCtxs',
+    'allMids',
+    'l2Book',
+    'userFunding',
+    'userFees',
+    'portfolio',
+]);
+export class HyperliquidRateLimitedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HyperliquidRateLimitedError';
+    }
+}
+/** Thrown by the proactive pacer BEFORE a call goes out. Subclass so every
+ *  existing `catch (HyperliquidRateLimitedError)` absorbs it — the same
+ *  relationship `BinanceWeightPacedError` has to `BinanceBannedError`. */
+export class HyperliquidPacedError extends HyperliquidRateLimitedError {
+    constructor(message) {
+        super(message);
+        this.name = 'HyperliquidPacedError';
+    }
+}
+const state = {
+    samples: [],
+    limitedUntil: 0,
+    consecutive429: 0,
+    windowIpWeight: 0,
+    windowAddressActions: 0,
+    windowStart: Date.now(),
+};
+function weightCeiling() {
+    const raw = Number(process.env.RC_HL_WEIGHT_CEILING);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_WEIGHT_CEILING;
+}
+function addressFloor() {
+    const raw = Number(process.env.RC_HL_ADDRESS_BUDGET_FLOOR);
+    return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_ADDRESS_FLOOR;
+}
+function pruneWindow(now) {
+    const cutoff = now - WINDOW_MS;
+    while (state.samples.length > 0 && state.samples[0].at < cutoff) {
+        state.samples.shift();
+    }
+}
+/** Current 60s IP-weight estimate. */
+export function currentIpWeight(now = Date.now()) {
+    pruneWindow(now);
+    return state.samples.reduce((sum, s) => sum + s.weight, 0);
+}
+/** Weight for an info context (defaults to the conservative 20). */
+export function infoWeight(ctx) {
+    return HL_INFO_WEIGHTS[ctx] ?? HL_INFO_WEIGHTS.default;
+}
+/** `/exchange` IP weight for a batch of n actions: 1 + floor(n/40). */
+export function exchangeIpWeight(batchLen) {
+    return 1 + Math.floor(Math.max(batchLen, 1) / 40);
+}
+/** FIRST LINE of every gated read's try-block.
+ *
+ *  Throws when:
+ *   - a 429 backoff is active (hard stop — like an active Binance ban), or
+ *   - the IP weight window is over its soft ceiling (proactive pacing), or
+ *   - the address budget is below the floor AND this context is shed-able.
+ *
+ *  Order/cancel/close paths must NOT call this — they arm the gate via
+ *  `noteError` only, so a limit can never block an exit. */
+export function assertNotLimited(ctx) {
+    const now = Date.now();
+    if (state.limitedUntil > now) {
+        const secs = Math.ceil((state.limitedUntil - now) / 1000);
+        throw new HyperliquidRateLimitedError(`Hyperliquid rate limit active (${secs}s remaining) — ${ctx} shed`);
+    }
+    const weight = infoWeight(ctx);
+    const used = currentIpWeight(now);
+    if (used + weight > weightCeiling()) {
+        throw new HyperliquidPacedError(`Hyperliquid IP weight pacer: ${used}+${weight} > ${weightCeiling()}/min ceiling — ${ctx} shed`);
+    }
+    const remaining = state.addressRemaining;
+    if (remaining !== undefined && remaining < addressFloor() && SHED_FIRST.has(ctx)) {
+        throw new HyperliquidPacedError(`Hyperliquid address action budget low (${remaining} left, floor ${addressFloor()}) — ` +
+            `shedding ${ctx}. Budget accrues with traded volume; reserveRequestWeight can purchase more.`);
+    }
+}
+/** Record a successful call's cost. `addressActions` is 0 for pure info reads
+ *  (they cost IP weight only) and n for an `/exchange` batch of n actions. */
+export function noteSuccess(ctx, cost) {
+    const now = Date.now();
+    const ipWeight = cost?.ipWeight ?? infoWeight(ctx);
+    const addressActions = cost?.addressActions ?? 0;
+    state.samples.push({ at: now, weight: ipWeight });
+    pruneWindow(now);
+    state.consecutive429 = 0;
+    state.limitedUntil = 0;
+    state.windowIpWeight += ipWeight;
+    state.windowAddressActions += addressActions;
+    if (addressActions > 0 && state.addressRemaining !== undefined) {
+        state.addressRemaining = Math.max(0, state.addressRemaining - addressActions);
+    }
+    maybeLogWindow(now);
+}
+/** Arm the gate from a caught error. Called in EVERY catch — including on the
+ *  order/cancel paths that are never pre-gated (so a burst of rejects still
+ *  backs the gate off). */
+export function noteError(err, ctx = 'unknown') {
+    if (!isRateLimitError(err))
+        return;
+    state.consecutive429 += 1;
+    const idx = Math.min(state.consecutive429 - 1, BACKOFF_LADDER_MS.length - 1);
+    const backoff = BACKOFF_LADDER_MS[idx];
+    state.limitedUntil = Date.now() + backoff;
+    logger.warn(TAG, `Hyperliquid rate limit hit on ${ctx} (#${state.consecutive429}) — backing off ${backoff / 1000}s`);
+}
+/** HL surfaces rate limiting as HTTP 429 and/or a text body; match on shape, not
+ *  on a venue flag, so the skill-side breaker can reuse this predicate. */
+export function isRateLimitError(err) {
+    if (err instanceof HyperliquidRateLimitedError)
+        return true;
+    const msg = err instanceof Error ? err.message : String(err ?? '');
+    return /429|rate limit|too many requests/i.test(msg);
+}
+/** Feed the address budget from info `userRateLimit` (`nRequestsCap −
+ *  nRequestsUsed`). Poll it every ~5 min — it costs weight 20. */
+export function updateAddressBudget(args) {
+    const remaining = Math.max(0, args.nRequestsCap - args.nRequestsUsed);
+    const prev = state.addressRemaining;
+    state.addressRemaining = remaining;
+    state.addressUpdatedAt = Date.now();
+    if (remaining < addressFloor() && (prev === undefined || prev >= addressFloor())) {
+        logger.warn(TAG, `★ Hyperliquid ADDRESS action budget low: ${remaining} remaining (cap ${args.nRequestsCap}). ` +
+            'Exhaustion throttles the account to 1 request/10s. Budget accrues at 1 action per 1 USDC ' +
+            'of traded volume; an operator can purchase more via reserveRequestWeight.');
+    }
+}
+/** Snapshot for tests + the readiness/diagnostic surfaces. */
+export function getGateState() {
+    const now = Date.now();
+    return {
+        ipWeight60s: currentIpWeight(now),
+        weightCeiling: weightCeiling(),
+        addressRemaining: state.addressRemaining,
+        limited: state.limitedUntil > now,
+        limitedForMs: Math.max(0, state.limitedUntil - now),
+    };
+}
+/** Permanent instrumentation — the `weight window summary` analog. Attribute load
+ *  from THESE lines, never from a guess. */
+function maybeLogWindow(now) {
+    if (now - state.windowStart < WINDOW_MS)
+        return;
+    logger.info(TAG, `hl window summary: ipWeight=${state.windowIpWeight}/${weightCeiling()} ` +
+        `addressActions=${state.windowAddressActions} ` +
+        `addressRemaining=${state.addressRemaining ?? 'unknown'}`);
+    state.windowIpWeight = 0;
+    state.windowAddressActions = 0;
+    state.windowStart = now;
+}
+/** Test-only reset. */
+export function __resetGateForTests() {
+    state.samples = [];
+    state.limitedUntil = 0;
+    state.consecutive429 = 0;
+    state.addressRemaining = undefined;
+    state.addressUpdatedAt = undefined;
+    state.windowIpWeight = 0;
+    state.windowAddressActions = 0;
+    state.windowStart = Date.now();
+}

package/venues/hyperliquid/hl-user-stream.d.ts

@@ -0,0 +1,90 @@
+export interface HlFillEvent {
+    coin: string;
+    px: string;
+    sz: string;
+    side: 'A' | 'B';
+    time: number;
+    dir: string;
+    closedPnl: string;
+    fee: string;
+    feeToken?: string;
+    builderFee?: string;
+    crossed: boolean;
+    oid: number;
+    tid: number;
+    cloid?: string;
+    startPosition?: string;
+    /** Present ONLY on a liquidation fill — an authoritative close-bypass signal. */
+    liquidation?: {
+        liquidatedUser?: string;
+        markPx?: string;
+        method?: string;
+    };
+}
+export interface HlOrderUpdateEvent {
+    order: {
+        coin: string;
+        side: 'A' | 'B';
+        limitPx: string;
+        sz: string;
+        oid: number;
+        timestamp: number;
+        origSz: string;
+        cloid?: string;
+        isTrigger?: boolean;
+        triggerPx?: string;
+        isPositionTpsl?: boolean;
+        reduceOnly?: boolean;
+        orderType?: string;
+    };
+    status: string;
+    statusTimestamp: number;
+}
+export interface HlUserStreamCallbacks {
+    onFill: (fill: HlFillEvent) => void;
+    onOrderUpdate: (update: HlOrderUpdateEvent) => void;
+    /** userEvents: liquidation / funding / non-user-cancel — the close-bypass feed. */
+    onUserEvent: (event: Record<string, unknown>) => void;
+    /**
+     * ★ MANDATORY. Fired after every (re)connect, carrying the window during which
+     * we were blind. T-5 proved the WS does NOT backfill it, so the caller MUST
+     * reconcile via REST (positions, open orders, fills since `sinceMs`) before
+     * trusting local state again. A caller that ignores this WILL miss fills.
+     */
+    onResyncNeeded: (window: {
+        sinceMs: number;
+        wasDisconnectedMs: number;
+    }) => void;
+}
+export declare class HyperliquidUserStream {
+    private readonly opts;
+    private ws;
+    private pingTimer;
+    private staleTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private stopped;
+    private lastFrameAt;
+    /** Last event we actually processed — the low-water mark for the REST gap-fill. */
+    private lastEventAt;
+    private disconnectedAt;
+    constructor(opts: {
+        /** MASTER address — subscriptions are keyed by the account, never the agent. */
+        walletAddress: string;
+        testnet?: boolean;
+        callbacks: HlUserStreamCallbacks;
+    });
+    get isConnected(): boolean;
+    /** Epoch-ms of the last processed event (0 = none yet). */
+    get lastEventTimestamp(): number;
+    start(): void;
+    stop(): void;
+    private url;
+    private connect;
+    private subscribeAll;
+    private handle;
+    private send;
+    private armTimers;
+    private clearTimers;
+    private onDisconnected;
+}