@reefclaw/openclaw-plugin 0.1.3 → 0.1.5

package/venues/hyperliquid/hl-public.js

@@ -0,0 +1,285 @@
+// 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.
+//   - 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).
+//   - 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 { toCcxtSymbol } from '@reefclaw/shared';
+import { logger } from '../../logger.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;
+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;
+    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;
+    }
+    // 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;
+    }
+    /** 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). */
+    async fetchTicker(symbol) {
+        const vs = this.venueSymbol(symbol, 'fetchTicker');
+        if (!vs)
+            return null;
+        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;
+        }
+        const timestamp = Number.isFinite(raw.timestamp) ? Number(raw.timestamp) : 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);
+        }
+    }
+}

package/venues/registry.d.ts

@@ -0,0 +1,24 @@
+import { fillExchangeId, parseVenue, type VenueId } from '@reefclaw/shared';
+import { LiveAdapter } from '../live/live-adapter.js';
+export type { VenueId };
+export { fillExchangeId, parseVenue };
+/** Venues this build can construct a LIVE adapter for. PAPER mode is
+ *  venue-flavored only by its market-data source (PaperMarketFeed / chart) and
+ *  is not gated here. */
+export declare const SUPPORTED_LIVE_VENUES: ReadonlySet<VenueId>;
+export declare function isLiveVenueSupported(venue: VenueId): boolean;
+/** Paper-wallet settlement/quote currency for a venue. Hyperliquid margins
+ *  USDC linear perps; Binance USDⓈ-M paper keeps the historical USDT.
+ *  Issue #174: the paper wallet MUST follow the venue — a USDT wallet on the
+ *  USDC venue reads as $0 equity and every order fails "Insufficient USDC". */
+export declare function venueQuoteCurrency(venue: VenueId): 'USDT' | 'USDC';
+type BinanceLiveAdapterArgs = ConstructorParameters<typeof LiveAdapter>;
+/** Construct the live adapter for a venue.
+ *
+ *  Binance: a pure pass-through to `new LiveAdapter(...)` — byte-identical to
+ *  the inline construction this factory replaced (Phase 0 no-behavior-change
+ *  rule; the args tuple is derived from the constructor so the two can never
+ *  drift). Hyperliquid: throws — reaching this arm means the boot-time
+ *  isLiveVenueSupported() fallback-to-PAPER gate was bypassed, which is a bug,
+ *  not a user state. */
+export declare function createLiveAdapter(venue: VenueId, ...args: BinanceLiveAdapterArgs): LiveAdapter;

package/venues/registry.js

@@ -0,0 +1,47 @@
+// Venue registry — the single seam where a trading venue's LIVE adapter is
+// constructed (Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.1/§7.1).
+//
+// Phase 0 scope: Binance is the ONLY venue this build can trade live;
+// 'hyperliquid' is a recognised-but-unsupported config value that boot handles
+// by falling back to PAPER (never by crashing register() — OpenClaw treats a
+// throwing register as "ignored" and the agent silently loses every tool).
+// Phase 3 adds the HyperliquidLiveAdapter arm HERE and nowhere else, so the
+// boot path never grows a second venue branch.
+//
+// Venue is LOCAL mechanism (TOOL_DISTRIBUTION_ARCHITECTURE.md §2 decision
+// rule: it holds keys + is part of the safety floor) — it is read from
+// ~/.reefclaw/plugin-config.json `exchange.venue` and MUST never be settable
+// from the central config channel.
+import { fillExchangeId, parseVenue } from '@reefclaw/shared';
+import { LiveAdapter } from '../live/live-adapter.js';
+export { fillExchangeId, parseVenue };
+/** Venues this build can construct a LIVE adapter for. PAPER mode is
+ *  venue-flavored only by its market-data source (PaperMarketFeed / chart) and
+ *  is not gated here. */
+export const SUPPORTED_LIVE_VENUES = new Set(['binance']);
+export function isLiveVenueSupported(venue) {
+    return SUPPORTED_LIVE_VENUES.has(venue);
+}
+/** Paper-wallet settlement/quote currency for a venue. Hyperliquid margins
+ *  USDC linear perps; Binance USDⓈ-M paper keeps the historical USDT.
+ *  Issue #174: the paper wallet MUST follow the venue — a USDT wallet on the
+ *  USDC venue reads as $0 equity and every order fails "Insufficient USDC". */
+export function venueQuoteCurrency(venue) {
+    return venue === 'hyperliquid' ? 'USDC' : 'USDT';
+}
+/** Construct the live adapter for a venue.
+ *
+ *  Binance: a pure pass-through to `new LiveAdapter(...)` — byte-identical to
+ *  the inline construction this factory replaced (Phase 0 no-behavior-change
+ *  rule; the args tuple is derived from the constructor so the two can never
+ *  drift). Hyperliquid: throws — reaching this arm means the boot-time
+ *  isLiveVenueSupported() fallback-to-PAPER gate was bypassed, which is a bug,
+ *  not a user state. */
+export function createLiveAdapter(venue, ...args) {
+    switch (venue) {
+        case 'binance':
+            return new LiveAdapter(...args);
+        case 'hyperliquid':
+            throw new Error("venue 'hyperliquid' has no live adapter in this build — arrives in Phase 3 of docs/HYPERLIQUID_INTEGRATION_PLAN.md");
+    }
+}