@reefclaw/openclaw-plugin 0.1.0

package/tools/set-exchange-credentials.js

@@ -0,0 +1,80 @@
+// set_exchange_credentials — operator-only plugin tool.
+//
+// Writes Binance API key + secret to ~/.reefclaw/plugin-config.json and
+// triggers an adapter reconnect if the current mode is live. The agent
+// should NOT call this tool; it's registered for the skill's operator RPC
+// path only. PR2 will enforce that via a skill-side scope gate (operator.write).
+//
+// Security:
+//   - The secret is NEVER logged. Only a redacted fingerprint (first 4 + last 2
+//     chars of the apiKey) goes to logs / audit.
+//   - If the current mode is PAPER, credentials are written but NOT activated —
+//     the operator must explicitly call set_trading_mode to move up the ladder.
+import { updatePluginConfig, redactCredential } from '../config/plugin-config-io.js';
+import { logger } from '../logger.js';
+const TAG = 'set-exchange-credentials';
+function validate(args) {
+    if (typeof args.apiKey !== 'string' || args.apiKey.trim().length < 8) {
+        return 'apiKey must be a string of at least 8 characters';
+    }
+    if (typeof args.secret !== 'string' || args.secret.trim().length < 8) {
+        return 'secret must be a string of at least 8 characters';
+    }
+    if (args.testnet !== undefined && typeof args.testnet !== 'boolean') {
+        return 'testnet must be a boolean when provided';
+    }
+    return null;
+}
+export async function setExchangeCredentialsTool(args, deps) {
+    const validationError = validate(args);
+    if (validationError) {
+        return {
+            ok: false,
+            message: validationError,
+            fingerprint: '(not-set)',
+            reconnected: false,
+            mode: deps.runtime.mode,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    const exchange = {
+        apiKey: args.apiKey.trim(),
+        secret: args.secret.trim(),
+        testnet: args.testnet ?? false,
+    };
+    const fingerprint = redactCredential(exchange.apiKey);
+    try {
+        updatePluginConfig({ exchange }, deps.configPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `Failed to write credentials: ${msg}`);
+        return {
+            ok: false,
+            message: `Failed to persist credentials: ${msg}`,
+            fingerprint,
+            reconnected: false,
+            mode: deps.runtime.mode,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    logger.info(TAG, `Stored credentials (fingerprint: ${fingerprint}, testnet: ${exchange.testnet})`);
+    // Only reconnect if we're already in a live mode — if the operator is still
+    // in PAPER, activating the keys is a separate deliberate step via
+    // set_trading_mode. This prevents accidentally going live by saving keys.
+    let reconnected = false;
+    if (deps.runtime.mode !== 'PAPER') {
+        await deps.runtime.reconnect({ mode: deps.runtime.mode, exchange }, { adapterDeps: deps.adapterDeps });
+        reconnected = true;
+    }
+    return {
+        ok: true,
+        message: reconnected
+            ? `Credentials updated and ${deps.runtime.mode} adapter reconnected`
+            : `Credentials stored (mode is PAPER — run set_trading_mode SHADOW to activate)`,
+        fingerprint,
+        reconnected,
+        mode: deps.runtime.mode,
+        readiness: deps.runtime.adapter.readiness,
+    };
+}

package/tools/set-trading-mode.d.ts

@@ -0,0 +1,26 @@
+import type { PluginRuntime } from '../onboarding/runtime.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingMode } from '../types.js';
+export interface SetTradingModeArgs {
+    mode: TradingMode;
+    /** Optional acknowledgment flag for going live. The skill layer will set
+     *  this explicitly when the operator confirms the elevated confirmation. */
+    acknowledged?: boolean;
+}
+export interface SetTradingModeResult {
+    ok: boolean;
+    message: string;
+    previousMode: TradingMode;
+    mode: TradingMode;
+    readiness: string;
+    reason?: string;
+}
+export interface SetTradingModeDeps {
+    runtime: PluginRuntime;
+    adapterDeps: {
+        adapter: IExchangeAdapter;
+    };
+    /** Override the config file path — tests use this. */
+    configPath?: string;
+}
+export declare function setTradingModeTool(args: SetTradingModeArgs, deps: SetTradingModeDeps): Promise<SetTradingModeResult>;

package/tools/set-trading-mode.js

@@ -0,0 +1,135 @@
+// set_trading_mode — operator-only plugin tool.
+//
+// Moves the plugin between PAPER / MICRO_LIVE / LIVE, enforcing
+// the one-rung-at-a-time ladder. Requires valid exchange credentials for
+// any non-PAPER target. Rebuilds the adapter via runtime.reconnect().
+//
+// The agent should NOT call this tool; PR2 will enforce operator-only scope
+// in the skill. PR1 leaves the plugin-side handler functional but unguarded
+// because the caller chain is currently controlled end-to-end by the skill.
+import { readPluginConfig } from '../config/plugin-config-io.js';
+import { validateModeTransition, modeRequiresCredentials } from '../onboarding/mode-ladder.js';
+import { logger } from '../logger.js';
+import { recordModeTransition } from '../audit/mode-transition-audit.js';
+const TAG = 'set-trading-mode';
+const VALID_MODES = ['PAPER', 'MICRO_LIVE', 'LIVE'];
+export async function setTradingModeTool(args, deps) {
+    const previousMode = deps.runtime.mode;
+    if (!args || typeof args.mode !== 'string' || !VALID_MODES.includes(args.mode)) {
+        return {
+            ok: false,
+            message: `Invalid mode. Must be one of: ${VALID_MODES.join(', ')}`,
+            previousMode,
+            mode: previousMode,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    const target = args.mode;
+    const acknowledged = args.acknowledged === true;
+    // 1. Ladder check.
+    const ladder = validateModeTransition(previousMode, target);
+    if (!ladder.allowed) {
+        recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'ladder' });
+        return {
+            ok: false,
+            message: ladder.reason ?? 'Mode transition not allowed',
+            previousMode,
+            mode: previousMode,
+            readiness: deps.runtime.adapter.readiness,
+            reason: 'ladder',
+        };
+    }
+    // 2. If already in the target mode, no-op (no audit entry — nothing happened).
+    if (previousMode === target) {
+        return {
+            ok: true,
+            message: `Already in ${target} mode`,
+            previousMode,
+            mode: previousMode,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    // 3. Credential requirement check.
+    let exchange = null;
+    if (modeRequiresCredentials(target)) {
+        try {
+            const cfg = readPluginConfig(deps.configPath);
+            if (cfg.exchange?.apiKey && cfg.exchange?.secret) {
+                exchange = {
+                    apiKey: cfg.exchange.apiKey,
+                    secret: cfg.exchange.secret,
+                    testnet: cfg.exchange.testnet ?? false,
+                };
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'config_read_error' });
+            return {
+                ok: false,
+                message: `Cannot read config: ${msg}`,
+                previousMode,
+                mode: previousMode,
+                readiness: deps.runtime.adapter.readiness,
+                reason: 'config_read_error',
+            };
+        }
+        if (!exchange) {
+            recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'missing_credentials' });
+            return {
+                ok: false,
+                message: `${target} mode requires exchange credentials. Run set_exchange_credentials first.`,
+                previousMode,
+                mode: previousMode,
+                readiness: deps.runtime.adapter.readiness,
+                reason: 'missing_credentials',
+            };
+        }
+    }
+    // 4. Elevated confirmation for full LIVE.
+    if (target === 'LIVE' && !acknowledged) {
+        recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'acknowledgment_required' });
+        return {
+            ok: false,
+            message: `Transition to LIVE requires explicit acknowledgment (acknowledged: true)`,
+            previousMode,
+            mode: previousMode,
+            readiness: deps.runtime.adapter.readiness,
+            reason: 'acknowledgment_required',
+        };
+    }
+    // 5. Persist the new mode.
+    try {
+        const { updatePluginConfig } = await import('../config/plugin-config-io.js');
+        updatePluginConfig({ tradingMode: target }, deps.configPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'config_write_error' });
+        return {
+            ok: false,
+            message: `Failed to persist mode: ${msg}`,
+            previousMode,
+            mode: previousMode,
+            readiness: deps.runtime.adapter.readiness,
+            reason: 'config_write_error',
+        };
+    }
+    // 6. Swap the adapter.
+    await deps.runtime.reconnect({ mode: target, exchange }, { adapterDeps: deps.adapterDeps });
+    logger.info(TAG, `Transitioned ${previousMode} → ${target}`);
+    recordModeTransition({
+        previousMode,
+        targetMode: target,
+        acknowledged,
+        ok: true,
+        testnet: exchange?.testnet,
+    });
+    return {
+        ok: true,
+        message: `Trading mode changed from ${previousMode} to ${target}`,
+        previousMode,
+        mode: deps.runtime.mode,
+        readiness: deps.runtime.adapter.readiness,
+    };
+}

