@reefclaw/openclaw-plugin 0.1.3 → 0.1.5

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.5",
   "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/persistence/state-manager.d.ts

@@ -39,4 +39,28 @@ export declare class StateManager {
     loadSync(): SimulatorState | null;
     /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
     loadOrDefaultSync(startingBalance: number, quoteCurrency: string): SimulatorState;
+    private saveSyncSafe;
 }
+export interface PaperQuoteMigrationResult {
+    state: SimulatorState;
+    migrated: boolean;
+    fromQuote: string;
+    releasedPositions: number;
+    droppedOrders: number;
+}
+/** Migrate a persisted paper state whose quote currency no longer matches the
+ *  configured venue's (issue #174 — e.g. a USDT wallet after switching to the
+ *  USDC-quoted hyperliquid venue). Pure; returns the input untouched when the
+ *  quotes already match.
+ *
+ *  Semantics (equity-preserving):
+ *  - Open positions are released at their entry price: opening deducted the
+ *    full entry notional from the wallet (spot-collateral model), so that
+ *    notional is credited back before the position rows — which reference the
+ *    OLD venue's symbols and are unpriceable on the new one — are dropped.
+ *  - Unfilled open orders never debited the wallet (fills do) — just dropped.
+ *  - Balances carry 1:1 (USDT↔USDC are both dollar stables; paper precision),
+ *    merging into any existing balance under the new quote.
+ *  - Trade history is kept (display-only). savedAt is bumped so the other
+ *    process's replaceState() staleness guard accepts the migrated snapshot. */
+export declare function migratePaperQuoteCurrency(state: SimulatorState, expectedQuote: string): PaperQuoteMigrationResult;

package/persistence/state-manager.js

@@ -144,11 +144,26 @@ export class StateManager {
     /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
     loadOrDefaultSync(startingBalance, quoteCurrency) {
         const loaded = this.loadSync();
-        if (loaded)
-            return loaded;
+        if (loaded) {
+            // Venue switch heal (issue #174): a persisted wallet quoted in the OLD
+            // venue's currency reads as $0 equity on the new venue. Migrate 1:1
+            // (USDT↔USDC), preserving total equity exactly.
+            const mig = migratePaperQuoteCurrency(loaded, quoteCurrency);
+            if (mig.migrated) {
+                logger.info(TAG, `Paper wallet quote migrated ${mig.fromQuote} → ${quoteCurrency} (venue switch): ` +
+                    `released ${mig.releasedPositions} open position(s) at entry price, ` +
+                    `dropped ${mig.droppedOrders} unfilled order(s), balances carried 1:1`);
+                this.saveSyncSafe(mig.state, 'migrated');
+            }
+            return mig.state;
+        }
         const state = createDefaultState(startingBalance, quoteCurrency);
         logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
         // Save synchronously so state persists immediately
+        this.saveSyncSafe(state, 'initial');
+        return state;
+    }
+    saveSyncSafe(state, label) {
         try {
             const dir = dirname(this.statePath);
             if (!existsSync(dir)) {
@@ -157,8 +172,51 @@ export class StateManager {
             writeFileSync(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
         }
         catch (err) {
-            logger.error(TAG, `Failed to save initial state: ${err instanceof Error ? err.message : String(err)}`);
+            logger.error(TAG, `Failed to save ${label} state: ${err instanceof Error ? err.message : String(err)}`);
         }
-        return state;
     }
 }
+/** Migrate a persisted paper state whose quote currency no longer matches the
+ *  configured venue's (issue #174 — e.g. a USDT wallet after switching to the
+ *  USDC-quoted hyperliquid venue). Pure; returns the input untouched when the
+ *  quotes already match.
+ *
+ *  Semantics (equity-preserving):
+ *  - Open positions are released at their entry price: opening deducted the
+ *    full entry notional from the wallet (spot-collateral model), so that
+ *    notional is credited back before the position rows — which reference the
+ *    OLD venue's symbols and are unpriceable on the new one — are dropped.
+ *  - Unfilled open orders never debited the wallet (fills do) — just dropped.
+ *  - Balances carry 1:1 (USDT↔USDC are both dollar stables; paper precision),
+ *    merging into any existing balance under the new quote.
+ *  - Trade history is kept (display-only). savedAt is bumped so the other
+ *    process's replaceState() staleness guard accepts the migrated snapshot. */
+export function migratePaperQuoteCurrency(state, expectedQuote) {
+    const fromQuote = state.config?.quoteCurrency ?? 'USDT';
+    if (fromQuote === expectedQuote) {
+        return { state, migrated: false, fromQuote, releasedPositions: 0, droppedOrders: 0 };
+    }
+    const next = JSON.parse(JSON.stringify(state));
+    next.config = { ...next.config, quoteCurrency: expectedQuote };
+    const old = next.wallet[fromQuote] ?? { total: 0, available: 0, locked: 0 };
+    let releasedPositions = 0;
+    for (const pos of next.positions ?? []) {
+        const notional = pos.entryPrice * pos.quantity;
+        if (Number.isFinite(notional) && notional > 0) {
+            old.total += notional;
+            old.available += notional;
+        }
+        releasedPositions++;
+    }
+    const droppedOrders = (next.openOrders ?? []).length;
+    next.positions = [];
+    next.openOrders = [];
+    const target = next.wallet[expectedQuote] ?? { total: 0, available: 0, locked: 0 };
+    target.total += old.total;
+    target.available += old.available;
+    target.locked += old.locked;
+    next.wallet[expectedQuote] = target;
+    delete next.wallet[fromQuote];
+    next.savedAt = Date.now();
+    return { state: next, migrated: true, fromQuote, releasedPositions, droppedOrders };
+}

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-crypto-metrics.js

@@ -3,9 +3,16 @@
 // because Binance's 24hr ticker endpoint does NOT include funding/OI data.
 export async function getCryptoMetricsTool(args, deps) {
     try {
-        // Funding rate & OI only exist on perpetual futures.
-        // Convert spot symbols (BTC/USDT) to perp format (BTC/USDT:USDT).
-        const perpSymbol = args.symbol.includes(':') ? args.symbol : `${args.symbol}:USDT`;
+        // Funding rate & OI only exist on perpetual futures. Convert a canonical
+        // symbol to its linear-perp ccxt form by settling in the QUOTE currency
+        // (BTC/USDT → BTC/USDT:USDT on Binance, BTC/USDC → BTC/USDC:USDC on
+        // Hyperliquid). A hardcoded :USDT suffix produced the nonsense form
+        // BTC/USDC:USDT on the HL venue (seen live, wisekid soak 2026-07-12) —
+        // never silently translate quote assets across venues.
+        const quote = args.symbol.split('/')[1];
+        const perpSymbol = args.symbol.includes(':') || !quote
+            ? args.symbol
+            : `${args.symbol}:${quote}`;
         // Fetch funding rate and open interest in parallel (separate API endpoints)
         const [fundingData, oiData, tickerData] = await Promise.all([
             deps.binanceApi.fetchFundingRate(perpSymbol),

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