@reefclaw/connect 0.1.6 → 0.1.8

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

package/assets/shared/fills.d.ts

@@ -1,7 +1,11 @@
 export type FillSource = 'ws' | 'rest_reconcile' | 'paper' | 'manual';
 export interface FillEvent {
     /** Exchange identifier — pair with exchangeTradeId for the idempotency key.
-     *  Currently always 'binance_futures'; multi-venue arrives in a later phase. */
+     *  One of FILL_EXCHANGE_ID's values (venues/symbols.ts): 'binance_futures'
+     *  (the historical literal — every pre-multi-venue row) or 'hyperliquid'.
+     *  Kept `string` (not the union) so an old webapp ingests fills from a newer
+     *  plugin; producers MUST source it from fillExchangeId(venue), never a
+     *  fresh literal. */
     exchange: string;
     /** Stable, exchange-issued trade id.  Required for source IN ('ws',
      *  'rest_reconcile').  May be a synthetic 'paper-<uuid>' for source='paper'. */

package/assets/shared/index.d.ts

@@ -8,3 +8,7 @@ export type { FillEvent, FillSource } from './fills.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
 export type { Direction, OhlcvBar, TradeFlowBucket, GlobalMarketContext, MarketContext, SignalCondition, StrategyEvaluation, StrategyDefinition, SignalEvent, StrategyState, SignalSnapshot, } from './signals/types.js';
 export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, EntryRuleConfig, StopRuleConfig, DirectionRule, PrimaryTimeframe, StrategyConfig, } from './signals/conditions/types.js';
+export type { VenueId } from './venues/symbols.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, } from './readiness.js';
+export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/index.js

@@ -3,3 +3,5 @@ export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from './protocol.js';
 export { logger, setLogLevel, formatError } from './logger.js';
 export { VALID_TRADING_MODES, isTradingMode, validateModeTransition, modeRequiresCredentials, } from './trading-mode.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/readiness.d.ts

@@ -2,7 +2,7 @@ export type ReadinessStatus = 'pass' | 'warn' | 'fail' | 'unknown';
 /** Which lifecycle phase a check belongs to. `connect` runs with NO Binance API
  *  keys (covers paper trading too); `golive` needs keys (Phase 2). */
 export type ReadinessPhase = 'connect' | 'golive';