package/tools/test-exchange-credentials.d.ts

@@ -0,0 +1,16 @@
+export interface TestExchangeCredentialsArgs {
+    apiKey: string;
+    secret: string;
+    testnet?: boolean;
+}
+export interface TestExchangeCredentialsResult {
+    ok: boolean;
+    message: string;
+    fingerprint: string;
+    canReadBalance: boolean;
+    canReadPositions: boolean;
+    balanceUSDT: number | null;
+    testnet: boolean;
+    errors: string[];
+}
+export declare function testExchangeCredentialsTool(args: TestExchangeCredentialsArgs): Promise<TestExchangeCredentialsResult>;

package/tools/test-exchange-credentials.js

@@ -0,0 +1,100 @@
+// test_exchange_credentials — operator-only plugin tool.
+//
+// Takes a candidate Binance API key + secret and verifies them with a
+// transient, read-only call to the exchange (fetchBalance via
+// validatePermissions). Nothing is written to disk. Nothing is retained
+// after the call returns. This is the "pre-flight" check that lets the
+// dashboard say "yes these keys work, you can now click Store" before
+// the operator commits the credentials via set_exchange_credentials.
+//
+// Security:
+//   - Builds a throwaway BinancePrivateApi instance scoped to one call.
+//   - Never logs the secret — only a redacted fingerprint.
+//   - Does not touch plugin-config.json at all.
+import { BinancePrivateApi } from '../ccxt/binance-private.js';
+import { redactCredential } from '../config/plugin-config-io.js';
+import { logger, formatError } from '../logger.js';
+const TAG = 'test-exchange-credentials';
+function validate(args) {
+    if (typeof args.apiKey !== 'string' || args.apiKey.trim().length < 8) {
+        return 'apiKey must be a string of at least 8 characters';
+    }
+    if (typeof args.secret !== 'string' || args.secret.trim().length < 8) {
+        return 'secret must be a string of at least 8 characters';
+    }
+    return null;
+}
+export async function testExchangeCredentialsTool(args) {
+    const fingerprint = redactCredential(args.apiKey);
+    const err = validate(args);
+    if (err) {
+        return {
+            ok: false,
+            message: err,
+            fingerprint,
+            canReadBalance: false,
+            canReadPositions: false,
+            balanceUSDT: null,
+            testnet: args.testnet ?? false,
+            errors: [err],
+        };
+    }
+    const config = {
+        apiKey: args.apiKey.trim(),
+        secret: args.secret.trim(),
+        testnet: args.testnet ?? false,
+    };
+    logger.info(TAG, `Testing credentials (fingerprint: ${fingerprint}, testnet: ${config.testnet})`);
+    let api;
+    try {
+        api = new BinancePrivateApi(config);
+    }
+    catch (e) {
+        const msg = formatError(e);
+        return {
+            ok: false,
+            message: `Could not initialize exchange client: ${msg}`,
+            fingerprint,
+            canReadBalance: false,
+            canReadPositions: false,
+            balanceUSDT: null,
+            testnet: config.testnet ?? false,
+            errors: [msg],
+        };
+    }
+    const perms = await api.validatePermissions();
+    // Opportunistically read the balance for the result payload — if
+    // validatePermissions already proved it works, this is a no-op second
+    // call that gives the user confidence ("connected, $123.45").
+    // Supports both USDT and USDC (Binance USDⓈ-M settles in either).
+    let balanceUSDT = null;
+    if (perms.canReadBalance) {
+        try {
+            const bal = await api.fetchBalance();
+            if (bal && typeof bal.total === 'object') {
+                const usdt = bal.total.USDT ?? 0;
+                const usdc = bal.total.USDC ?? 0;
+                const sum = usdt + usdc;
+                if (Number.isFinite(sum) && sum > 0)
+                    balanceUSDT = sum;
+            }
+        }
+        catch {
+            // Ignore — we already know canReadBalance is true, so this is cosmetic.
+        }
+    }
+    const ok = perms.canReadBalance && perms.canReadPositions;
+    const message = ok
+        ? `Connection verified — USDT balance: ${balanceUSDT != null ? balanceUSDT.toFixed(2) : 'unknown'}`
+        : `API permission check failed: ${perms.errors.join('; ')}`;
+    return {
+        ok,
+        message,
+        fingerprint,
+        canReadBalance: perms.canReadBalance,
+        canReadPositions: perms.canReadPositions,
+        balanceUSDT,
+        testnet: config.testnet ?? false,
+        errors: perms.errors,
+    };
+}

