@reefclaw/openclaw-plugin 0.1.4 → 0.1.5

package/index.js

@@ -19,7 +19,7 @@ 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 { createLiveAdapter, fillExchangeId, isLiveVenueSupported, parseVenue, } from './venues/registry.js';
+import { createLiveAdapter, fillExchangeId, isLiveVenueSupported, parseVenue, venueQuoteCurrency, } 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';
@@ -876,11 +876,24 @@ const paperTradingPlugin = {
             return;
         }
         logger.info(TAG, 'Initializing paper trading plugin...');
-        // Resolve config from plugin settings
+        // Resolve config from plugin settings. The paper wallet's quote currency
+        // follows the VENUE (USDC on hyperliquid, USDT on binance — issue #174:
+        // a hardcoded USDT wallet reads as $0 equity on the USDC venue). The
+        // authoritative plugin-config read happens further down, AFTER the
+        // simulator exists — peek only the venue here; same file, same parse
+        // rules, and an unreadable config falls back to the binance default
+        // exactly like the main read does.
+        let paperQuoteCurrency = DEFAULT_CONFIG.quoteCurrency;
+        try {
+            paperQuoteCurrency = venueQuoteCurrency(parseVenue(readPluginConfig().exchange?.venue).venue);
+        }
+        catch {
+            /* unreadable plugin-config → binance default, matching the main read */
+        }
         const pluginConfig = {
             startingBalance: DEFAULT_CONFIG.startingBalance,
             symbol: DEFAULT_CONFIG.symbol,
-            quoteCurrency: DEFAULT_CONFIG.quoteCurrency,
+            quoteCurrency: paperQuoteCurrency,
         };
         logger.info(TAG, `Config: ${pluginConfig.startingBalance} ${pluginConfig.quoteCurrency}, symbol: ${pluginConfig.symbol}`);
         // Load or initialize state (sync — OpenClaw ignores async register())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.4",
+  "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",

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/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/venues/registry.d.ts

@@ -7,6 +7,11 @@ export { fillExchangeId, parseVenue };
  *  is not gated here. */
 export declare const SUPPORTED_LIVE_VENUES: ReadonlySet<VenueId>;
 export declare function isLiveVenueSupported(venue: VenueId): boolean;
+/** Paper-wallet settlement/quote currency for a venue. Hyperliquid margins
+ *  USDC linear perps; Binance USDⓈ-M paper keeps the historical USDT.
+ *  Issue #174: the paper wallet MUST follow the venue — a USDT wallet on the
+ *  USDC venue reads as $0 equity and every order fails "Insufficient USDC". */
+export declare function venueQuoteCurrency(venue: VenueId): 'USDT' | 'USDC';
 type BinanceLiveAdapterArgs = ConstructorParameters<typeof LiveAdapter>;
 /** Construct the live adapter for a venue.
  *

package/venues/registry.js

@@ -22,6 +22,13 @@ export const SUPPORTED_LIVE_VENUES = new Set(['binance']);
 export function isLiveVenueSupported(venue) {
     return SUPPORTED_LIVE_VENUES.has(venue);
 }
+/** Paper-wallet settlement/quote currency for a venue. Hyperliquid margins
+ *  USDC linear perps; Binance USDⓈ-M paper keeps the historical USDT.
+ *  Issue #174: the paper wallet MUST follow the venue — a USDT wallet on the
+ *  USDC venue reads as $0 equity and every order fails "Insufficient USDC". */
+export function venueQuoteCurrency(venue) {
+    return venue === 'hyperliquid' ? 'USDC' : 'USDT';
+}
 /** Construct the live adapter for a venue.
  *
  *  Binance: a pure pass-through to `new LiveAdapter(...)` — byte-identical to