@reefclaw/openclaw-plugin 0.1.3 → 0.1.4

package/ccxt/binance-public.d.ts

@@ -1,6 +1,7 @@
 import type { CcxtTicker, CcxtOHLCV } from '../types.js';
 import type { OrderBookDepth } from '../simulator/types.js';
-export declare class BinancePublicApi {
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+export declare class BinancePublicApi implements PublicMarketDataApi {
     private exchange;
     constructor();
     /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */

package/ccxt/intel-public.d.ts

@@ -0,0 +1,25 @@
+import { type IntelApiDeps } from '../tools/intel-api.js';
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+type RawCcxt = Record<string, any>;
+export declare class IntelPublicApi implements PublicMarketDataApi {
+    private readonly deps;
+    constructor(deps: IntelApiDeps);
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    fetchTickerRaw(): Promise<RawCcxt | null>;
+    fetchFundingRate(): Promise<RawCcxt | null>;
+    fetchOpenInterest(): Promise<RawCcxt | null>;
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    fetchOrderBook(): Promise<OrderBookDepth | null>;
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    fetchOHLCV(): Promise<CcxtOHLCV[] | null>;
+}
+export {};

package/ccxt/intel-public.js

@@ -0,0 +1,80 @@
+// Intel-backed public market-data source for PAPER mode on hosts that Binance
+// geo-blocks (HTTP 451). Paper execution is fully simulated; it only needs a
+// price, which the intel service serves from its own (permitted-region) feeds
+// via GET /api/price/:symbol (latest 1m close, ≤~60s stale). See
+// docs/AGENT_READINESS_GATE_PLAN.md sibling + the wisekid 451 findings.
+//
+// Selected only when plugin-config `paperMarketDataSource: 'intel'` AND paper
+// mode (index.ts). Live trading NEVER uses this — live needs the real exchange.
+//
+// Increment 1 serves PRICE only (fetchTicker), which is the trading-critical
+// path: create_order / close_position price + the PaperMarketFeed mark loop.
+// Candles / order book / funding / OI have no intel HTTP route yet, so those
+// return null here — the SAME shape a 451 produces today (no regression), and
+// order-book absence is already handled by the fill engine's random-slippage
+// fallback. Candle/book/OI intel routes are a follow-up.
+import { logger } from '../logger.js';
+import { fetchIntelApi } from '../tools/intel-api.js';
+const TAG = 'intel-public';
+/** CCXT symbol (`BTC/USDT`, `BTC/USDT:USDT`) → intel format (`BTCUSDT`). */
+function toIntelSymbol(symbol) {
+    return symbol.replace('/', '').replace(/:.*$/, '');
+}
+export class IntelPublicApi {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        logger.info(TAG, 'Intel public market-data source active (paper mode, Binance reads routed to intel)');
+    }
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    async fetchTicker(symbol) {
+        const res = await fetchIntelApi(`/api/price/${toIntelSymbol(symbol)}`, this.deps);
+        if ('error' in res) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel failed: ${res.error}`);
+            return null;
+        }
+        const body = res;
+        const price = Number(body.price);
+        if (!Number.isFinite(price) || price <= 0) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel returned a bad price: ${body.price}`);
+            return null;
+        }
+        const timestamp = Number.isFinite(body.time) ? body.time : Date.now();
+        return {
+            // Key on the ORIGINAL ccxt symbol so the simulator's per-symbol maps line up.
+            symbol,
+            last: price,
+            bid: price,
+            ask: price,
+            baseVolume: 0,
+            quoteVolume: 0,
+            change: 0,
+            percentage: 0,
+            timestamp,
+            datetime: new Date(timestamp).toISOString(),
+        };
+    }
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    async fetchTickerRaw() {
+        return null;
+    }
+    async fetchFundingRate() {
+        return null;
+    }
+    async fetchOpenInterest() {
+        return null;
+    }
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    async fetchOrderBook() {
+        return null;
+    }
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    async fetchOHLCV() {
+        return null;
+    }
+}

package/ccxt/public-market-data-api.d.ts

@@ -0,0 +1,12 @@
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+type RawCcxt = Record<string, any>;
+export interface PublicMarketDataApi {
+    fetchTickerRaw(symbol: string): Promise<RawCcxt | null>;
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    fetchFundingRate(symbol: string): Promise<RawCcxt | null>;
+    fetchOpenInterest(symbol: string): Promise<RawCcxt | null>;
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+}
+export {};

package/ccxt/public-market-data-api.js

@@ -0,0 +1,9 @@
+// The public market-data surface paper mode reads (prices, candles, book,
+// funding, OI). Both BinancePublicApi (direct Binance) and IntelPublicApi
+// (via the intel service, for Binance-451-geo-blocked hosts) implement it, so
+// the paper wiring can select a source without any consumer knowing which.
+//
+// Deliberately EXCLUDES probeReachability: that is Binance-specific and only
+// the readiness reporter uses it — it must always probe the REAL Binance host
+// to detect the 451, so it keeps a concrete BinancePublicApi, never this.
+export {};

package/config/plugin-config-io.d.ts