package/tools/toggle-strategy.d.ts

@@ -0,0 +1,8 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface ToggleStrategyArgs {
+    name: string;
+    active: boolean;
+}
+export declare function toggleStrategyTool(args: ToggleStrategyArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/toggle-strategy.js

@@ -0,0 +1,8 @@
+// Tool: toggle_strategy — activate or deactivate a strategy.
+import { fetchIntelApi } from './intel-api.js';
+export async function toggleStrategyTool(args, deps) {
+    return fetchIntelApi(`/api/strategies/${encodeURIComponent(args.name)}/toggle`, deps, {
+        method: 'PUT',
+        body: { active: args.active },
+    });
+}

package/trading-params-cache.d.ts

@@ -0,0 +1,26 @@
+import { type IntelApiDeps } from './tools/intel-api.js';
+export interface TradingParameters {
+    regimeConfidenceFloor: number;
+    signalConfluenceThreshold: number;
+    scorecardStrongGoThreshold: number;
+    scorecardGoThreshold: number;
+    scorecardMarginalThreshold: number;
+    confidencePenaltyThreshold: number;
+    unprovenSetupScore: number;
+    rrWarningThreshold: number;
+    lossStreakQuarterSize: number;
+    lossStreakHalfSize: number;
+    maxPositionSize: number;
+    maxOpenPositions: number;
+    maxGrossExposure: number;
+    maxPerTradeLoss: number;
+    drawdownYellow: number;
+    drawdownOrange: number;
+    drawdownRed: number;
+}
+/** Get trading parameters (from cache or fetch). Returns defaults on failure. */
+export declare function getTradingParams(deps: IntelApiDeps): Promise<TradingParameters>;
+/** Get cached params synchronously (for pure functions like preTradeRiskCheck). */
+export declare function getCachedTradingParams(): TradingParameters;
+/** Force-refresh the cache (call on plugin init). */
+export declare function refreshTradingParams(deps: IntelApiDeps): Promise<void>;

package/trading-params-cache.js

@@ -0,0 +1,52 @@
+// Trading parameters cache — fetches from intelligence API and caches locally.
+// Plugin tools (score-setup, pre-trade-check) read from this cache.
+import { fetchIntelApi } from './tools/intel-api.js';
+// Hardcoded defaults (same as intelligence/src/trading-params/types.ts)
+const DEFAULTS = {
+    regimeConfidenceFloor: 0.35,
+    signalConfluenceThreshold: 0.8,
+    scorecardStrongGoThreshold: 7.5,
+    scorecardGoThreshold: 5.5,
+    scorecardMarginalThreshold: 4.0,
+    confidencePenaltyThreshold: 0.35,
+    unprovenSetupScore: 5,
+    rrWarningThreshold: 1.5,
+    lossStreakQuarterSize: 5,
+    lossStreakHalfSize: 3,
+    maxPositionSize: 10_000,
+    maxOpenPositions: 5,
+    maxGrossExposure: 1.5,
+    maxPerTradeLoss: 500,
+    drawdownYellow: -0.01,
+    drawdownOrange: -0.02,
+    drawdownRed: -0.025,
+};
+let cached = { ...DEFAULTS };
+let cacheExpiry = 0;
+const CACHE_TTL = 60_000; // 60s
+/** Get trading parameters (from cache or fetch). Returns defaults on failure. */
+export async function getTradingParams(deps) {
+    const now = Date.now();
+    if (now < cacheExpiry)
+        return cached;
+    try {
+        const res = await fetchIntelApi('/api/trading-params', deps);
+        if (!('error' in res) && res.params) {
+            cached = { ...DEFAULTS, ...res.params };
+            cacheExpiry = now + CACHE_TTL;
+        }
+    }
+    catch {
+        // Silently use cached/defaults on failure
+    }
+    return cached;
+}
+/** Get cached params synchronously (for pure functions like preTradeRiskCheck). */
+export function getCachedTradingParams() {
+    return cached;
+}
+/** Force-refresh the cache (call on plugin init). */
+export async function refreshTradingParams(deps) {
+    cacheExpiry = 0; // force refresh
+    await getTradingParams(deps);
+}

package/types.d.ts

@@ -0,0 +1,110 @@
+import type { RealizationRule } from './simulator/types.js';
+/** CCXT order — matches skill/src/gateway/event-parser.ts CcxtOrder */
+export interface CcxtOrder {
+    id: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit';
+    status: 'open' | 'closed' | 'canceled';
+    amount: number;
+    filled: number;
+    remaining: number;
+    average: number | null;
+    price: number | null;
+    cost: number;
+    fee: {
+        cost: number;
+        currency: string;
+    };
+    timestamp: number;
+    datetime: string;
+    timeInForce: string;
+    /** Client-supplied order id (Binance: `newClientOrderId`). Present on exchange
+     *  responses; used by bracket reconciliation to identify our orders on restart. */
+    clientOrderId?: string;
+    /** Raw upstream exchange response preserved verbatim. Binance algo endpoint
+     *  carries `orderType` (STOP_MARKET / TAKE_PROFIT_MARKET / TRAILING_STOP_MARKET)
+     *  and `algoType` (CONDITIONAL) fields that are authoritative for role
+     *  classification — more reliable than our CID-shape inference since they
+     *  also cover externally-placed stops (manual operator SL via Binance UI).
+     *  Top-level `type` stays narrow ('market'|'limit') for TS type safety;
+     *  consumers that need order subtype read `info.orderType`. */
+    info?: Record<string, unknown>;
+}
+/** CCXT ticker — matches skill/src/gateway/event-parser.ts CcxtTicker */
+export interface CcxtTicker {
+    symbol: string;
+    last: number;
+    bid: number;
+    ask: number;
+    baseVolume: number;
+    quoteVolume: number;
+    change: number;
+    percentage: number;
+    timestamp: number;
+    datetime: string;
+}
+/** CCXT balance — compatible with skill/src/gateway/event-parser.ts CcxtBalance (stricter: named fields are required here, optional there) */
+export interface CcxtBalance {
+    [currency: string]: {
+        free: number;
+        used: number;
+        total: number;
+    } | unknown;
+    free: Record<string, number>;
+    used: Record<string, number>;
+    total: Record<string, number>;
+}
+/** CCXT position — returned by fetch_positions */
+export interface CcxtPosition {
+    symbol: string;
+    side: 'long' | 'short';
+    contracts: number;
+    contractSize: number;
+    entryPrice: number;
+    markPrice: number;
+    notional: number;
+    unrealizedPnl: number;
+    percentage: number;
+    timestamp: number;
+    datetime: string;
+    setupType?: string;
+    thesis?: string;
+    stopPrice?: number;
+    targetPrice?: number;
+    regime?: string;
+    regimeConfidence?: number;
+    scorecardVerdict?: string;
+    confluenceScore?: number;
+    originalStopPrice?: number;
+    mfePeakPrice?: number;
+    mfeR?: number;
+    giveBackRatio?: number;
+    invalidationPrice?: number;
+    realizationRule?: RealizationRule;
+    /** Derived: has the pinned invalidation price been reached at the current
+     *  mark? When false, the agent's own plan says the trade is still valid (a
+     *  salient anti-re-litigation cue). Undefined when no invalidation was pinned. */
+    invalidationHit?: boolean;
+    bracket?: {
+        slPrice?: number;
+        tpPrice?: number;
+        state: string;
+    };
+}
+/** CCXT OHLCV tuple: [timestamp, open, high, low, close, volume] */
+export type CcxtOHLCV = [number, number, number, number, number, number];
+/** Trading mode for the plugin. */
+export type TradingMode = 'PAPER' | 'SHADOW' | 'MICRO_LIVE' | 'LIVE';
+export interface PluginConfig {
+    startingBalance: number;
+    symbol: string;
+    quoteCurrency: string;
+}
+export declare const DEFAULT_CONFIG: PluginConfig;
+/** Exchange credentials for shadow/live modes. Read from openclaw.json. */
+export interface ExchangeConfig {
+    apiKey: string;
+    secret: string;
+    testnet?: boolean;
+}

package/types.js

@@ -0,0 +1,7 @@
+// Types for the ReefClaw Paper Trading plugin.
+// CCXT-compatible types that match what the GatewayProvider's event-parser expects.
+export const DEFAULT_CONFIG = {
+    startingBalance: 10000,
+    symbol: 'BTC/USDT',
+    quoteCurrency: 'USDT',
+};

package/util/plugin-paths.d.ts

@@ -0,0 +1,3 @@
+/** Resolve the base directory where plugin state lives. The trailing
+ *  `plugins` segment is included so callers can append `<pluginId>`. */
+export declare function resolvePluginsBaseDir(explicitBase?: string): string;

package/util/plugin-paths.js

@@ -0,0 +1,15 @@
+// Centralises the "where do plugin state files live" decision so test setup
+// can redirect every state writer with a single OPENCLAW_HOME env var.
+// Honors precedence: explicit override > OPENCLAW_HOME env > $HOME/.openclaw.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Resolve the base directory where plugin state lives. The trailing
+ *  `plugins` segment is included so callers can append `<pluginId>`. */
+export function resolvePluginsBaseDir(explicitBase) {
+    if (explicitBase)
+        return explicitBase;
+    const envBase = process.env.OPENCLAW_HOME;
+    if (envBase)
+        return join(envBase, 'plugins');
+    return join(homedir(), '.openclaw', 'plugins');
+}