@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/venues/hyperliquid/hl-public.js

@@ -0,0 +1,436 @@
+// Hyperliquid public market-data source (keyless) — Phase 1 of
+// docs/HYPERLIQUID_INTEGRATION_PLAN.md. Implements PublicMarketDataApi so
+// PAPER mode on venue='hyperliquid' prices the simulator, the stop-watcher,
+// and every market-data tool from Hyperliquid instead of Binance. Live
+// trading does NOT use this class (the Phase 3 adapter owns its own reads).
+//
+// Protocol facts (verified 2026-07-11, plan §3 + live probe):
+//   - REST is POST-only: /info on api.hyperliquid.xyz (testnet:
+//     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.
+//   - `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
+//     credentialed refactor can never silently enroll CCXT's builder fee or
+//     referral code. hl-public.test.ts asserts these options forever.
+//
+// Error contract mirrors BinancePublicApi/IntelPublicApi: null on ANY failure,
+// 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 { 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).
+// 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');
+}
+/** Base URLs verified against the official docs + pinned ccxt source (plan §3.1). */
+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)
+        return DEFAULT_TICKER_TTL_MS;
+    return raw;
+}
+export class HyperliquidPublicApi {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    exchange;
+    testnet;
+    fetchImpl;
+    tickerTtlMs = resolveTickerTtlMs();
+    /** 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;
+        if (opts.exchange) {
+            this.exchange = opts.exchange;
+        }
+        else {
+            const HlClass = ccxtCjs.hyperliquid ?? ccxtCjs.default?.hyperliquid;
+            if (!HlClass) {
+                throw new Error('CCXT hyperliquid class not found — check ccxt version');
+            }
+            this.exchange = new HlClass({
+                enableRateLimit: true,
+                options: {
+                    // ★ Never let CCXT enroll its own builder fee / referral code —
+                    // plan §3.8. Keyless clients can't sign those actions anyway, but
+                    // the pin is deliberate defense-in-depth for future refactors.
+                    builderFee: false,
+                    refSet: true,
+                },
+            });
+            if (this.testnet) {
+                this.exchange.setSandboxMode(true);
+            }
+        }
+        logger.info(TAG, `Hyperliquid public API initialized (no auth${this.testnet ? ', TESTNET' : ''})`);
+    }
+    baseUrl() {
+        return this.testnet ? HL_TESTNET_API : HL_MAINNET_API;
+    }
+    /** Canonical/ccxt symbol → this venue's ccxt symbol, or null (logged) when
+     *  the symbol isn't a Hyperliquid USDC perp — a caller bug we surface
+     *  loudly rather than silently translating quote assets. */
+    venueSymbol(symbol, ctx) {
+        try {
+            return toCcxtSymbol('hyperliquid', symbol);
+        }
+        catch (err) {
+            logger.warn(TAG, `${ctx}(${symbol}) — not a Hyperliquid symbol (${err instanceof Error ? err.message : String(err)}); use USDC pairs like BTC/USDC`);
+            return null;
+        }
+    }
+    /** Fetch-all-tickers with a short TTL + inflight dedup. Returns a map keyed
+     *  by ccxt symbol, or null on failure. */
+    async getTickers() {
+        const now = Date.now();
+        if (this.tickersCache && now - this.tickersCache.at < this.tickerTtlMs) {
+            return this.tickersCache.bySymbol;
+        }
+        if (this.tickersInflight)
+            return this.tickersInflight;
+        this.tickersInflight = (async () => {
+            try {
+                const raw = await this.exchange.fetchTickers();
+                const bySymbol = new Map(Object.entries(raw ?? {}));
+                this.tickersCache = { at: Date.now(), bySymbol };
+                return bySymbol;
+            }
+            catch (err) {
+                logger.error(TAG, `fetchTickers failed: ${err instanceof Error ? err.message : String(err)}`);
+                return null;
+            }
+            finally {
+                this.tickersInflight = null;
+            }
+        })();
+        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');
+        if (!vs)
+            return null;
+        const tickers = await this.getTickers();
+        return tickers?.get(vs) ?? null;
+    }
+    /** 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) {
+            if (tickers)
+                logger.warn(TAG, `fetchTicker(${symbol}) — ${vs} not in Hyperliquid universe`);
+            return null;
+        }
+        const last = Number(raw.last ?? raw.close ?? raw.markPrice ?? NaN);
+        if (!Number.isFinite(last) || last <= 0) {
+            logger.warn(TAG, `fetchTicker(${symbol}) — no usable price on ticker`);
+            return null;
+        }
+        // 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,
+            last,
+            bid: Number(raw.bid ?? NaN) > 0 ? Number(raw.bid) : last,
+            ask: Number(raw.ask ?? NaN) > 0 ? Number(raw.ask) : last,
+            baseVolume: Number(raw.baseVolume ?? 0) || 0,
+            quoteVolume: Number(raw.quoteVolume ?? 0) || 0,
+            change: Number(raw.change ?? 0) || 0,
+            percentage: Number(raw.percentage ?? 0) || 0,
+            timestamp,
+            datetime: raw.datetime ?? new Date(timestamp).toISOString(),
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchFundingRate(symbol) {
+        const vs = this.venueSymbol(symbol, 'fetchFundingRate');
+        if (!vs)
+            return null;
+        try {
+            const r = await this.exchange.fetchFundingRate(vs);
+            return r ?? null;
+        }
+        catch (err) {
+            logger.error(TAG, `fetchFundingRate(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchOpenInterest(symbol) {
+        const vs = this.venueSymbol(symbol, 'fetchOpenInterest');
+        if (!vs)
+            return null;
+        try {
+            const r = await this.exchange.fetchOpenInterest(vs);
+            return r ?? null;
+        }
+        catch (err) {
+            logger.error(TAG, `fetchOpenInterest(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** l2Book — Hyperliquid serves at most 20 levels/side (plan §3.6). */
+    async fetchOrderBook(symbol, limit = 20) {
+        const vs = this.venueSymbol(symbol, 'fetchOrderBook');
+        if (!vs)
+            return null;
+        try {
+            const raw = await this.exchange.fetchOrderBook(vs, Math.min(limit, 20));
+            return {
+                bids: (raw.bids ?? []).map((l) => [l[0], l[1]]),
+                asks: (raw.asks ?? []).map((l) => [l[0], l[1]]),
+                timestamp: raw.timestamp ?? Date.now(),
+            };
+        }
+        catch (err) {
+            logger.error(TAG, `fetchOrderBook(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** candleSnapshot — only the most recent 5000 candles exist per (coin,
+     *  interval) (plan §3.6); requests inside that window behave like Binance. */
+    async fetchOHLCV(symbol, timeframe = '1h', limit = 100) {
+        const vs = this.venueSymbol(symbol, 'fetchOHLCV');
+        if (!vs)
+            return null;
+        try {
+            const raw = await this.exchange.fetchOHLCV(vs, timeframe, undefined, limit);
+            const valid = [];
+            for (const candle of raw) {
+                if (candle.length >= 6 &&
+                    typeof candle[0] === 'number' &&
+                    typeof candle[1] === 'number' &&
+                    typeof candle[2] === 'number' &&
+                    typeof candle[3] === 'number' &&
+                    typeof candle[4] === 'number' &&
+                    typeof candle[5] === 'number') {
+                    valid.push(candle);
+                }
+            }
+            return valid;
+        }
+        catch (err) {
+            logger.error(TAG, `fetchOHLCV(${symbol}, ${timeframe}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Probe Hyperliquid reachability from this host — the readiness gate's
+     *  venue signal, mirroring BinancePublicApi.probeReachability's outcome
+     *  shape. Hand-rolled POST /info `exchangeStatus` (weight 2) so the probe
+     *  has zero ccxt-method-shape dependence; the response's `time` field
+     *  (verified live 2026-07-11: `{"specialStatuses":null,"time":…}`) doubles
+     *  as the clock-drift source. Geo classification is best-effort — HL's
+     *  API-level geo behavior is UNVERIFIED (plan §3.9); a 403/451 maps to
+     *  geo_blocked, anything else non-2xx/network maps to unreachable. */
+    async probeReachability() {
+        const ac = new AbortController();
+        const tid = setTimeout(() => ac.abort(), 10_000);
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl()}/info`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ type: 'exchangeStatus' }),
+                signal: ac.signal,
+            });
+            if (res.status === 451 || res.status === 403) {
+                logger.warn(TAG, `probeReachability: HTTP ${res.status} (geo/policy block)`);
+                return { outcome: 'geo_blocked', driftMs: null };
+            }
+            if (res.status < 200 || res.status >= 300) {
+                logger.warn(TAG, `probeReachability: HTTP ${res.status}`);
+                return { outcome: 'unreachable', driftMs: null };
+            }
+            const body = (await res.json());
+            const serverTime = Number(body?.time);
+            const driftMs = Number.isFinite(serverTime) ? serverTime - Date.now() : null;
+            return { outcome: 'reachable', driftMs };
+        }
+        catch (err) {
+            logger.warn(TAG, `probeReachability failed: ${err instanceof Error ? err.message : String(err)}`);
+            return { outcome: 'unreachable', driftMs: null };
+        }
+        finally {
+            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/assets/plugin/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;