@@ -21,8 +21,23 @@ export interface PluginConfigFile {
      *  prod runs the bridge under systemd and a supervisor there would
      *  double-connect the relay room. Kill-switch: RC_CONNECTOR_SUPERVISOR=off. */
     connectorSupervisor?: 'on' | 'off';
+    /** Where PAPER mode reads market-data prices from. 'binance' (default) hits
+     *  Binance public endpoints directly; 'intel' routes them through the intel
+     *  service (GET /api/price/:symbol) so a host that Binance geo-blocks (HTTP
+     *  451) can still paper-trade. PAPER-ONLY + advisory: live trading always
+     *  uses the real exchange, and readiness still probes real Binance to detect
+     *  the 451. Kill-switch: RC_PAPER_MARKET_DATA=binance forces the default. */
+    paperMarketDataSource?: 'binance' | 'intel';
     apiBaseUrl?: string;
     intelligenceUrl?: string;
+    /** Exchange credentials + venue selection. `exchange.venue` picks the
+     *  trading venue ('binance' default | 'hyperliquid'); it is LOCAL mechanism
+     *  (never central-pushable) per docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.2.
+     *  Until Phase 3 ships the hyperliquid adapter, a non-PAPER mode on
+     *  venue='hyperliquid' falls back to PAPER at boot. NOTE: updatePluginConfig
+     *  replaces this block wholesale (the documented `exchange: null` clears
+     *  credentials), so any writer (set_exchange_credentials, SSH edits) must
+     *  carry `venue` through or it resets to the binance default. */
     exchange?: ExchangeConfig;
     tradingMode?: TradingMode;
     microLive?: {

package/index.js

@@ -11,6 +11,7 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { BinancePublicApi } from './ccxt/binance-public.js';
+import { IntelPublicApi } from './ccxt/intel-public.js';
 import { BinancePrivateApi } from './ccxt/binance-private.js';
 import { ExchangeSimulator } from './simulator/exchange-simulator.js';
 import { ShadowTracker } from './shadow/shadow-tracker.js';
@@ -18,7 +19,8 @@ import { StateManager } from './persistence/state-manager.js';
 import { logger, setLogLevel, formatError } from './logger.js';
 import { DEFAULT_CONFIG } from './types.js';
 import { PaperAdapter } from './paper-adapter.js';
-import { LiveAdapter } from './live/live-adapter.js';
+import { createLiveAdapter, fillExchangeId, isLiveVenueSupported, parseVenue, } from './venues/registry.js';
+import { HyperliquidPublicApi } from './venues/hyperliquid/hl-public.js';
 import { loadBracketMode } from './config/brackets-config.js';
 import { loadUserDataStreamMode, loadUserDataStreamTunables, loadUserDataStreamDbWrite, getUserDataStreamIngestBaseUrl, resolveIngestToken, resolveReefclawUserId, } from './config/user-data-stream-config.js';
 import { TradeStoreClient } from './ingest/trade-store-client.js';
@@ -912,6 +914,14 @@ const paperTradingPlugin = {
         let intelligenceUrl = 'https://intel.reefclaw.com';
         let exchangeConfig = null;
         let tradingMode = 'PAPER';
+        // Trading venue (multi-venue Phase 0 — docs/HYPERLIQUID_INTEGRATION_PLAN.md).
+        // Absent config field = 'binance', so every pre-venue install is untouched.
+        let venue = 'binance';
+        // exchange.testnet as written on disk — needed independently of
+        // exchangeConfig because the hyperliquid venue never builds a Binance
+        // credential config (Phase 0 gate) but its keyless public API still needs
+        // the mainnet/testnet routing.
+        let venueTestnet = false;
         let signalsEvaluator = 'central';
         let signalsSymbols = [];
         try {
@@ -928,9 +938,18 @@ const paperTradingPlugin = {
                 if (Array.isArray(rcConfig?.signals?.symbols)) {
                     signalsSymbols = rcConfig.signals.symbols.map((s) => String(s).toUpperCase());
                 }
-                // Read exchange credentials (Phase 9b)
+                // Read exchange credentials (Phase 9b) + venue (multi-venue Phase 0)
                 const exchange = rcConfig?.exchange;
-                if (exchange?.apiKey && exchange?.secret) {
+                const venueParse = parseVenue(exchange?.venue);
+                venue = venueParse.venue;
+                venueTestnet = exchange?.testnet === true;
+                if (venueParse.unrecognized) {
+                    logger.warn(TAG, `Unrecognized exchange.venue '${venueParse.unrecognized}' in plugin-config — treating as 'binance'`);
+                }
+                // apiKey/secret are a BINANCE credential pair; never build a Binance
+                // client config for another venue (a hyperliquid block carries
+                // walletAddress/agentPrivateKey instead — consumed from Phase 3 on).
+                if (venue === 'binance' && exchange?.apiKey && exchange?.secret) {
                     exchangeConfig = {
                         apiKey: exchange.apiKey,
                         secret: exchange.secret,
@@ -964,6 +983,14 @@ const paperTradingPlugin = {
         else {
             logger.warn(TAG, 'No connection token found — get_market_intel will return errors');
         }
+        // Venue support gate (multi-venue Phase 0). Checked BEFORE the credentials
+        // gate so a hyperliquid config gets the accurate diagnosis ("venue not
+        // supported yet"), not a misleading "missing API keys". Fallback-to-PAPER,
+        // never a throw — register() must stay non-crashing.
+        if (tradingMode !== 'PAPER' && !isLiveVenueSupported(venue)) {
+            logger.warn(TAG, `Trading mode ${tradingMode} on venue '${venue}' is not supported in this build — falling back to PAPER (live support arrives in Phase 3 of docs/HYPERLIQUID_INTEGRATION_PLAN.md)`);
+            tradingMode = 'PAPER';
+        }
         // Validate trading mode vs credentials
         if (tradingMode !== 'PAPER' && !exchangeConfig) {
             logger.warn(TAG, `Trading mode ${tradingMode} requires exchange API keys — falling back to PAPER`);
@@ -1063,6 +1090,9 @@ const paperTradingPlugin = {
             // closure — only invoked on a fill, long after `runtime` is built), so it
             // follows a live<->paper reconnect.
             resolveMode: () => (runtime.adapter.isLive ? 'live' : 'paper'),
+            // Venue tag (positions.exchange, migration 0058) — static per process;
+            // a venue change requires config edit + restart.
+            venue,
         };
         if (positionDecisionsClient) {
             logger.info(TAG, `Journal close-on-reduce-only-fill ${closeOnReduceOnlyFill ? 'ENABLED' : 'disabled'}`);
@@ -1146,6 +1176,11 @@ const paperTradingPlugin = {
                     tradeIngest = {
                         client: new TradeStoreClient({ baseUrl: ingestBaseUrl, ingestToken }),
                         userId: reefclawUserId,
+                        // Venue-derived FillEvent.exchange — 'binance_futures' for the
+                        // binance venue, i.e. byte-identical to the pre-venue literal
+                        // WsIngest defaulted to. Half of the (exchange, exchange_trade_id)
+                        // audit-trail idempotency key; never a fresh string literal.
+                        exchange: fillExchangeId(venue),
                     };
                     logger.info(TAG, `User-data stream dbWrite=on — WS audit-trail ingest wired to ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
                 }
@@ -1203,7 +1238,12 @@ const paperTradingPlugin = {
                     logger.warn(TAG, `approval mode=${approvalModeForTool} but WEBAPP_INGEST_TOKEN or REEFCLAW_USER_ID env missing — proposal path disabled`);
                     approvalModeForTool = 'off';
                 }
-                const liveAdapter = new LiveAdapter(exchangeConfig, tradingMode, microLiveConfig, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, autoCapture);
+                // Venue-dispatched construction (multi-venue Phase 0). For 'binance'
+                // this is a pure pass-through to `new LiveAdapter(...)` — identical
+                // args, identical behavior; the unsupported-venue arm is unreachable
+                // here because the isLiveVenueSupported() gate above already fell back
+                // to PAPER. Phase 3 adds the hyperliquid adapter inside the factory.
+                const liveAdapter = createLiveAdapter(venue, exchangeConfig, tradingMode, microLiveConfig, bracketMode, userDataStreamMode, userDataStreamTunables, tradeIngest, autoCapture);
                 adapter = liveAdapter;
                 // ---- Approval-mode Phase B — start ProposalDecisionListener ----
                 // Started only when approval.mode='per_trade' AND proposalManagerCtx
@@ -1320,11 +1360,64 @@ const paperTradingPlugin = {
         else {
             adapter = new PaperAdapter(simulator);
         }
+        // PAPER market-data source selection.
+        //
+        // Venue precedence (Hyperliquid Phase 1 — docs/HYPERLIQUID_INTEGRATION_PLAN.md):
+        // the configured VENUE decides which exchange prices paper mode, full stop.
+        // venue='hyperliquid' → every public read (PaperMarketFeed marks, the
+        // simulator's fill prices, fetch_ticker/fetch_ohlcv/get_orderbook tools)
+        // comes from Hyperliquid's keyless /info endpoints; the Binance-only
+        // `paperMarketDataSource:'intel'` escape hatch does not apply (intel has
+        // no HL rows until Phase 2 — silently serving Binance prices for a
+        // Hyperliquid book would be a lie, the exact class the symbol-translation
+        // rule forbids).
+        //
+        // Binance venue (default) is unchanged: a host Binance geo-blocks (HTTP
+        // 451) can route PRICE reads through the intel service by setting
+        // plugin-config `paperMarketDataSource:'intel'` (GET /api/price/:symbol).
+        // LIVE always uses the real exchange, and the readiness reporter probes
+        // the CONFIGURED venue. Kill-switch RC_PAPER_MARKET_DATA=binance forces
+        // the Binance-direct default (binance venue only).
+        //
+        // hlPublicApi is constructed once per process when the venue is
+        // hyperliquid — shared by the paper data path and the readiness probe.
+        const hlPublicApi = venue === 'hyperliquid' ? new HyperliquidPublicApi({ testnet: venueTestnet }) : null;
+        let configuredPaperSource;
+        try {
+            configuredPaperSource = readPluginConfig().paperMarketDataSource;
+        }
+        catch {
+            configuredPaperSource = undefined;
+        }
+        const paperDataSource = process.env.RC_PAPER_MARKET_DATA === 'binance'
+            ? 'binance'
+            : configuredPaperSource ?? 'binance';
+        const useIntelPaperData = venue === 'binance' &&
+            !adapter.isLive && paperDataSource === 'intel' && connectionToken.length > 0;
+        const marketDataApi = !adapter.isLive && hlPublicApi
+            ? hlPublicApi
+            : useIntelPaperData
+                ? new IntelPublicApi({ connectionToken, intelligenceUrl })
+                : binanceApi;
+        if (!adapter.isLive && hlPublicApi) {
+            logger.info(TAG, `PAPER market data sourced from Hyperliquid${venueTestnet ? ' TESTNET' : ''} (venue=hyperliquid) — use USDC pairs (e.g. BTC/USDC)`);
+            if (paperDataSource === 'intel') {
+                logger.warn(TAG, 'paperMarketDataSource=intel is a Binance-venue option — ignored on venue=hyperliquid (intel has no Hyperliquid rows until Phase 2)');
+            }
+        }
+        else if (useIntelPaperData) {
+            logger.warn(TAG, 'PAPER market data routed through intel (paperMarketDataSource=intel) — prices from GET /api/price; live + readiness still use Binance directly');
+        }
+        else if (venue === 'binance' && !adapter.isLive && paperDataSource === 'intel' && connectionToken.length === 0) {
+            logger.warn(TAG, 'paperMarketDataSource=intel requested but no connection token — falling back to Binance direct (which will 451 on a geo-blocked host)');
+        }
         // Build tool dependencies
         // `simDeps` for tools that need the simulator directly (ticker, market structure, risk scenario)
         // `adapterDeps` for the 7 adapter-based trading tools
-        const simDeps = { binanceApi, simulator };
-        const adapterDeps = { binanceApi, adapter };
+        // Both carry `marketDataApi` (Binance direct, or intel in paper mode) so
+        // every paper market-data read follows the selected source at once.
+        const simDeps = { binanceApi: marketDataApi, simulator };
+        const adapterDeps = { binanceApi: marketDataApi, adapter };
         // ---- Plugin runtime (mutable holder) ----
         // Owns the adapter + mode + stop-watcher and exposes `reconnect()` so the
         // operator can swap credentials / trading mode from the dashboard without
@@ -1357,7 +1450,7 @@ const paperTradingPlugin = {
         // resting limits fill. Paper-only — started here when the boot adapter is
         // paper; PluginRuntime.reconnect() stops it on a switch to live and
         // restarts it on a switch back to paper. Reuses the ban-gated fetchTicker.
-        const marketFeed = new PaperMarketFeed(binanceApi, simulator);
+        const marketFeed = new PaperMarketFeed(marketDataApi, simulator);
         if (!adapter.isLive) {
             marketFeed.start();
         }
@@ -2022,16 +2115,19 @@ const paperTradingPlugin = {
         pluginInitialised = true;
         logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
         // Agent-readiness reporter (docs/AGENT_READINESS_GATE_PLAN.md Phase 1):
-        // probe host→Binance reachability (HTTP 451 geo-block) + clock drift on the
-        // host and POST a plain-English report to the webapp, so a silently-broken
-        // agent shows an actionable dashboard alert instead of a false green.
-        // Advisory + fire-and-forget; no token → no-op. Runs here once (guarded by
-        // the pluginInitialised early-return → once per process) + on an unref'd
-        // interval inside the reporter.
+        // probe host→venue reachability (Binance HTTP 451 geo-block / Hyperliquid
+        // /info) + clock drift on the host and POST a plain-English report to the
+        // webapp, so a silently-broken agent shows an actionable dashboard alert
+        // instead of a false green. Probes ONLY the configured venue — on a
+        // Binance-451 host trading Hyperliquid a Binance probe would be a
+        // permanent false alarm. Advisory + fire-and-forget; no token → no-op.
+        // Runs here once (guarded by the pluginInitialised early-return → once per
+        // process) + on an unref'd interval inside the reporter.
         startReadinessReporter({
             apiBaseUrl,
             token: resolveIngestToken({ connectionToken }),
-            binanceApi,
+            venue,
+            publicApi: hlPublicApi ?? binanceApi,
             toolCount: toolNames.length,
         });
         maybeStartConnectorSupervisor();

package/ingest/position-auto-capture.d.ts

@@ -21,6 +21,11 @@ export interface AutoCaptureContext {
      *  from the current adapter (so it follows a runtime reconnect). Tags the
      *  journal position row so paper and live entries can be segregated. */
     resolveMode?: () => 'paper' | 'live';
+    /** Venue this gateway trades ('binance' | 'hyperliquid'). Static per process
+     *  — changing venue requires a config edit + restart (plan §5.2), so unlike
+     *  `resolveMode` this is a plain value, not a resolver. Tags journal rows
+     *  (positions.exchange, migration 0058). */
+    venue?: 'binance' | 'hyperliquid';
 }
 export interface CreateOrderInputs {
     symbol: string;

package/ingest/position-auto-capture.js

@@ -85,6 +85,7 @@ export async function onCreateOrderFilled(ctx, inputs, order) {
         currentSize: filledQty,
         avgEntryPrice: fillPrice,
         mode: ctx.resolveMode?.(),
+        exchange: ctx.venue,
     };
     // postPosition is awaited — we need the UUID before posting the entry row.
     const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
@@ -253,6 +254,7 @@ export async function onWsFillObserved(ctx, fill) {
         currentSize: fill.fillSize,
         avgEntryPrice: fill.fillPrice,
         mode: ctx.resolveMode?.(),
+        exchange: ctx.venue,
     };
     const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
     if (!positionId) {
@@ -332,8 +334,12 @@ async function handleReduceOnlyExit(ctx, fill) {
         regimeConfidence: 0.5,
         fillPrice: fill.fillPrice,
         fillSize: Math.abs(fill.fillSize),
-        // realizedPnl is Binance-exact (summed across exit fills). When it's a true
-        // break-even 0 the webapp recomputes from entries server-side — harmless.
+        // realizedPnl is Binance-exact (summed across exit fills); the zeros below
+        // are filled in PER-METRIC by the webapp close route (price-based R from
+        // the pinned invalidation_price, mfe/give-back from the last review — see
+        // webapp lib/api/close-metrics.ts). The route's old all-four-zero gate
+        // meant this non-zero PnL used to suppress that fill-in entirely, persisting
+        // realized_r=0 on every bracket_fill close (the 2026-07-11 zero-hole).
         realizedPnl,
         realizedR: 0,
         mfeRAtClose: 0,

package/ingest/position-decisions-client.d.ts

@@ -17,6 +17,10 @@ export interface PositionUpsertPayload {
      *  journal row so paper and live positions can be segregated. Omitted only
      *  if the active adapter can't be resolved (treated as legacy/NULL). */
     mode?: 'paper' | 'live';
+    /** Venue the position was opened on ('binance' | 'hyperliquid') — journal /
+     *  analytics segmentation (fees + funding cadence differ per venue).
+     *  Absent → NULL (legacy binance), mirroring `mode`. Migration 0058. */
+    exchange?: string;
 }
 export interface PositionEntryPayload {
     positionId: string;

package/ingest/readiness-reporter.d.ts

@@ -1,9 +1,23 @@
-import { type ReadinessReport } from '@reefclaw/shared';
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import { type ReadinessReport, type VenueId } from '@reefclaw/shared';
+/** Venue-agnostic reachability probe — BinancePublicApi.probeReachability and
+ *  HyperliquidPublicApi.probeReachability both return exactly this shape. */
+export interface VenueReachabilityProbe {
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
+}
 export interface ReadinessReporterOptions {
     apiBaseUrl: string;
     token: string;
-    binanceApi: Pick<BinancePublicApi, 'probeReachability'>;
+    /** Which venue this agent trades — decides the reachability check id
+     *  (binance_reachable vs hyperliquid_reachable) and which host `publicApi`
+     *  probes. The reporter probes ONLY the configured venue: on a
+     *  Binance-451-blocked host trading Hyperliquid, a Binance probe would be
+     *  a permanent false alarm (plan §5.11). */
+    venue: VenueId;
+    /** Public API of the CONFIGURED venue (probe only). */
+    publicApi: VenueReachabilityProbe;
     /** Number of trading tools registered (a health signal). */
     toolCount: number;
     fetchImpl?: typeof fetch;
@@ -11,8 +25,17 @@ export interface ReadinessReporterOptions {
     requestTimeoutMs?: number;
 }
 /** Run every connect-phase check once and assemble the report. Exported for
- *  unit tests. */
-export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'binanceApi' | 'toolCount'>): Promise<ReadinessReport>;
+ *  unit tests.
+ *
+ *  `bootWarmup` marks the FIRST cycle, which fires during gateway boot while
+ *  the event loop is congested (WS start, snapshot, seed all racing). That
+ *  delay between the probe's server-time response and the local `Date.now()`
+ *  read inflates the apparent clock drift — observed −4112ms at boot
+ *  self-correcting to −108ms on the next 5-min cycle. During warm-up a
+ *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
+ *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
+ *  skewed clock still surfaces on cycle 2. */
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount'>, bootWarmup?: boolean): Promise<ReadinessReport>;
 /** Test-only — reset the singleton guard between unit tests. */
 export declare function __resetReadinessReporterForTests(): void;
 /** Fire the readiness report once at boot then on an unref'd interval. */

package/ingest/readiness-reporter.js

@@ -24,10 +24,24 @@ function resolveIntervalMs(explicit) {
     return Math.max(MIN_INTERVAL_MS, raw);
 }
 /** Run every connect-phase check once and assemble the report. Exported for
- *  unit tests. */
-export async function collectReadiness(opts) {
+ *  unit tests.
+ *
+ *  `bootWarmup` marks the FIRST cycle, which fires during gateway boot while
+ *  the event loop is congested (WS start, snapshot, seed all racing). That
+ *  delay between the probe's server-time response and the local `Date.now()`
+ *  read inflates the apparent clock drift — observed −4112ms at boot
+ *  self-correcting to −108ms on the next 5-min cycle. During warm-up a
+ *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
+ *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
+ *  skewed clock still surfaces on cycle 2. */
+export async function collectReadiness(opts, bootWarmup = false) {
     const now = Date.now();
     const checks = [];
+    // The venue decides which reachability check this report carries; the copy
+    // for both ids lives in shared/src/readiness.ts. Clock drift comes from the
+    // same probe on both venues (Binance fapi serverTime / Hyperliquid
+    // exchangeStatus.time — live-verified 2026-07-11).
+    const reachId = opts.venue === 'hyperliquid' ? 'hyperliquid_reachable' : 'binance_reachable';
     // plugin_loaded — trivially true (this code runs inside the loaded plugin),
     // but a positive row is what proves the report path is alive at all.
     checks.push(makeReadinessCheck('plugin_loaded', 'pass', { checkedAt: now }));
@@ -36,37 +50,46 @@ export async function collectReadiness(opts) {
         detail: `${opts.toolCount} tools`,
         checkedAt: now,
     }));
-    // binance_reachable (+ clock drift from the same probe response)
-    const probe = await opts.binanceApi.probeReachability();
+    // venue reachability (+ clock drift from the same probe response)
+    const probe = await opts.publicApi.probeReachability();
     if (probe.outcome === 'reachable') {
-        checks.push(makeReadinessCheck('binance_reachable', 'pass', { checkedAt: now }));
+        checks.push(makeReadinessCheck(reachId, 'pass', { checkedAt: now }));
         const drift = probe.driftMs;
         if (drift == null) {
             checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
         }
         else {
             const abs = Math.abs(drift);
-            const status = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
+            const rawStatus = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
+            // Boot warm-up: a non-pass reading on the first cycle is untrustworthy
+            // (event-loop congestion inflates the measured drift) — report 'unknown'
+            // and let the next cycle confirm, rather than flash the banner amber/red.
+            const status = bootWarmup && rawStatus !== 'pass' ? 'unknown' : rawStatus;
             checks.push(makeReadinessCheck('clock_in_sync', status, {
-                detail: `drift ${Math.round(drift)}ms`,
+                detail: bootWarmup && rawStatus !== 'pass'
+                    ? `drift ${Math.round(drift)}ms (boot warm-up — rechecking)`
+                    : `drift ${Math.round(drift)}ms`,
                 checkedAt: now,
             }));
         }
     }
     else if (probe.outcome === 'geo_blocked') {
-        checks.push(makeReadinessCheck('binance_reachable', 'fail', { detail: 'HTTP 451', checkedAt: now }));
+        checks.push(makeReadinessCheck(reachId, 'fail', {
+            detail: opts.venue === 'binance' ? 'HTTP 451' : 'blocked (HTTP 451/403)',
+            checkedAt: now,
+        }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
     else if (probe.outcome === 'unreachable') {
         // Network/DNS/timeout — could be transient, so warn (amber) rather than
         // asserting a definitive failure. A persistent problem stays amber across
-        // re-checks; only the 451 geo-block is a hard red.
-        checks.push(makeReadinessCheck('binance_reachable', 'warn', { detail: 'unreachable', checkedAt: now }));
+        // re-checks; only the geo-block is a hard red.
+        checks.push(makeReadinessCheck(reachId, 'warn', { detail: 'unreachable', checkedAt: now }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
     else {
         // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
-        checks.push(makeReadinessCheck('binance_reachable', 'unknown', { checkedAt: now }));
+        checks.push(makeReadinessCheck(reachId, 'unknown', { checkedAt: now }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
     return {
@@ -74,7 +97,7 @@ export async function collectReadiness(opts) {
         generatedAt: now,
         overall: deriveOverallReadiness(checks),
         checks,
-        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount },
+        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount, venue: opts.venue },
     };
 }
 async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {
@@ -119,12 +142,9 @@ export function startReadinessReporter(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const intervalMs = resolveIntervalMs(opts.intervalMs);
     const timeoutMs = opts.requestTimeoutMs ?? 10_000;
-    const cycle = async () => {
+    const cycle = async (bootWarmup) => {
         try {
-            const report = await collectReadiness({
-                binanceApi: opts.binanceApi,
-                toolCount: opts.toolCount,
-            });
+            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup);
             await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
             if (report.overall === 'fail') {
                 const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');
@@ -135,8 +155,9 @@ export function startReadinessReporter(opts) {
             logger.warn(TAG, `readiness cycle failed: ${formatError(err)}`);
         }
     };
-    void cycle();
-    const timer = setInterval(() => void cycle(), intervalMs);
+    // First fire is the boot cycle (warm-up); the interval cycles are steady-state.
+    void cycle(true);
+    const timer = setInterval(() => void cycle(false), intervalMs);
     timer.unref();
     logger.info(TAG, `readiness reporter started (interval ${Math.round(intervalMs / 1000)}s)`);
 }

package/live/bracket-id.d.ts

@@ -1,3 +1,4 @@
+import type { VenueId } from '@reefclaw/shared';
 import type { BracketId, BracketRole } from './bracket-types.js';
 /** Generate a fresh 16-char hex bracketId. */
 export declare function generateBracketId(): BracketId;
@@ -16,3 +17,11 @@ export declare function parseBracketCid(cid: string): {
 /** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
  *  — true for both the current and legacy schemes. */
 export declare function isBracketCid(cid: string): boolean;
+/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
+ *  parser; other venues return null until their scheme ships. */
+export declare function parseBracketClientId(venue: VenueId, cid: string): {
+    bracketId: BracketId;
+    role: BracketRole;
+} | null;
+/** Venue-aware isBracketCid. */
+export declare function isBracketClientId(venue: VenueId, cid: string): boolean;

package/live/bracket-id.js

@@ -79,3 +79,21 @@ export function parseBracketCid(cid) {
 export function isBracketCid(cid) {
     return CID_REGEX.test(cid) || LEGACY_CID_REGEX.test(cid);
 }
+// ---- Venue-dispatched recognition (multi-venue Phase 0 seam) ----
+//
+// ALL bracket client-order-id recognition stays centralized in THIS module —
+// the brackets.md rule ("never hardcode an rc-/bkt regex elsewhere") extends
+// per-venue. Binance = the bkt/rc- schemes above. Hyperliquid client order
+// ids are 128-bit hex cloids with a different scheme (hl-cloid.ts, Phase 3 of
+// docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.7) and will be dispatched from
+// here; until then the hyperliquid arm recognises nothing, which is correct —
+// this build never emits an HL bracket order.
+/** Venue-aware parseBracketCid. Binance delegates to the existing dual-scheme
+ *  parser; other venues return null until their scheme ships. */
+export function parseBracketClientId(venue, cid) {
+    return venue === 'binance' ? parseBracketCid(cid) : null;
+}
+/** Venue-aware isBracketCid. */
+export function isBracketClientId(venue, cid) {
+    return venue === 'binance' ? isBracketCid(cid) : false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "ReefClaw trading plugin for OpenClaw \u2014 paper trading with real Binance market data, plus the ReefClaw dashboard connector (supervised by OpenClaw, no service manager needed). Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",
@@ -22,7 +22,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@reefclaw/shared": "0.1.0",
+    "@reefclaw/shared": "0.1.1",
     "ccxt": "4.5.37",
     "json5": "2.2.3",
     "ws": "8.19.0"

package/tools/close-position.d.ts

@@ -1,11 +1,11 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { CcxtOrder } from '../types.js';
 import { type ClosePositionArgs } from './assessment-validation.js';
 import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
 import { type ExitGateMode } from '../config/position-review-config.js';
 export declare function closePositionTool(args: ClosePositionArgs, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
     adapter: IExchangeAdapter;
     autoCapture?: AutoCaptureContext;
     /** Override for tests — production reads from plugin-config.json on each

package/tools/create-order.d.ts

@@ -1,4 +1,4 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { CcxtOrder } from '../types.js';
 import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
@@ -21,7 +21,7 @@ export declare function createOrderTool(args: {
     realization_rule?: unknown;
     supersedes_id?: string;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
     adapter: IExchangeAdapter;
     autoCapture?: AutoCaptureContext;
     /** Approval-mode wiring. The same ProposalManager handles both modes;

package/tools/fetch-ohlcv.d.ts

@@ -1,11 +1,11 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 import type { CcxtOHLCV } from '../types.js';
 export declare function fetchOhlcvTool(args: {
     symbol: string;
     timeframe?: string;
     limit?: number;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
 }): Promise<CcxtOHLCV[] | {
     error: string;
 }>;

package/tools/fetch-ticker.d.ts

@@ -1,10 +1,10 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { CcxtTicker } from '../types.js';
 export declare function fetchTickerTool(args: {
     symbol: string;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
     simulator: ExchangeSimulator;
 }): Promise<CcxtTicker | {
     error: string;

package/tools/get-crypto-metrics.d.ts

@@ -1,4 +1,4 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 export interface CryptoMetricsResult {
     symbol: string;
     fundingRate: number | null;
@@ -12,7 +12,7 @@ export interface CryptoMetricsResult {
 export declare function getCryptoMetricsTool(args: {
     symbol: string;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
 }): Promise<CryptoMetricsResult | {
     error: string;
 }>;

package/tools/get-market-structure.d.ts

@@ -1,4 +1,4 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 /**
  * Average True Range using Wilder's smoothing.
  * Input: OHLCV candles array, period (default 14).
@@ -41,7 +41,7 @@ export declare function getMarketStructureTool(args: {
     symbol: string;
     timeframes?: string[];
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
 }): Promise<MarketStructureResult | {
     error: string;
 }>;

package/tools/get-orderbook.d.ts

@@ -1,4 +1,4 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 export interface OrderbookResult {
     symbol: string;
     bids: [number, number][];
@@ -15,7 +15,7 @@ export declare function getOrderbookTool(args: {
     symbol: string;
     depth?: number;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
 }): Promise<OrderbookResult | {
     error: string;
 }>;

package/tools/get-volume-analysis.d.ts

@@ -1,4 +1,4 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 export interface VolumeAnalysisResult {
     symbol: string;
     timeframe: string;
@@ -15,7 +15,7 @@ export declare function getVolumeAnalysisTool(args: {
     symbol: string;
     timeframe?: string;
 }, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
 }): Promise<VolumeAnalysisResult | {
     error: string;
 }>;

package/tools/helpers.d.ts

@@ -1,12 +1,13 @@
-import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
 import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
 import type { CcxtTicker } from '../types.js';
 /**
- * Fetch the latest ticker from Binance and update the simulator.
+ * Fetch the latest ticker from the configured market-data source (Binance, or
+ * intel in paper mode on a geo-blocked host) and update the simulator.
  * Returns the ticker on success, or an error object on failure.
  */
 export declare function fetchCurrentPrice(symbol: string, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
     simulator: ExchangeSimulator;
 }): Promise<CcxtTicker | {
     error: string;
@@ -16,7 +17,7 @@ export declare function fetchCurrentPrice(symbol: string, deps: {
  * Best-effort: never throws. Skips fetch if cached book is fresh enough.
  */
 export declare function fetchOrderBook(symbol: string, deps: {
-    binanceApi: BinancePublicApi;
+    binanceApi: PublicMarketDataApi;
     simulator: ExchangeSimulator;
 }): Promise<void>;
 /** Type guard: check if the result is an error object */

package/tools/helpers.js

@@ -1,6 +1,7 @@
 // Shared helpers for tool implementations.
 /**
- * Fetch the latest ticker from Binance and update the simulator.
+ * Fetch the latest ticker from the configured market-data source (Binance, or
+ * intel in paper mode on a geo-blocked host) and update the simulator.
  * Returns the ticker on success, or an error object on failure.
  */
 export async function fetchCurrentPrice(symbol, deps) {

package/types.d.ts

@@ -102,9 +102,28 @@ export interface PluginConfig {
     quoteCurrency: string;
 }
 export declare const DEFAULT_CONFIG: PluginConfig;
-/** Exchange credentials for shadow/live modes. Read from openclaw.json. */
+/** Exchange credentials for shadow/live modes. Read from plugin-config.json's
+ *  `exchange` block (openclaw.json legacy fallback). Which fields matter
+ *  depends on `venue` (docs/HYPERLIQUID_INTEGRATION_PLAN.md §5.2):
+ *
+ *    binance (default, and the only live-supported venue until Phase 3) —
+ *      apiKey + secret (HMAC pair) are required; walletAddress/agentPrivateKey
+ *      are ignored.
+ *    hyperliquid — walletAddress (MASTER wallet address, 0x…, used for
+ *      queries; never its private key) + agentPrivateKey (an approved
+ *      agent/API wallet's key — signs orders, cannot withdraw). apiKey/secret
+ *      are meaningless. Boot falls back to PAPER for this venue until the
+ *      Phase 3 adapter ships.
+ *
+ *  apiKey/secret stay required at the type level because every constructed
+ *  instance today feeds BinancePrivateApi; the on-disk JSON is parsed, not
+ *  type-constructed, so an HL block without them is readable. Phase 3
+ *  restructures this into a per-venue discriminated union. */
 export interface ExchangeConfig {
+    venue?: 'binance' | 'hyperliquid';
     apiKey: string;
     secret: string;
     testnet?: boolean;
+    walletAddress?: string;
+    agentPrivateKey?: string;
 }

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

@@ -0,0 +1,52 @@
+import type { CcxtTicker, CcxtOHLCV } from '../../types.js';
+import type { OrderBookDepth } from '../../simulator/types.js';
+import type { PublicMarketDataApi } from '../../ccxt/public-market-data-api.js';
+export interface HyperliquidPublicApiOptions {
+    testnet?: boolean;
+    /** Test seam — injected ccxt exchange instance. */
+    exchange?: any;
+    fetchImpl?: typeof fetch;
+}
+export declare class HyperliquidPublicApi implements PublicMarketDataApi {
+    private exchange;
+    private readonly testnet;
+    private readonly fetchImpl;
+    private readonly tickerTtlMs;
+    /** One upstream fetchTickers call serves every symbol within the TTL. */
+    private tickersCache;
+    private tickersInflight;
+    constructor(opts?: HyperliquidPublicApiOptions);
+    private baseUrl;
+    /** 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. */
+    private venueSymbol;
+    /** Fetch-all-tickers with a short TTL + inflight dedup. Returns a map keyed
+     *  by ccxt symbol, or null on failure. */
+    private getTickers;
+    fetchTickerRaw(symbol: string): Promise<Record<string, any> | null>;
+    /** Ticker from the cached all-assets snapshot. Hyperliquid's asset contexts
+     *  carry mark/mid rather than a trade-tape bid/ask; absent fields fall back
+     *  to `last` with zero modeled spread — the paper fill engine models
+     *  slippage itself (same convention as IntelPublicApi). */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    fetchFundingRate(symbol: string): Promise<Record<string, any> | null>;
+    fetchOpenInterest(symbol: string): Promise<Record<string, any> | null>;
+    /** l2Book — Hyperliquid serves at most 20 levels/side (plan §3.6). */
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    /** candleSnapshot — only the most recent 5000 candles exist per (coin,
+     *  interval) (plan §3.6); requests inside that window behave like Binance. */
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | 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. */
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
+}

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,19 @@
+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;
+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,40 @@
+// 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);
+}
+/** 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");
+    }
+}