@reefclaw/connect 0.1.12 → 0.1.14

package/assets/plugin/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/assets/plugin/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;
+}

package/assets/plugin/venues/hyperliquid/hl-user-stream.js

@@ -0,0 +1,220 @@
+// Hyperliquid user data stream (plan §5.4/§5.9) — the HL analog of
+// `live/user-data-stream.ts`.
+//
+// ★ THE MEASURED FACT THAT SHAPES THIS FILE (T-5, testnet 2026-07-12):
+//   **HL's WS replays NOTHING on reconnect.** We killed the socket, placed an
+//   order inside the gap, re-subscribed — and received ZERO events for it, while
+//   REST showed it plainly. There is no `isSnapshot` backfill for the gap.
+//
+//   ⇒ WS is a FAST PATH, never the ledger. Every reconnect MUST be followed by a
+//     REST truth-check (positions + open orders + fills since the disconnect), and
+//     the caller is REQUIRED to wire `onResyncNeeded`. This class refuses to
+//     pretend otherwise: it tracks `lastEventAt`/`disconnectedAt` and hands them
+//     to the resync callback so the gap window is explicit.
+//
+// Other HL-specific rules honoured here:
+//   - No listenKey. Auth is by SUBSCRIBING with the MASTER address (agent wallets
+//     sign; queries always name the master).
+//   - Server closes an idle socket after 60s of silence ⇒ app-level ping every 30s
+//     (same cadence the intel HL client uses).
+//   - Subscriptions are NOT auto-restored by the server: they must be re-sent on
+//     every (re)connect.
+//   - `orderUpdates` carries trigger orders natively (statuses incl. `triggered`,
+//     `siblingFilledCanceled`, `liquidatedCanceled`, `delistedCanceled`,
+//     `marginCanceled`) — simpler than Binance, where brackets needed a separate
+//     ALGO_UPDATE channel.
+import WebSocket from 'ws';
+import { logger } from '../../logger.js';
+const TAG = 'hl-user-stream';
+const PING_INTERVAL_MS = 30_000; // server cuts idle sockets at 60s
+const STALE_AFTER_MS = 90_000; // no frame at all for 90s ⇒ terminate + reconnect
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+export class HyperliquidUserStream {
+    opts;
+    ws = null;
+    pingTimer = null;
+    staleTimer = null;
+    reconnectTimer = null;
+    reconnectAttempts = 0;
+    stopped = false;
+    lastFrameAt = 0;
+    /** Last event we actually processed — the low-water mark for the REST gap-fill. */
+    lastEventAt = 0;
+    disconnectedAt = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    /** Epoch-ms of the last processed event (0 = none yet). */
+    get lastEventTimestamp() {
+        return this.lastEventAt;
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.clearTimers();
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.ws = null;
+    }
+    url() {
+        return this.opts.testnet
+            ? 'wss://api.hyperliquid-testnet.xyz/ws'
+            : 'wss://api.hyperliquid.xyz/ws';
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        const url = this.url();
+        logger.info(TAG, `connecting ${url}`);
+        const ws = new WebSocket(url);
+        this.ws = ws;
+        ws.on('open', () => {
+            this.reconnectAttempts = 0;
+            this.lastFrameAt = Date.now();
+            this.subscribeAll();
+            this.armTimers();
+            // ★ T-5: the server sends NO backfill for the gap. Tell the caller exactly
+            // how blind we were so it can REST-reconcile that window. `lastEventAt || 0`
+            // makes the first connect a full-snapshot request too.
+            const wasDisconnectedMs = this.disconnectedAt ? Date.now() - this.disconnectedAt : 0;
+            const sinceMs = this.lastEventAt || Date.now() - 60_000;
+            logger.info(TAG, `connected — REST resync required (blind ${Math.round(wasDisconnectedMs / 1000)}s; ` +
+                'HL WS does not replay missed events — verified testnet 2026-07-12)');
+            this.opts.callbacks.onResyncNeeded({ sinceMs, wasDisconnectedMs });
+            this.disconnectedAt = 0;
+        });
+        ws.on('message', (raw) => {
+            this.lastFrameAt = Date.now();
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            this.handle(msg);
+        });
+        ws.on('close', (code, reason) => {
+            logger.warn(TAG, `closed code=${code} reason=${reason?.toString().slice(0, 80)}`);
+            this.onDisconnected();
+        });
+        ws.on('error', (err) => {
+            logger.warn(TAG, `socket error: ${err.message}`);
+            // 'close' follows — reconnect is handled there.
+        });
+    }
+    subscribeAll() {
+        const user = this.opts.walletAddress;
+        // Subscriptions are NOT restored by the server after a reconnect — always re-send.
+        const subs = [
+            { type: 'orderUpdates', user },
+            { type: 'userFills', user },
+            { type: 'userEvents', user },
+            { type: 'userFundings', user },
+        ];
+        for (const subscription of subs) {
+            this.send({ method: 'subscribe', subscription });
+        }
+    }
+    handle(msg) {
+        const { channel, data } = msg;
+        if (!channel || channel === 'subscriptionResponse' || channel === 'pong')
+            return;
+        switch (channel) {
+            case 'userFills': {
+                const payload = data;
+                for (const fill of payload?.fills ?? []) {
+                    this.lastEventAt = Math.max(this.lastEventAt, fill.time ?? Date.now());
+                    this.opts.callbacks.onFill(fill);
+                }
+                break;
+            }
+            case 'orderUpdates': {
+                const updates = (Array.isArray(data) ? data : []);
+                for (const u of updates) {
+                    this.lastEventAt = Math.max(this.lastEventAt, u.statusTimestamp ?? Date.now());
+                    this.opts.callbacks.onOrderUpdate(u);
+                }
+                break;
+            }
+            case 'userEvents': {
+                this.lastEventAt = Date.now();
+                this.opts.callbacks.onUserEvent((data ?? {}));
+                break;
+            }
+            case 'userFundings': {
+                this.lastEventAt = Date.now();
+                this.opts.callbacks.onUserEvent({ fundings: data });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    send(payload) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            this.ws.send(JSON.stringify(payload));
+        }
+        catch (err) {
+            logger.warn(TAG, `send failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    armTimers() {
+        this.clearTimers();
+        // App-level ping — the server cuts an idle socket at 60s.
+        this.pingTimer = setInterval(() => this.send({ method: 'ping' }), PING_INTERVAL_MS);
+        // Frame-staleness watchdog — a silent socket is worse than a closed one
+        // (we would believe stale positions). Terminate ⇒ reconnect ⇒ REST resync.
+        this.staleTimer = setInterval(() => {
+            if (!this.lastFrameAt)
+                return;
+            const silentMs = Date.now() - this.lastFrameAt;
+            if (silentMs > STALE_AFTER_MS) {
+                logger.warn(TAG, `no frames for ${Math.round(silentMs / 1000)}s — terminating socket`);
+                try {
+                    this.ws?.terminate();
+                }
+                catch {
+                    /* the close handler drives the reconnect */
+                }
+            }
+        }, 15_000);
+    }
+    clearTimers() {
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        if (this.staleTimer)
+            clearInterval(this.staleTimer);
+        this.pingTimer = null;
+        this.staleTimer = null;
+    }
+    onDisconnected() {
+        this.clearTimers();
+        this.ws = null;
+        if (this.stopped)
+            return;
+        if (!this.disconnectedAt)
+            this.disconnectedAt = Date.now();
+        const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempts, RECONNECT_MAX_MS);
+        const jittered = delay * (0.8 + Math.random() * 0.4);
+        this.reconnectAttempts += 1;
+        logger.info(TAG, `reconnecting in ${Math.round(jittered / 1000)}s (attempt ${this.reconnectAttempts})`);
+        this.reconnectTimer = setTimeout(() => this.connect(), jittered);
+    }
+}

package/assets/plugin/venues/registry.d.ts

@@ -0,0 +1,38 @@
+import { LiveAdapter } from '../live/live-adapter.js';
+import { HyperliquidLiveAdapter, type HlLiveAdapterOptions } from './hyperliquid/hl-live-adapter.js';
+import { fillExchangeId, parseVenue, type VenueId } from './symbols.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>;
+/** Every live adapter this build can construct. Both are EventEmitters exposing
+ *  the same lifecycle events (`drift_detected`) and both implement
+ *  IExchangeAdapter — the boot path treats them identically. */
+export type AnyLiveAdapter = LiveAdapter | HyperliquidLiveAdapter;
+/** Venue-typed construction spec. A discriminated union so the compiler — not a
+ *  runtime branch in the boot path — guarantees each venue gets ITS OWN args
+ *  (Binance takes API key/secret; Hyperliquid takes a master address + agent key,
+ *  a completely different credential shape). */
+export type LiveAdapterSpec = {
+    venue: 'binance';
+    args: BinanceLiveAdapterArgs;
+} | {
+    venue: 'hyperliquid';
+    args: HlLiveAdapterOptions;
+};
+/** Construct the live adapter for a venue — the ONLY place either class is newed.
+ *
+ *  Binance: a pure pass-through to `new LiveAdapter(...)` — byte-identical to the
+ *  inline construction this factory replaced (the args tuple is derived from the
+ *  constructor so the two can never drift).
+ *  Hyperliquid: `new HyperliquidLiveAdapter(...)` (Phase 3). */
+export declare function createLiveAdapter(spec: LiveAdapterSpec): AnyLiveAdapter;

package/assets/plugin/venues/registry.js

@@ -0,0 +1,46 @@
+// 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 { LiveAdapter } from '../live/live-adapter.js';
+import { HyperliquidLiveAdapter } from './hyperliquid/hl-live-adapter.js';
+import { fillExchangeId, parseVenue } from './symbols.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', 'hyperliquid']);
+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 — the ONLY place either class is newed.
+ *
+ *  Binance: a pure pass-through to `new LiveAdapter(...)` — byte-identical to the
+ *  inline construction this factory replaced (the args tuple is derived from the
+ *  constructor so the two can never drift).
+ *  Hyperliquid: `new HyperliquidLiveAdapter(...)` (Phase 3). */
+export function createLiveAdapter(spec) {
+    switch (spec.venue) {
+        case 'binance':
+            return new LiveAdapter(...spec.args);
+        case 'hyperliquid':
+            return new HyperliquidLiveAdapter(spec.args);
+    }
+}

package/assets/plugin/venues/symbols.d.ts

@@ -0,0 +1,43 @@
+export type VenueId = 'binance' | 'hyperliquid';
+export declare const VENUE_IDS: readonly VenueId[];
+export declare function isVenueId(value: unknown): value is VenueId;
+/** Parse a raw config value into a venue.
+ *  Absent/empty → 'binance' (every pre-venue config file keeps today's
+ *  behavior byte-identically). An unrecognized string is surfaced to the
+ *  caller instead of being silently coerced — mis-spelling a venue must be
+ *  loud, never quietly become "trade on Binance". */
+export declare function parseVenue(raw: unknown): {
+    venue: VenueId;
+    unrecognized?: string;
+};
+/** `FillEvent.exchange` / webapp `trades.exchange` value — half of the
+ *  audit-trail idempotency key `(exchange, exchange_trade_id)` (migration
+ *  0042). 'binance_futures' is the historical literal on every existing row;
+ *  NEVER change these strings once a venue has written rows. */
+export declare const FILL_EXCHANGE_ID: Record<VenueId, string>;
+export declare function fillExchangeId(venue: VenueId): string;
+/** Quote/settle asset of the venue's linear perps. */
+export declare const VENUE_QUOTE_ASSET: Record<VenueId, string>;
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export declare const HL_INTEL_PREFIX = "HL_";
+/** Canonical symbol → the venue's CCXT unified symbol.
+ *  'BTC/USDT' (binance) → 'BTC/USDT:USDT'; 'BTC/USDC' (hyperliquid) →
+ *  'BTC/USDC:USDC'. Accepts an already-suffixed input (idempotent). */
+export declare function toCcxtSymbol(venue: VenueId, canonical: string): string;
+/** Canonical symbol → intel DB symbol.
+ *  binance: 'BTC/USDT' → 'BTCUSDT' (the historical concatenated form intel has
+ *  always stored); hyperliquid: 'BTC/USDC' → 'HL_BTC' (namespaced coin, case
+ *  preserved). */
+export declare function toIntelSymbol(venue: VenueId, canonical: string): string;
+/** Inverse of toIntelSymbol. 'HL_'-prefixed → hyperliquid; everything else is
+ *  the historical Binance namespace. Binance symbols that are not
+ *  USDT-concatenated (none exist in INTEL_SYMBOLS today) come back verbatim as
+ *  canonical — honest passthrough, not a guess. */
+export declare function fromIntelSymbol(intelSymbol: string): {
+    venue: VenueId;
+    canonical: string;
+};
+/** The Hyperliquid venue-native coin name for a canonical symbol
+ *  ('BTC/USDC' → 'BTC'). Orders address assets by integer index resolved from
+ *  `meta.universe` at runtime — the coin name is the stable half. */
+export declare function toHyperliquidCoin(canonical: string): string;