-export type ReadinessCheckId = 'binance_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered';
+export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered';
 export interface ReadinessCheck {
     /** Stable machine id. Widened to string so the webapp can render checks from a
      *  newer plugin it doesn't have the union for. */
@@ -27,6 +27,11 @@ export interface ReadinessReport {
     agent?: {
         pluginVersion?: string;
         toolCount?: number;
+        /** Trading venue this agent executes on ('binance' | 'hyperliquid').
+         *  Kept `string` so an older webapp renders reports from a newer plugin.
+         *  The webapp mirrors it into connections.exchange (display/record only —
+         *  the authoritative venue is the plugin's local config). */
+        venue?: string;
     };
 }
 interface CheckCopy {

package/assets/shared/readiness.js

@@ -13,6 +13,15 @@ export const READINESS_CHECK_COPY = {
         phase: 'connect',
         fixHint: 'Your agent host is geo-blocked by Binance (HTTP 451). Run OpenClaw from a Binance-permitted region — most EU / several Asia VPS regions work.',
     },
+    // Dormant until the Hyperliquid venue ships (docs/HYPERLIQUID_INTEGRATION_PLAN.md
+    // Phase 1): the reporter probes only the CONFIGURED venue, so this id is never
+    // emitted while venue='binance'. Landed early so older webapps render it via the
+    // string-widened ReadinessCheck.id the moment a newer plugin starts sending it.
+    hyperliquid_reachable: {
+        label: 'Hyperliquid reachable',
+        phase: 'connect',
+        fixHint: 'Your agent host cannot reach the Hyperliquid API (api.hyperliquid.xyz). Check outbound HTTPS/DNS/firewall; if the host region is restricted, run OpenClaw from a permitted region.',
+    },
     clock_in_sync: {
         label: 'Host clock in sync',
         phase: 'connect',

package/assets/shared/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;

package/assets/shared/venues/symbols.js

@@ -0,0 +1,123 @@
+// Venue identity + symbol-coordinate mapping for multi-venue support.
+//
+// Phase 0 of docs/HYPERLIQUID_INTEGRATION_PLAN.md (§5.3): the single source of
+// truth for how one market is named across the four coordinate systems —
+//
+//   layer                      binance              hyperliquid
+//   canonical (agent/webapp)   'BTC/USDT'           'BTC/USDC'
+//   CCXT unified               'BTC/USDT:USDT'      'BTC/USDC:USDC'
+//   venue-native               'BTCUSDT'            coin 'BTC' (asset index via meta)
+//   intel DB symbol            'BTCUSDT'            'HL_BTC'
+//
+// The intel namespace ('HL_' prefix) is deliberate: a distinct symbol string IS
+// venue isolation to the entire symbol-keyed intel read stack (context, cache
+// keys, conditions, facts, regime, API routes) with zero schema migration —
+// see the plan §5.3 for the trade-off vs an `exchange` column.
+//
+// Scattered `.replace('USDT', …)` conversions are the anti-pattern this module
+// replaces at NEW call sites (existing Binance sites migrate opportunistically,
+// never in the Phase 0 no-behavior-change window).
+//
+// Case rule: Hyperliquid coin names are case-sensitive ('kPEPE' = 1000 PEPE);
+// the intel symbol preserves the venue's exact casing after the 'HL_' prefix
+// ('HL_kPEPE') so round-trips are lossless. Never uppercase an HL coin.
+export const VENUE_IDS = ['binance', 'hyperliquid'];
+export function isVenueId(value) {
+    return value === 'binance' || value === 'hyperliquid';
+}
+/** 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 function parseVenue(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return { venue: 'binance' };
+    if (isVenueId(raw))
+        return { venue: raw };
+    return { venue: 'binance', unrecognized: String(raw) };
+}
+/** `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 const FILL_EXCHANGE_ID = {
+    binance: 'binance_futures',
+    hyperliquid: 'hyperliquid',
+};
+export function fillExchangeId(venue) {
+    return FILL_EXCHANGE_ID[venue];
+}
+/** Quote/settle asset of the venue's linear perps. */
+export const VENUE_QUOTE_ASSET = {
+    binance: 'USDT',
+    hyperliquid: 'USDC',
+};
+/** Prefix that namespaces Hyperliquid rows inside the intel symbol column. */
+export const HL_INTEL_PREFIX = 'HL_';
+/** Strip a CCXT settle suffix ('BTC/USDT:USDT' → 'BTC/USDT'). Same regex as
+ *  webapp/src/lib/symbols.ts normalizeSymbol — kept inline so this module has
+ *  zero imports and survives the sync-copy deploy boundary. */
+function stripSettleSuffix(symbol) {
+    return symbol.replace(/:[A-Z]+$/, '');
+}
+function splitCanonical(canonical) {
+    const stripped = stripSettleSuffix(canonical.trim());
+    const parts = stripped.split('/');
+    if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+        throw new Error(`Not a canonical BASE/QUOTE symbol: '${canonical}'`);
+    }
+    return { base: parts[0], quote: parts[1] };
+}
+/** 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 function toCcxtSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET[venue]) {
+        throw new Error(`Symbol '${canonical}' is not ${VENUE_QUOTE_ASSET[venue]}-quoted — not a ${venue} linear perp`);
+    }
+    return `${base}/${quote}:${quote}`;
+}
+/** 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 function toIntelSymbol(venue, canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (venue === 'hyperliquid') {
+        if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+            throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+        }
+        return `${HL_INTEL_PREFIX}${base}`;
+    }
+    return `${base}${quote}`;
+}
+/** 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 function fromIntelSymbol(intelSymbol) {
+    if (intelSymbol.startsWith(HL_INTEL_PREFIX)) {
+        const coin = intelSymbol.slice(HL_INTEL_PREFIX.length);
+        if (coin.length === 0) {
+            throw new Error(`Malformed intel symbol '${intelSymbol}' — empty coin after HL_ prefix`);
+        }
+        return { venue: 'hyperliquid', canonical: `${coin}/${VENUE_QUOTE_ASSET.hyperliquid}` };
+    }
+    if (intelSymbol.endsWith(VENUE_QUOTE_ASSET.binance) && intelSymbol.length > 4) {
+        const base = intelSymbol.slice(0, -VENUE_QUOTE_ASSET.binance.length);
+        return { venue: 'binance', canonical: `${base}/${VENUE_QUOTE_ASSET.binance}` };
+    }
+    return { venue: 'binance', canonical: intelSymbol };
+}
+/** 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 function toHyperliquidCoin(canonical) {
+    const { base, quote } = splitCanonical(canonical);
+    if (quote !== VENUE_QUOTE_ASSET.hyperliquid) {
+        throw new Error(`Symbol '${canonical}' is not USDC-quoted — not a Hyperliquid perp`);
+    }
+    return base;
+}

package/assets/skill/SKILL.md

@@ -39,6 +39,12 @@ You are being connected to **ReefClaw**, a supervised trading control room. Your
 
 **Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
 
+## Host requirements (check before connecting)
+
+ReefClaw trades on Binance USD-M Futures, so **the machine running this OpenClaw must be able to reach Binance** (`fapi.binance.com`). Binance geo-restricts many locations: cheap US cloud regions — and some other jurisdictions — return **HTTP 451** ("restricted location"), and the agent then cannot fetch market data or trade. This applies even in **paper mode**, which uses live Binance prices.
+
+If your market-data calls fail with `451`, this host is geo-blocked — move the agent to a Binance-permitted region (most EU and several Asia VPS regions work). This is a hosting requirement; ReefClaw cannot configure around it.
+
 ## Connecting (first run) — saving the connect message
 
 The onboarding page at [reefclaw.com/onboarding](https://reefclaw.com/onboarding) gives the user a single **connect message** that carries THREE fields: