@reefclaw/openclaw-plugin 0.1.2 → 0.1.4

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.2",
+  "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/skills/reefclaw/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:

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;
+    }>;
+}