@reefclaw/openclaw-plugin 0.1.0

package/live/bracket-types.d.ts

@@ -0,0 +1,102 @@
+/** Role of a clientOrderId within a bracket. */
+export type BracketRole = 'entry' | 'stop' | 'target';
+/** Short tag stored inside clientOrderId suffix. */
+export type BracketRoleTag = 'e' | 's' | 't';
+/** Immutable opaque identifier tying entry + SL + TP together. */
+export type BracketId = string;
+/** Lifecycle state of a bracket attached to an open position. */
+export type BracketState = 'pending_entry' | 'attaching' | 'active' | 'partial' | 'triggered_sl' | 'triggered_tp' | 'cancelled' | 'failed';
+/** Operator-provided bracket parameters for a new entry. */
+export interface BracketRequest {
+    symbol: string;
+    side: 'buy' | 'sell';
+    stopPrice?: number;
+    targetPrice?: number;
+}
+/** A single ledger entry representing one bracket. Authoritative on disk;
+ *  mirrored to intelligence DB for durability. */
+export interface BracketLedgerEntry {
+    bracketId: BracketId;
+    symbol: string;
+    entrySide: 'buy' | 'sell';
+    entryCid: string;
+    slCid?: string;
+    tpCid?: string;
+    stopPrice?: number;
+    targetPrice?: number;
+    /** Filled entry quantity the bracket legs were sized to (reduceOnly +
+     *  explicit amount, NOT closePosition). modifyStop/modifyTarget MUST reuse
+     *  this — rebuilding a leg with a placeholder size silently under-protects
+     *  the position to that size. Set at attach time. */
+    qty?: number;
+    state: BracketState;
+    attachStartedAt?: string;
+    attachCompletedAt?: string;
+    attachLatencyMs?: number;
+    closedAt?: string;
+    closeReason?: 'triggered_sl' | 'triggered_tp' | 'cancelled_manual' | 'cancelled_auto' | 'attach_failed';
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Event emitted by BracketManager for telemetry + logging. */
+export type BracketEvent = {
+    type: 'bracket.entry_submitted';
+    bracketId: BracketId;
+    symbol: string;
+    ts: string;
+} | {
+    type: 'bracket.entry_filled';
+    bracketId: BracketId;
+    symbol: string;
+    ts: string;
+} | {
+    type: 'bracket.attached';
+    bracketId: BracketId;
+    symbol: string;
+    latencyMs: number;
+    ts: string;
+} | {
+    type: 'bracket.attach_failed';
+    bracketId: BracketId;
+    symbol: string;
+    error: string;
+    retryCount: number;
+    ts: string;
+} | {
+    type: 'bracket.sla_breach';
+    bracketId: BracketId;
+    symbol: string;
+    latencyMs: number;
+    ts: string;
+} | {
+    type: 'bracket.triggered';
+    bracketId: BracketId;
+    symbol: string;
+    side: 'sl' | 'tp';
+    ts: string;
+} | {
+    type: 'bracket.cancelled';
+    bracketId: BracketId;
+    symbol: string;
+    reason: string;
+    ts: string;
+} | {
+    type: 'bracket.orphan_detected';
+    bracketId: BracketId;
+    symbol: string;
+    ts: string;
+} | {
+    type: 'bracket.orphan_cancelled';
+    bracketId: BracketId;
+    symbol: string;
+    ts: string;
+} | {
+    type: 'bracket.modified';
+    bracketId: BracketId;
+    symbol: string;
+    field: 'stop' | 'target';
+    oldValue: number;
+    newValue: number;
+    ts: string;
+};

package/live/bracket-types.js

@@ -0,0 +1,8 @@
+// Bracket order types — shared across BracketManager, BracketLedger,
+// BracketReconciler, and the telemetry pusher.
+//
+// A "bracket" is the pair of exchange-side protective orders attached to a
+// live position: a STOP_MARKET (stop-loss) and a TAKE_PROFIT_MARKET
+// (take-profit), both reduceOnly + closePosition. One entry → one bracketId
+// → three clientOrderIds (entry/stop/target).
+export {};

package/live/deposit-tracker.d.ts

@@ -0,0 +1,62 @@
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+interface TransferFetcher {
+    fetchTransfers(startMs: number, endMs: number): Promise<Array<{
+        tranId: string;
+        time: number;
+        amount: number;
+        asset: string;
+    }>>;
+}
+export interface DepositTrackerOptions {
+    /** Earliest transfer time to consider (ms). Defaults to `Date.now()`. */
+    sessionStartMs?: number;
+    /** Minimum gap between polls (ms). Transfers (deposits/withdrawals/spot↔
+     *  futures moves) are RARE and only affect the cosmetic Day-P&L anchor —
+     *  never a safety path. `fetchTransfers` is 30 Binance weight; at the old
+     *  30s default that was ~60 weight/min PERMANENT on an IP budget already
+     *  pinned at the pacer ceiling 24/7 (2026-05-16 RCA). 5 min cuts it to
+     *  ~6 weight/min; the only cost is a capital flow taking ≤5 min to be
+     *  subtracted from Day P&L. Default: 5 min. */
+    minPollIntervalMs?: number;
+    /** Currencies to sum as quote (1:1 with USD assumed). Anything else is
+     *  logged and ignored. */
+    quoteCurrencies?: readonly string[];
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export declare class DepositTracker {
+    private api;
+    private seenTranIds;
+    /** Last SUCCESSFUL poll — anchors the fetch window so transfers that land
+     *  between a success and a run of failures are still covered by the next
+     *  successful poll. */
+    private lastPollMs;
+    /** Last poll ATTEMPT (success or failure) — drives the throttle. Advancing
+     *  this on failure too is what stops a sustained income-endpoint outage
+     *  from retrying the 30-weight call on every balance cycle (~seconds
+     *  apart) instead of once per minPollIntervalMs. */
+    private lastAttemptMs;
+    private sessionStartMs;
+    private netSinceSessionStart;
+    private readonly minPollIntervalMs;
+    private readonly quoteCurrencies;
+    private readonly now;
+    constructor(api: TransferFetcher | BinancePrivateApi, opts?: DepositTrackerOptions);
+    /** Reset the tracker — used when the agent re-anchors the session NAV for
+     *  any reason (date rollover, operator-triggered reset). */
+    reset(sessionStartMs?: number): void;
+    getSessionStartMs(): number;
+    /** Net quote-currency transfers into (positive) or out of (negative) the
+     *  futures wallet since the tracker was armed. */
+    getNetTransfers(): number;
+    /**
+     * Check the exchange for new transfers. Returns the delta (signed) that
+     * happened since the last poll — callers should add this to their session
+     * NAV anchor so the new wallet level doesn't register as trading P&L.
+     *
+     * The fetch is throttled by `minPollIntervalMs`; rapid calls return 0 without
+     * hitting the API.
+     */
+    refresh(): Promise<number>;
+}
+export {};

package/live/deposit-tracker.js

@@ -0,0 +1,97 @@
+// DepositTracker — detects wallet-transfer deltas (spot↔futures moves,
+// deposits, withdrawals) and feeds them to the enricher so capital flows
+// are subtracted from Day P&L instead of being mistaken for trading gains.
+import { logger } from '../logger.js';
+const TAG = 'deposit-tracker';
+export class DepositTracker {
+    api;
+    seenTranIds = new Set();
+    /** Last SUCCESSFUL poll — anchors the fetch window so transfers that land
+     *  between a success and a run of failures are still covered by the next
+     *  successful poll. */
+    lastPollMs;
+    /** Last poll ATTEMPT (success or failure) — drives the throttle. Advancing
+     *  this on failure too is what stops a sustained income-endpoint outage
+     *  from retrying the 30-weight call on every balance cycle (~seconds
+     *  apart) instead of once per minPollIntervalMs. */
+    lastAttemptMs;
+    sessionStartMs;
+    netSinceSessionStart = 0;
+    minPollIntervalMs;
+    quoteCurrencies;
+    now;
+    constructor(api, opts = {}) {
+        this.api = api;
+        this.now = opts.now ?? (() => Date.now());
+        this.sessionStartMs = opts.sessionStartMs ?? this.now();
+        this.lastPollMs = this.sessionStartMs;
+        this.lastAttemptMs = this.sessionStartMs;
+        this.minPollIntervalMs = opts.minPollIntervalMs ?? 300_000;
+        this.quoteCurrencies = opts.quoteCurrencies ?? ['USDT', 'USDC'];
+    }
+    /** Reset the tracker — used when the agent re-anchors the session NAV for
+     *  any reason (date rollover, operator-triggered reset). */
+    reset(sessionStartMs) {
+        this.seenTranIds.clear();
+        this.sessionStartMs = sessionStartMs ?? this.now();
+        this.lastPollMs = this.sessionStartMs;
+        this.lastAttemptMs = this.sessionStartMs;
+        this.netSinceSessionStart = 0;
+    }
+    getSessionStartMs() {
+        return this.sessionStartMs;
+    }
+    /** Net quote-currency transfers into (positive) or out of (negative) the
+     *  futures wallet since the tracker was armed. */
+    getNetTransfers() {
+        return this.netSinceSessionStart;
+    }
+    /**
+     * Check the exchange for new transfers. Returns the delta (signed) that
+     * happened since the last poll — callers should add this to their session
+     * NAV anchor so the new wallet level doesn't register as trading P&L.
+     *
+     * The fetch is throttled by `minPollIntervalMs`; rapid calls return 0 without
+     * hitting the API.
+     */
+    async refresh() {
+        const now = this.now();
+        // Throttle on the last ATTEMPT (not the last success) — otherwise a
+        // sustained fetch failure bypasses the throttle entirely and every
+        // balance cycle re-fires the 30-weight income call into the outage.
+        if (now - this.lastAttemptMs < this.minPollIntervalMs)
+            return 0;
+        this.lastAttemptMs = now;
+        // A small lookback overlap guards against clock skew between our host and
+        // Binance's edge — duplicate entries get filtered via seenTranIds. The
+        // window anchors on the last SUCCESS so transfers that landed during a
+        // run of failed polls are still picked up.
+        const start = Math.max(this.sessionStartMs, this.lastPollMs - 5_000);
+        let entries;
+        try {
+            entries = await this.api.fetchTransfers(start, now);
+        }
+        catch (err) {
+            logger.warn(TAG, `Transfer poll failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+        this.lastPollMs = now;
+        let delta = 0;
+        for (const e of entries) {
+            if (!e.tranId || this.seenTranIds.has(e.tranId))
+                continue;
+            this.seenTranIds.add(e.tranId);
+            if (this.quoteCurrencies.includes(e.asset)) {
+                delta += e.amount;
+            }
+            else if (e.amount !== 0) {
+                logger.warn(TAG, `Non-quote transfer ignored: ${e.amount} ${e.asset} (tranId=${e.tranId})`);
+            }
+        }
+        if (delta !== 0) {
+            this.netSinceSessionStart += delta;
+            logger.info(TAG, `Capital flow detected: ${delta > 0 ? '+' : ''}${delta.toFixed(4)} (session total: ${this.netSinceSessionStart.toFixed(4)})`);
+        }
+        return delta;
+    }
+}

package/live/emergency-controls.d.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+export interface EmergencyStep {
+    description: string;
+    status: 'pending' | 'done' | 'failed';
+    error?: string;
+}
+export interface EmergencyProgress {
+    action: 'kill' | 'flatten';
+    status: 'in_progress' | 'completed' | 'failed' | 'partial';
+    steps: EmergencyStep[];
+    startedAt: string;
+    completedAt?: string;
+}
+export declare class EmergencyControls extends EventEmitter {
+    private adapter;
+    private isHedgeMode;
+    constructor(adapter: IExchangeAdapter, isHedgeMode?: boolean);
+    /**
+     * Kill switch: cancel all open orders on exchange.
+     * Retries up to 3 times on transient failure.
+     */
+    kill(): Promise<EmergencyProgress>;
+    /**
+     * Flatten: close all positions at market.
+     * Loop-verifies: re-fetches positions after close, retries remainder.
+     * Uses reduceOnly to prevent accidental position reversal.
+     */
+    flatten(): Promise<EmergencyProgress>;
+    private closePositionWithRetry;
+    private emitProgress;
+}

package/live/emergency-controls.js

@@ -0,0 +1,226 @@
+// Emergency controls for live trading — kill switch and flatten with retry logic.
+// These NEVER have a readiness gate — they must work in ALL adapter states.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../logger.js';
+const TAG = 'emergency';
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1_000;
+const MAX_FLATTEN_ATTEMPTS = 3;
+export class EmergencyControls extends EventEmitter {
+    adapter;
+    isHedgeMode;
+    constructor(adapter, isHedgeMode = false) {
+        super();
+        this.adapter = adapter;
+        this.isHedgeMode = isHedgeMode;
+    }
+    /**
+     * Kill switch: cancel all open orders on exchange.
+     * Retries up to 3 times on transient failure.
+     */
+    async kill() {
+        const progress = {
+            action: 'kill',
+            status: 'in_progress',
+            steps: [],
+            startedAt: new Date().toISOString(),
+        };
+        this.emitProgress(progress);
+        logger.warn(TAG, '🔴 KILL SWITCH ACTIVATED');
+        try {
+            // Fetch current open orders
+            const openOrders = await this.adapter.getOpenOrders();
+            if (openOrders.length === 0) {
+                progress.steps.push({ description: 'No open orders to cancel', status: 'done' });
+                progress.status = 'completed';
+                progress.completedAt = new Date().toISOString();
+                this.emitProgress(progress);
+                logger.info(TAG, 'Kill: no open orders');
+                return progress;
+            }
+            progress.steps.push({ description: `Cancelling ${openOrders.length} orders...`, status: 'pending' });
+            this.emitProgress(progress);
+            // Cancel all with retry
+            let success = false;
+            for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    await this.adapter.cancelAllOrders();
+                    success = true;
+                    break;
+                }
+                catch (err) {
+                    logger.warn(TAG, `Kill attempt ${attempt}/${MAX_RETRIES} failed: ${formatError(err)}`);
+                    if (attempt < MAX_RETRIES) {
+                        await sleep(RETRY_DELAY_MS);
+                    }
+                }
+            }
+            if (success) {
+                progress.steps[progress.steps.length - 1].status = 'done';
+                progress.steps[progress.steps.length - 1].description = `${openOrders.length} orders cancelled`;
+                progress.status = 'completed';
+            }
+            else {
+                progress.steps[progress.steps.length - 1].status = 'failed';
+                progress.steps[progress.steps.length - 1].error = 'Failed after 3 retries';
+                progress.steps.push({
+                    description: 'MANUAL INTERVENTION REQUIRED — cancel orders manually on Binance',
+                    status: 'failed',
+                });
+                progress.status = 'failed';
+            }
+            progress.completedAt = new Date().toISOString();
+            this.emitProgress(progress);
+            return progress;
+        }
+        catch (err) {
+            logger.error(TAG, `Kill switch error: ${formatError(err)}`);
+            progress.status = 'failed';
+            progress.steps.push({
+                description: `MANUAL INTERVENTION REQUIRED: ${formatError(err)}`,
+                status: 'failed',
+                error: formatError(err),
+            });
+            progress.completedAt = new Date().toISOString();
+            this.emitProgress(progress);
+            return progress;
+        }
+    }
+    /**
+     * Flatten: close all positions at market.
+     * Loop-verifies: re-fetches positions after close, retries remainder.
+     * Uses reduceOnly to prevent accidental position reversal.
+     */
+    async flatten() {
+        const progress = {
+            action: 'flatten',
+            status: 'in_progress',
+            steps: [],
+            startedAt: new Date().toISOString(),
+        };
+        this.emitProgress(progress);
+        logger.warn(TAG, '🟠 FLATTEN ALL ACTIVATED');
+        try {
+            for (let attempt = 1; attempt <= MAX_FLATTEN_ATTEMPTS; attempt++) {
+                // Fresh snapshot of positions from exchange. getPositionsOrNull()
+                // returns null when the fetch FAILED (429 / weight-paced / transient)
+                // — position state is UNKNOWN, NOT "flat". Treating a failed fetch as
+                // "all closed" would make the single most safety-critical control
+                // report a green "Flatten complete" to the operator mid-crisis while
+                // positions are still live on Binance. Never declare success on null;
+                // skip this attempt's close work and retry (final verification below
+                // delivers an honest partial/MANUAL-INTERVENTION verdict if it
+                // persists). Same null≠empty contract as closePosition/reconciler.
+                const positions = await this.adapter.getPositionsOrNull();
+                if (positions === null) {
+                    logger.warn(TAG, `Flatten attempt ${attempt}/${MAX_FLATTEN_ATTEMPTS}: position fetch failed (exchange data unavailable) — cannot confirm flat, retrying`);
+                    continue;
+                }
+                if (positions.length === 0) {
+                    progress.steps.push({ description: 'All positions closed', status: 'done' });
+                    progress.status = 'completed';
+                    progress.completedAt = new Date().toISOString();
+                    this.emitProgress(progress);
+                    logger.info(TAG, 'Flatten complete — no positions remaining');
+                    return progress;
+                }
+                if (attempt > 1) {
+                    logger.warn(TAG, `Flatten retry ${attempt}/${MAX_FLATTEN_ATTEMPTS}: ${positions.length} positions still open`);
+                }
+                // Close each position
+                for (const position of positions) {
+                    const step = {
+                        description: `Closing ${position.symbol} ${position.side} ${position.contracts}`,
+                        status: 'pending',
+                    };
+                    progress.steps.push(step);
+                    this.emitProgress(progress);
+                    try {
+                        await this.closePositionWithRetry(position);
+                        step.status = 'done';
+                        step.description = `Closed ${position.symbol} ${position.side} ${position.contracts}`;
+                    }
+                    catch (err) {
+                        step.status = 'failed';
+                        step.error = formatError(err);
+                        logger.error(TAG, `Failed to close ${position.symbol}: ${formatError(err)}`);
+                    }
+                    this.emitProgress(progress);
+                }
+            }
+            // Final verification. A null here means we exhausted all attempts
+            // without ever getting a trustworthy snapshot — we CANNOT confirm the
+            // account is flat, so we must NOT report `completed`. Surface it as
+            // partial + MANUAL INTERVENTION (operator must check Binance directly)
+            // rather than the false-green that motivated this fix.
+            const remaining = await this.adapter.getPositionsOrNull();
+            if (remaining === null) {
+                progress.status = 'partial';
+                progress.steps.push({
+                    description: 'MANUAL INTERVENTION REQUIRED — could not verify positions are closed (exchange data unavailable); check Binance directly',
+                    status: 'failed',
+                });
+                logger.error(TAG, 'Flatten verification failed: position fetch unavailable — flat state UNCONFIRMED');
+            }
+            else if (remaining.length > 0) {
+                progress.status = 'partial';
+                progress.steps.push({
+                    description: `MANUAL INTERVENTION REQUIRED — ${remaining.length} positions still open on Binance`,
+                    status: 'failed',
+                });
+                logger.error(TAG, `Flatten incomplete: ${remaining.length} positions remain`);
+            }
+            else {
+                progress.status = 'completed';
+            }
+            progress.completedAt = new Date().toISOString();
+            this.emitProgress(progress);
+            return progress;
+        }
+        catch (err) {
+            logger.error(TAG, `Flatten error: ${formatError(err)}`);
+            progress.status = 'failed';
+            progress.steps.push({
+                description: `MANUAL INTERVENTION REQUIRED: ${formatError(err)}`,
+                status: 'failed',
+                error: formatError(err),
+            });
+            progress.completedAt = new Date().toISOString();
+            this.emitProgress(progress);
+            return progress;
+        }
+    }
+    // ---- Internal ----
+    async closePositionWithRetry(position) {
+        const closeSide = position.side === 'long' ? 'sell' : 'buy';
+        const options = { emergency: true };
+        if (this.isHedgeMode) {
+            options.positionSide = position.side === 'long' ? 'LONG' : 'SHORT';
+        }
+        else {
+            options.reduceOnly = true;
+        }
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                return await this.adapter.createOrder(position.symbol, closeSide, 'market', position.contracts, undefined, undefined, options);
+            }
+            catch (err) {
+                logger.warn(TAG, `Close ${position.symbol} attempt ${attempt}/${MAX_RETRIES}: ${formatError(err)}`);
+                if (attempt < MAX_RETRIES) {
+                    await sleep(RETRY_DELAY_MS);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        // TypeScript: unreachable, but satisfies return type
+        throw new Error(`Failed to close ${position.symbol} after ${MAX_RETRIES} attempts`);
+    }
+    emitProgress(progress) {
+        this.emit('progress', progress);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/live/exchange-errors.d.ts

@@ -0,0 +1,12 @@
+export type ErrorAction = 'report' | 'wait_and_retry' | 'check_and_retry' | 'fix_precision' | 'sync_time';
+export interface ParsedExchangeError {
+    code: number | null;
+    message: string;
+    action: ErrorAction;
+    retryAfterMs: number;
+    isRetryable: boolean;
+    isNetworkError: boolean;
+    humanMessage: string;
+}
+/** Parse a CCXT/Binance error into a structured response. */
+export declare function parseExchangeError(err: unknown): ParsedExchangeError;

package/live/exchange-errors.js

@@ -0,0 +1,130 @@
+// Exchange error handler — maps Binance error codes to human-readable messages
+// and determines appropriate recovery action.
+import { logger } from '../logger.js';
+const TAG = 'exchange-error';
+/** Known Binance Futures error codes and their human-readable meanings. */
+const BINANCE_ERRORS = {
+    // Order errors
+    [-2019]: { message: 'Insufficient margin', action: 'report' },
+    [-1111]: { message: 'Precision error (lot size or tick size mismatch)', action: 'fix_precision' },
+    [-4131]: { message: 'Order below minimum notional value', action: 'report' },
+    [-1015]: { message: 'Too many orders — exchange rate limit hit', action: 'wait_and_retry' },
+    [-2022]: { message: 'Stop price invalid (must be above/below current price depending on side)', action: 'report' },
+    [-1021]: { message: 'Timestamp sync error — clock drift', action: 'sync_time' },
+    [-1003]: { message: 'IP rate limit exceeded', action: 'wait_and_retry' },
+    [-1010]: { message: 'Order not found', action: 'report' },
+    [-2021]: { message: 'Order would immediately trigger', action: 'report' },
+    [-4164]: { message: 'Order price exceeds MAX_PRICE filter', action: 'report' },
+    [-4165]: { message: 'Order price below MIN_PRICE filter', action: 'report' },
+    [-4028]: { message: 'Reduce only rejected — no open position', action: 'report' },
+    [-4005]: { message: 'Order quantity too small', action: 'report' },
+    [-4003]: { message: 'Order quantity exceeds MAX_QTY', action: 'report' },
+    [-4014]: { message: 'Too many open orders', action: 'report' },
+    // System errors
+    [-1000]: { message: 'Unknown exchange error', action: 'report' },
+    [-1001]: { message: 'Exchange internal error — try again later', action: 'wait_and_retry' },
+    [-1002]: { message: 'Unauthorized — API key invalid or insufficient permissions', action: 'report' },
+    [-1006]: { message: 'Unexpected response from exchange', action: 'wait_and_retry' },
+    [-1007]: { message: 'Exchange request timeout', action: 'check_and_retry' },
+    [-1014]: { message: 'Unsupported order combination', action: 'report' },
+    [-1016]: { message: 'Service shutting down', action: 'report' },
+    [-1020]: { message: 'Unsupported operation', action: 'report' },
+};
+/** Parse a CCXT/Binance error into a structured response. */
+export function parseExchangeError(err) {
+    const error = err;
+    // Extract error code (CCXT wraps Binance errors)
+    let code = null;
+    let rawMessage = '';
+    if (typeof error === 'object' && error !== null) {
+        // CCXT errors often have a message like "binance {...}" or structured fields
+        rawMessage = String(error.message ?? error);
+        // Try to extract Binance error code from message
+        const codeMatch = rawMessage.match(/"code"\s*:\s*(-?\d+)/);
+        if (codeMatch) {
+            code = parseInt(codeMatch[1], 10);
+        }
+        // Also check if CCXT provides it directly
+        if (typeof error.code === 'number') {
+            code = error.code;
+        }
+    }
+    else {
+        rawMessage = String(err);
+    }
+    // Check for network errors
+    const isNetworkError = isNetworkRelated(rawMessage);
+    if (isNetworkError) {
+        return {
+            code: null,
+            message: rawMessage,
+            action: 'check_and_retry',
+            retryAfterMs: 1000,
+            isRetryable: true,
+            isNetworkError: true,
+            humanMessage: 'Network error communicating with exchange. Checking if order went through...',
+        };
+    }
+    // Look up known error code
+    if (code !== null && BINANCE_ERRORS[code]) {
+        const known = BINANCE_ERRORS[code];
+        const retryAfterMs = known.action === 'wait_and_retry' ? (code === -1015 || code === -1003 ? 60_000 : 5_000) : 0;
+        return {
+            code,
+            message: rawMessage,
+            action: known.action,
+            retryAfterMs,
+            isRetryable: known.action !== 'report',
+            isNetworkError: false,
+            humanMessage: buildHumanMessage(code, known.message, rawMessage),
+        };
+    }
+    // Unknown error
+    logger.warn(TAG, `Unknown exchange error (code=${code}): ${rawMessage}`);
+    return {
+        code,
+        message: rawMessage,
+        action: 'report',
+        retryAfterMs: 0,
+        isRetryable: false,
+        isNetworkError: false,
+        humanMessage: `Exchange error: ${rawMessage}`,
+    };
+}
+/** Check if an error is network-related (timeout, connection reset, etc.). */
+function isNetworkRelated(message) {
+    const patterns = [
+        'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND',
+        'network', 'timeout', 'socket hang up', 'EPIPE',
+        'EAI_AGAIN', 'EHOSTUNREACH', 'fetch failed',
+    ];
+    const lower = message.toLowerCase();
+    return patterns.some(p => lower.includes(p.toLowerCase()));
+}
+/** Build a human-friendly error message. */
+function buildHumanMessage(code, knownMessage, rawMessage) {
+    switch (code) {
+        case -2019: {
+            // Try to extract balance info from raw message
+            const match = rawMessage.match(/(\d+\.?\d*)\s*USDT/);
+            if (match)
+                return `Insufficient margin: available ${match[1]} USDT`;
+            return 'Insufficient margin — check your balance';
+        }
+        case -4131:
+            return `Order too small: below this symbol's minimum notional value. Check exchange info for the exact minimum.`;
+        case -1111:
+            return `Precision error: amount or price has too many decimal places. Order will be auto-corrected on retry.`;
+        case -1015:
+        case -1003:
+            return `Exchange rate limit hit. Wait 60 seconds before retrying.`;
+        case -2022:
+            return `Invalid stop price. For buy stops: stop must be above current price. For sell stops: stop must be below.`;
+        case -1021:
+            return `Clock out of sync with exchange. Syncing time automatically...`;
+        case -4028:
+            return `Cannot reduce position — no open position found. The position may have already been closed.`;
+        default:
+            return `Exchange error ${code}: ${knownMessage}`;
+    }
+}