@reefclaw/openclaw-plugin 0.1.0

package/ccxt/binance-private.js

@@ -0,0 +1,1415 @@
+// Authenticated CCXT wrapper for Binance Futures.
+// Used for shadow mode (read-only validation) and future live trading.
+// API keys stay local — never transmitted to ReefClaw servers.
+import { createRequire } from 'node:module';
+import { logger, formatError } from '../logger.js';
+import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
+import { parseBracketCid, isBracketCid } from '../live/bracket-id.js';
+const TAG = 'binance-private';
+// Load ccxt via CJS require — same pattern as binance-public.ts
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let ccxtCjs;
+try {
+    const _require = createRequire(import.meta.url);
+    ccxtCjs = _require('ccxt');
+}
+catch {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ccxtCjs = require('ccxt');
+}
+/** Reverse-lookup a raw Binance market id (e.g. "ADAUSDT") to the CCXT
+ *  unified symbol (e.g. "ADA/USDT:USDT") so algo orders come back in the
+ *  same format as regular orders. Callers that already have a unified
+ *  symbol pass it as `explicit` and it is used verbatim.
+ *
+ *  Primary path: CCXT's `safeMarket(id, undefined, undefined, 'swap')` —
+ *  the blessed internal helper. It handles the single-vs-array shape of
+ *  `markets_by_id` and, critically, disambiguates shared spot/futures ids
+ *  (Binance shares `BTCUSDT` between both) via the 'swap' marketType hint
+ *  so we always land on the USDT-M perpetual entry.
+ *
+ *  Fallback path: direct `markets_by_id` lookup with a `linear: true`
+ *  preference. Covers CCXT versions that don't expose safeMarket and tests
+ *  that stub markets_by_id without the helper.
+ *
+ *  On any miss or error: return the raw id. Visible degradation (audit
+ *  reverts to false-negative) is preferable to silently dropping the order. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveUnifiedSymbol(ex, explicit, rawSymbol) {
+    if (explicit)
+        return explicit;
+    const raw = String(rawSymbol ?? '');
+    if (!raw)
+        return '';
+    try {
+        if (typeof ex?.safeMarket === 'function') {
+            // safeMarket(marketId, market?, delimiter?, marketType?) — see CCXT
+            // base/Exchange.ts. For an unknown id it returns a synthetic market
+            // { id: raw, symbol: raw, ... }; detect that by checking whether
+            // symbol differs from the raw id before accepting the result.
+            const market = ex.safeMarket(raw, undefined, undefined, 'swap');
+            if (typeof market?.symbol === 'string' && market.symbol !== raw) {
+                return market.symbol;
+            }
+        }
+        const entry = ex?.markets_by_id?.[raw];
+        if (!entry)
+            return raw;
+        if (Array.isArray(entry)) {
+            const linear = entry.find((m) => m?.linear === true && typeof m?.symbol === 'string');
+            if (linear?.symbol)
+                return linear.symbol;
+            const fallback = entry.find((m) => typeof m?.symbol === 'string');
+            return fallback?.symbol ?? raw;
+        }
+        return typeof entry?.symbol === 'string' ? entry.symbol : raw;
+    }
+    catch {
+        return raw;
+    }
+}
+export class BinancePrivateApi {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    exchange;
+    testnet;
+    constructor(credentials) {
+        this.testnet = credentials.testnet ?? false;
+        const BinanceClass = ccxtCjs.binance ?? ccxtCjs.default?.binance;
+        if (!BinanceClass) {
+            throw new Error('CCXT binance class not found — check ccxt version');
+        }
+        this.exchange = new BinanceClass({
+            apiKey: credentials.apiKey,
+            secret: credentials.secret,
+            enableRateLimit: true,
+            options: {
+                defaultType: 'future',
+                warnOnFetchOpenOrdersWithoutSymbol: false,
+                // CCXT 4.5 deprecated Binance Futures testnet and throws NotSupported
+                // on signed write calls unless this flag is set. testnet.binancefuture.com
+                // still works on the Binance side; the check is CCXT-side only. See
+                // node_modules/ccxt/dist/cjs/src/binance.js line ~12225.
+                disableFuturesSandboxWarning: true,
+                // Auto-sync request timestamps to server time. Without this, even a
+                // 1s clock drift on the client trips Binance's recvWindow check with
+                // "Timestamp for this request was Nms ahead of the server's time."
+                // CCXT pings the server on the first signed call to learn the offset.
+                adjustForTimeDifference: true,
+            },
+        });
+        // Enable demo/testnet if configured
+        if (this.testnet) {
+            this.exchange.setSandboxMode(true);
+        }
+        // ---- WIDENED CANCEL TRACER (2026-05-16) ------------------------------
+        // The narrow chokepoint (fapiPrivateDeleteAlgoOrder + the
+        // cancelOrderByClientId ATTRIBUTION) is deployed and PROVEN working
+        // (it caught the one bracket_integrity flush with a full stack) yet is
+        // SILENT for the recurring ~20s rc-* bracket kills — while a clean
+        // NON-rc closePosition STOP+TP pair, identical in shape to the agent's,
+        // survived 3.6 min untouched on the SAME symbol (controlled prod test
+        // 2026-05-16). => the kill is keyed to the rc-* cid and BYPASSES every
+        // BinancePrivateApi cancel method, i.e. something cancels directly on
+        // the raw ccxt client. Wrap EVERY cancel surface on the raw instance so
+        // no caller (this class, the reconciler, the agent, a ccxt cross-call,
+        // anything holding `exchange`) can bypass it; log method + args + full
+        // caller stack. Pure observability — each wrapper calls straight through
+        // (same `this`, same return Promise), zero behaviour change. Remove
+        // once the proven source is fixed and soaked.
+        {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            const cancelSurfaces = [
+                'cancelOrder', 'cancelOrders', 'cancelAllOrders', 'cancelOrdersForSymbols',
+                'fapiPrivateDeleteOrder', 'fapiPrivateDeleteAllOpenOrders',
+                'fapiPrivateDeleteAlgoOrder', 'fapiPrivateDeleteBatchOrders',
+                'fapiPrivateDeleteAlgoFuturesOrder',
+            ];
+            let armed = 0;
+            for (const m of cancelSurfaces) {
+                const orig = ex[m];
+                if (typeof orig !== 'function')
+                    continue;
+                ex[m] = (...args) => {
+                    let argStr;
+                    try {
+                        argStr = JSON.stringify(args).slice(0, 600);
+                    }
+                    catch {
+                        argStr = '(unserializable)';
+                    }
+                    const stack = new Error('wide-cancel-trace').stack ?? '(no stack)';
+                    logger.warn(TAG, `WIDE-CANCEL-TRACE — raw ccxt ${m}(${argStr}) invoked. If this ` +
+                        `carries an rc-*-{s,t} cid/algoId, THIS is the bracket ` +
+                        `stripper (the narrow chokepoint never sees it). Caller ` +
+                        `stack follows:\n${stack}`);
+                    return orig.apply(ex, args);
+                };
+                armed++;
+            }
+            logger.info(TAG, `WIDE-CANCEL-TRACE armed on ${armed} raw cancel surface(s)`);
+        }
+        logger.info(TAG, `Binance private API initialized (${this.testnet ? 'testnet' : 'mainnet'})`);
+    }
+    /**
+     * Validate API key permissions by making test API calls.
+     * Best-effort — never throws.
+     */
+    async validatePermissions() {
+        const result = {
+            canReadBalance: false,
+            canReadPositions: false,
+            canTrade: false,
+            errors: [],
+        };
+        // Test: read balance. Route through the gate like every other read —
+        // a permission probe during an active ban would otherwise extend it,
+        // and a 429/418 here must arm the gate for the pollers.
+        try {
+            assertNotBanned('fetchBalance');
+            await this.exchange.fetchBalance();
+            noteSuccess();
+            result.canReadBalance = true;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            result.errors.push(`Balance read failed: ${formatError(err)}`);
+        }
+        // Test: read positions (same gate routing as the balance probe above).
+        try {
+            assertNotBanned('fetchPositions');
+            await this.exchange.fetchPositions();
+            noteSuccess();
+            result.canReadPositions = true;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            result.errors.push(`Position read failed: ${formatError(err)}`);
+        }
+        // Note: We DON'T test trade permission here (would require placing a real order).
+        // Trade permission is validated implicitly when micro-live/live mode attempts the first order.
+        // For now, if balance + positions work, the key is likely valid.
+        result.canTrade = result.canReadBalance; // Optimistic — actual test in live mode
+        return result;
+    }
+    /** Fetch real account balance. Returns null on error. */
+    async fetchBalance() {
+        try {
+            assertNotBanned('fetchBalance');
+            const raw = await this.exchange.fetchBalance();
+            noteSuccess();
+            const free = {};
+            const used = {};
+            const total = {};
+            const result = { free, used, total };
+            for (const currency of Object.keys(raw.total ?? {})) {
+                // Keep any NON-ZERO balance — negative included. Binance multi-asset
+                // margin (BNFCR, live on prod) legitimately reports negative wallet
+                // lines (cumulative realized losses); the old `> 0` filter silently
+                // dropped them, overstating NAV for any consumer of the filtered
+                // total/free maps. `!== 0` preserves the original skip-empty intent
+                // without the sign bias.
+                if ((raw.total[currency] ?? 0) !== 0 || (raw.free[currency] ?? 0) !== 0) {
+                    free[currency] = raw.free[currency] ?? 0;
+                    used[currency] = raw.used[currency] ?? 0;
+                    total[currency] = raw.total[currency] ?? 0;
+                    result[currency] = {
+                        free: free[currency],
+                        used: used[currency],
+                        total: total[currency],
+                    };
+                }
+            }
+            // Preserve CCXT's raw `info` field so downstream callers can read
+            // Binance-specific fields like info.assets[i].walletBalance for
+            // margin-aware balance normalisation (see
+            // UserDataStreamController.normalizeBinanceFuturesBalance). Without
+            // this, CCXT's fetchBalance.total returns marginBalance (wallet +
+            // uPnl) and WS store holds walletBalance only, causing persistent
+            // drift on any margin asset with open-position uPnl.
+            result.info = raw.info;
+            return result;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchBalance failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Fetch account-transfer income entries (deposits/withdrawals into/out of the
+     * Futures wallet) between two timestamps. These surface as `incomeType=TRANSFER`
+     * on Binance's `/fapi/v1/income` endpoint; positive `income` = inflow to
+     * futures, negative = outflow. Used by DepositTracker to re-anchor
+     * sessionStartNav so capital flows never show up as Day P&L.
+     */
+    async fetchTransfers(startMs, endMs) {
+        try {
+            const params = {
+                incomeType: 'TRANSFER',
+                startTime: Math.max(0, Math.floor(startMs)),
+                endTime: Math.floor(endMs),
+                limit: 1000,
+            };
+            assertNotBanned('fetchTransfers');
+            const raw = await this.exchange.fapiPrivateGetIncome(params);
+            noteSuccess();
+            if (!Array.isArray(raw))
+                return [];
+            return raw.map((r) => ({
+                // tranId is Binance's idempotency key for the transfer; fall back to a
+                // time+amount composite if the exchange omits it (shouldn't happen).
+                tranId: String(r.tranId ?? `${r.time}-${r.income}-${r.asset}`),
+                time: Number(r.time ?? 0),
+                amount: Number(r.income ?? 0),
+                asset: String(r.asset ?? ''),
+            }));
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTransfers failed: ${formatError(err)}`);
+            throw err;
+        }
+    }
+    /**
+     * Sum trading-effect income (every incomeType EXCEPT TRANSFER) since
+     * `sinceMs` — i.e. net wallet change from trading. This matches Binance
+     * mobile app's "Today's Realized PNL" line (verified 2026-05-14).
+     *
+     * An earlier comment here claimed Binance's UI uses GROSS REALIZED_PNL
+     * only and that the gross/net values "no longer match" — that was based
+     * on a faulty assumption that propagated into the live-adapter and
+     * caused dashboard Realized to show $2.28 less negative than Binance's
+     * own UI. Reverted: gross is for debug only, net is what the user sees.
+     *
+     * Single REST call, weight=30. Returns `null` (NOT 0) on a failed/paced
+     * fetch — null≠empty: a non-answer must never collapse to a zero the
+     * caller would treat as real (2026-05-16 KPI incident). Unused in prod
+     * (kept for parity / ad-hoc reconciliation).
+     *
+     * Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/account/rest-api/Get-Income-History
+     */
+    async fetchRealizedPnlSince(sinceMs) {
+        const b = await this.fetchTodayIncomeBreakdown(sinceMs);
+        return b ? b.netNonTransfer : null;
+    }
+    /**
+     * One income-history call, two numbers:
+     *   - `realizedPnlGross`: sum of `incomeType === 'REALIZED_PNL'` only.
+     *     KEPT FOR DEBUG / RECONCILIATION ONLY — despite an earlier comment
+     *     claiming this matches Binance's "Today's Realized PNL" UI line,
+     *     the mobile app verification on 2026-05-14 showed Binance reports
+     *     the NET figure (-$5.98 in the test) while gross was -$3.70. Do
+     *     NOT surface this number in the dashboard Realized KPI.
+     *   - `netNonTransfer`: sum of EVERY non-TRANSFER incomeType (REALIZED_PNL +
+     *     COMMISSION + FUNDING_FEE + rebates). This equals today's net wallet
+     *     change from trading and matches the Binance mobile app's
+     *     "Today's Realized PNL" line. Used for BOTH the Realized KPI display
+     *     AND the `sessionStartNav` anchor so Day P&L reflects total NAV
+     *     change since UTC midnight.
+     *
+     * Both numbers refresh together. Caller throttles. Single page (limit=1000)
+     * — > 1000 income rows in a UTC day is unrealistic for a single account.
+     *
+     * Return contract (null≠empty — same rule as getOpenOrders /
+     * closePosition / the bracket reconciler):
+     *   - `{realizedPnlGross, netNonTransfer}` on a successful parse, INCLUDING
+     *     a genuine empty income history (`{0,0}` = Binance confirms no income
+     *     today — a real zero the caller can anchor on: wallet − 0).
+     *   - `null` on a failed/paced/garbled fetch (rate-limit, 418, network,
+     *     non-array body). It is "today's income UNKNOWN", NOT "zero". The
+     *     caller MUST keep its last good anchor. Coercing this to `{0,0}`
+     *     pinned `sessionStartNav` to `wallet_now` and zeroed Day P&L — the
+     *     2026-05-16 KPI incident this contract exists to prevent.
+     *
+     * `opts.forced` selects the never-paced ban-gate context — pass it ONLY
+     * for the boot + UTC-day-rollover anchor (the values that actually change
+     * within a UTC day). Routine same-day refreshes leave it false so they
+     * stay cosmetic/sheddable; a shed there is now a harmless no-op because
+     * the caller keeps the (invariant) last good anchor.
+     *
+     * Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/account/rest-api/Get-Income-History
+     */
+    async fetchTodayIncomeBreakdown(sinceMs, opts) {
+        const context = opts?.forced
+            ? 'fetchTodayIncomeBreakdownForced'
+            : 'fetchTodayIncomeBreakdown';
+        try {
+            const params = {
+                startTime: Math.max(0, Math.floor(sinceMs)),
+                endTime: Date.now(),
+                limit: 1000,
+            };
+            assertNotBanned(context);
+            const raw = await this.exchange.fapiPrivateGetIncome(params);
+            noteSuccess();
+            // null≠empty: a non-array is a garbled/non-answer (NOT "no income
+            // today"), so it must NOT be coerced into a zero anchor.
+            if (!Array.isArray(raw))
+                return null;
+            let realizedPnlGross = 0;
+            let netNonTransfer = 0;
+            for (const r of raw) {
+                const row = r;
+                const type = String(row.incomeType ?? '');
+                if (type === 'TRANSFER')
+                    continue;
+                const amt = Number(row.income ?? 0);
+                if (!Number.isFinite(amt))
+                    continue;
+                netNonTransfer += amt;
+                if (type === 'REALIZED_PNL')
+                    realizedPnlGross += amt;
+            }
+            // A genuine empty income history IS a confirmed zero — {0,0} here is
+            // correct (the caller anchors sessionStartNav = wallet − 0).
+            return { realizedPnlGross, netNonTransfer };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            // null, NEVER {0,0}: a failed/paced fetch is "today's income UNKNOWN",
+            // not "zero". {0,0} pins sessionStartNav to wallet_now and zeroes
+            // Day P&L (2026-05-16 KPI incident). The caller keeps its last good
+            // anchor, which is invariant within a UTC day. Don't WARN-spam the
+            // EXPECTED paced/banned case — the ban gate already logs that once
+            // per window; only a genuine failure is notable here.
+            if (!(err instanceof BinanceBannedError)) {
+                logger.warn(TAG, `fetchTodayIncomeBreakdown failed: ${formatError(err)}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Discover symbols that had any trade-tagged income activity since `sinceMs`.
+     *
+     * /fapi/v1/income (no incomeType filter) returns up to 1000 entries spanning
+     * REALIZED_PNL, COMMISSION, FUNDING_FEE, etc. — every entry that originates
+     * from a trade carries a non-empty `symbol`. We collect the unique symbols
+     * and translate each raw Binance id ('BTCUSDT') into the CCXT-unified form
+     * ('BTC/USDT:USDT') via the same `resolveUnifiedSymbol` helper used elsewhere
+     * in this file, so callers can store / compare them under one canonical key.
+     *
+     * Used by RestGapFiller at startup to recover symbols traded during plugin
+     * downtime that aren't in the persisted touched-symbols cache (Codex
+     * finding 4 follow-up). Single REST call, weight=30 — well below the 2400/min
+     * budget. Single page; > 1000 income rows in the window is rare and would
+     * indicate a multi-hour outage that needs an operator-driven backfill anyway.
+     *
+     * Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/account/rest-api/Get-Income-History
+     */
+    async fetchRecentTradedSymbols(sinceMs) {
+        try {
+            const params = {
+                startTime: Math.max(0, Math.floor(sinceMs)),
+                endTime: Date.now(),
+                limit: 1000,
+            };
+            assertNotBanned('fetchRecentTradedSymbols');
+            const raw = await this.exchange.fapiPrivateGetIncome(params);
+            noteSuccess();
+            if (!Array.isArray(raw))
+                return [];
+            const out = new Set();
+            for (const r of raw) {
+                const sym = r?.symbol;
+                if (typeof sym !== 'string' || sym.length === 0)
+                    continue;
+                const unified = resolveUnifiedSymbol(this.exchange, undefined, sym);
+                if (unified)
+                    out.add(unified);
+            }
+            return [...out];
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchRecentTradedSymbols failed: ${formatError(err)}`);
+            throw err;
+        }
+    }
+    /** Fetch real open positions. Returns null on error. */
+    async fetchPositions(symbol) {
+        try {
+            assertNotBanned('fetchPositions');
+            const symbols = symbol ? [symbol] : undefined;
+            const raw = await this.exchange.fetchPositions(symbols);
+            noteSuccess();
+            // Filter to positions with actual quantity
+            return raw
+                .filter((p) => {
+                const contracts = Number(p.contracts ?? 0);
+                return contracts > 0;
+            })
+                .map((p) => ({
+                symbol: String(p.symbol ?? ''),
+                side: String(p.side ?? 'long'),
+                contracts: Number(p.contracts ?? 0),
+                contractSize: Number(p.contractSize ?? 1),
+                entryPrice: Number(p.entryPrice ?? 0),
+                markPrice: Number(p.markPrice ?? 0),
+                notional: Number(p.notional ?? 0),
+                unrealizedPnl: Number(p.unrealizedPnl ?? 0),
+                percentage: Number(p.percentage ?? 0),
+                timestamp: Date.now(),
+                datetime: new Date().toISOString(),
+            }));
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchPositions failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Fetch real open orders — REGULAR + ALGO (conditional) orders merged.
+     *
+     *  Binance Futures splits orders into two namespaces:
+     *   - Regular orders (`/fapi/v1/openOrders`) — limit, market, etc.
+     *   - Algo orders (`/fapi/v1/openAlgoOrders`) — STOP_MARKET,
+     *     TAKE_PROFIT_MARKET, TRAILING_STOP_MARKET. CCXT submits these via
+     *     `createOrder` but the unified `fetchOpenOrders` does NOT include them.
+     *  The bracket-orders feature lives entirely in the algo bucket, so we
+     *  fetch both and merge the results so downstream consumers (reconciler,
+     *  dashboard) see a single list. Algo orders are normalised into the same
+     *  CcxtOrder shape with `clientAlgoId` → `clientOrderId`. */
+    async fetchOpenOrders(symbol) {
+        try {
+            // This wrapper makes TWO Binance REST calls (regular /fapi/v1/openOrders
+            // + algo /fapi/v1/openAlgoOrders, both 1 scoped / 40 unscoped per
+            // developers.binance.com). Account the COMBINED cost up-front via a
+            // distinct context (CONTEXT_WEIGHT: fetchOpenOrders=2, …All=80) so the
+            // process-wide pacer doesn't undercount the single most expensive hot
+            // call ~16×. Gate once here (not in the algo sub-call) so a mid-wrapper
+            // pace can't return a regular-only partial that reads as "no brackets".
+            assertNotBanned(symbol ? 'fetchOpenOrders' : 'fetchOpenOrdersAll');
+            const raw = await this.exchange.fetchOpenOrders(symbol);
+            noteSuccess();
+            const regular = raw.map((o) => ({
+                id: String(o.id ?? ''),
+                symbol: String(o.symbol ?? ''),
+                side: String(o.side ?? 'buy'),
+                type: String(o.type ?? 'limit'),
+                status: String(o.status ?? 'open'),
+                amount: Number(o.amount ?? 0),
+                filled: Number(o.filled ?? 0),
+                remaining: Number(o.remaining ?? 0),
+                average: o.average != null ? Number(o.average) : null,
+                price: o.price != null ? Number(o.price) : null,
+                cost: Number(o.cost ?? 0),
+                fee: { cost: 0, currency: 'USDT' },
+                timestamp: Number(o.timestamp ?? Date.now()),
+                datetime: String(o.datetime ?? new Date().toISOString()),
+                timeInForce: String(o.timeInForce ?? 'GTC'),
+                clientOrderId: o.clientOrderId != null ? String(o.clientOrderId) : undefined,
+                // Preserve raw CCXT order shape (which preserves Binance's raw
+                // payload inside its own `info`). Downstream classifiers read
+                // `info.info?.orderType` / similar when they need authoritative
+                // order subtype beyond the narrow 'market'|'limit' typing above.
+                info: o.info != null && typeof o.info === 'object' ? o.info : undefined,
+            }));
+            // Merge algo/conditional orders (STOP_MARKET/TAKE_PROFIT_MARKET — our
+            // protective brackets) from the separate /fapi/v1/openAlgoOrders
+            // endpoint. fetchOpenAlgoOrders returns [] ONLY when the endpoint
+            // method is structurally absent (non-algo/paper key — a stable
+            // capability gap, safe to merge as empty); a real 429/network failure
+            // THROWS and is caught below → this whole call returns `null`
+            // ("exchange order state unknown — do not treat as zero brackets").
+            // A partial "regular-only" list that looks successful would make live
+            // SL/TP vanish from audit/reconciler → phantom-naked re-attach spiral.
+            const algo = await this.fetchOpenAlgoOrders(symbol);
+            return [...regular, ...algo];
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOpenOrders failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Fetch open algo (conditional) orders. Used by fetchOpenOrders to merge
+     *  STOP_MARKET / TAKE_PROFIT_MARKET orders into the unified list. Best-effort:
+     *  returns [] on endpoint error so the caller degrades gracefully. */
+    async fetchOpenAlgoOrders(symbol) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            if (typeof ex.fapiPrivateGetOpenAlgoOrders !== 'function') {
+                return [];
+            }
+            // Binance API expects the bare symbol ("BTCUSDT"), CCXT passes "BTC/USDT"
+            // in the unified layer. Use marketId() to translate when a symbol is given.
+            const params = {};
+            if (symbol) {
+                try {
+                    params.symbol = ex.marketId(symbol);
+                }
+                catch {
+                    params.symbol = symbol.replace('/', '').split(':')[0];
+                }
+            }
+            const raw = await ex.fapiPrivateGetOpenAlgoOrders(params);
+            // A successful call to "open algo orders" returns an array (possibly
+            // empty). A non-array is an unexpected/garbled response — treat it as
+            // a FAILURE, not "zero algo orders". Returning [] here would make
+            // live SL/TP brackets silently vanish from the merged result while
+            // fetchOpenOrders still looks successful (non-null) — the exact
+            // partial-success-as-success trap the null contract forbids.
+            if (!Array.isArray(raw)) {
+                throw new Error('fetchOpenAlgoOrders: unexpected non-array response');
+            }
+            return raw.map((o) => {
+                // Translate algo side → CCXT side (Binance returns "SELL"/"BUY" uppercase)
+                const side = String(o.side ?? 'sell').toLowerCase();
+                const stopPrice = o.triggerPrice != null ? Number(o.triggerPrice) : null;
+                const createTime = o.createTime != null ? Number(o.createTime) : Date.now();
+                // Binance's algo endpoint returns raw market IDs (e.g. "ADAUSDT"). The
+                // regular (non-algo) fetchOpenOrders branch returns CCXT unified form
+                // (e.g. "ADA/USDT:USDT"). Portfolio-wide consumers that key orders by
+                // symbol (audit_bracket_protection, reconciler) see both in one list —
+                // if formats disagree, position↔order grouping silently loses matches.
+                // Before 2026-04-22 the no-explicit-symbol path fell back to `o.symbol`
+                // verbatim, producing 291 audit false-negatives in 24h on prod and the
+                // bracket_integrity death loop. Resolve the raw ID through CCXT's
+                // markets_by_id cache (populated by loadMarkets on startup).
+                const resolvedSymbol = resolveUnifiedSymbol(ex, symbol, o.symbol);
+                // CcxtOrder.type is narrow ('market'|'limit'); we preserve the original
+                // STOP_MARKET / TAKE_PROFIT_MARKET in `info` for consumers that care.
+                return {
+                    id: String(o.algoId ?? ''),
+                    symbol: resolvedSymbol,
+                    side,
+                    type: 'market',
+                    status: String(o.algoStatus ?? 'open').toLowerCase() === 'new' ? 'open' : 'open',
+                    amount: Number(o.quantity ?? 0),
+                    filled: 0,
+                    remaining: Number(o.quantity ?? 0),
+                    average: null,
+                    price: stopPrice,
+                    cost: 0,
+                    fee: { cost: 0, currency: 'USDT' },
+                    timestamp: createTime,
+                    datetime: new Date(createTime).toISOString(),
+                    timeInForce: String(o.timeInForce ?? 'GTC'),
+                    clientOrderId: o.clientAlgoId != null ? String(o.clientAlgoId) : undefined,
+                    // Preserve the raw Binance algo response verbatim. Key fields
+                    // consumers read:
+                    //   - `orderType`: 'STOP_MARKET' | 'TAKE_PROFIT_MARKET' | 'TRAILING_STOP_MARKET'
+                    //   - `algoType`:  'CONDITIONAL' (vs 'VP' / 'TWAP' on the algo/futures endpoint)
+                    //   - `triggerPrice`, `slTriggerPrice`, `tpTriggerPrice`: authoritative stop/tp levels
+                    // Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api/Current-All-Algo-Open-Orders
+                    info: o,
+                };
+            });
+        }
+        catch (err) {
+            // CRITICAL: do NOT degrade a real fetch failure to []. ReefClaw's
+            // protective brackets ARE algo orders (STOP_MARKET/TAKE_PROFIT_MARKET
+            // on /fapi/v1/openAlgoOrders). A transient 429/network failure here,
+            // swallowed as [], merges into fetchOpenOrders as a SUCCESSFUL-looking
+            // (non-null) list with every SL/TP missing → audit/reconciler read
+            // "unprotected" → phantom-naked re-attach / bracket clobber. That is
+            // exactly the null-collapse class the getOpenOrders→null contract
+            // exists to prevent. Propagate: fetchOpenOrders' outer catch converts
+            // this to `null` ("exchange state unknown — skip this cycle"), which
+            // every consumer already handles safely. noteBinanceError is left to
+            // that single outer catch so the ban gate isn't armed twice.
+            logger.warn(TAG, `fetchOpenAlgoOrders failed (propagating as unknown, NOT empty): ${formatError(err)}`);
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    /** Query the live status of a SINGLE algo (conditional) order by its
+     *  clientAlgoId via GET /fapi/v1/algoOrder (weight 1, doc-verified
+     *  developers.binance.com/.../Query-Algo-Order, 2026-05-15).
+     *
+     *  This is the authoritative per-order disambiguator for the bracket-spiral
+     *  class. A broad /fapi/v1/openAlgoOrders empty result is NOT proof a
+     *  specific bracket leg is gone — Binance returns a *successful* [] under
+     *  weight pressure / eventual-consistency. This call asks Binance a DIRECT
+     *  question about one exact order id and returns its `algoStatus`.
+     *
+     *  Returns the UPPERCASE algoStatus on success — one of (doc-verified enum):
+     *  NEW | WORKING | TRIGGERED | CANCELED | FINISHED | EXPIRED | REJECTED.
+     *  Returns `null` on ANY non-answer: CCXT implicit method absent
+     *  (non-algo/paper key — stable capability gap), ban / weight-paced,
+     *  429 / network, order-not-found (-2013 or aged-out per Binance's
+     *  3-day / 90-day retention rule), or a garbled / unparseable response.
+     *
+     *  `null` is the explicit "could not get an answer" — the SAME null≠empty
+     *  contract as the rest of the bracket path. Callers MUST map `null` to
+     *  'unknown' and never to a destructive decision. Best-effort by design:
+     *  never throws into the caller (a thrown ban/pace is swallowed to `null`
+     *  because "I was rate-limited" is just another flavour of "no answer").
+     *  Ships dark in Phase 1 — no call sites yet. */
+    async queryAlgoOrderStatus(clientAlgoId) {
+        if (!clientAlgoId)
+            return null;
+        try {
+            // Read path → pre-gate (weight 1, paced like other reads; the gate
+            // throws BinanceBanned/WeightPaced which the catch below absorbs to
+            // `null` = safe "unknown", never a verdict).
+            assertNotBanned('queryAlgoOrder');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            if (typeof ex.fapiPrivateGetAlgoOrder !== 'function') {
+                return null;
+            }
+            // CCXT signs fapiPrivate* implicit calls and injects timestamp/recvWindow.
+            // Binance requires algoId OR clientAlgoId; we always have the cid.
+            const raw = await ex.fapiPrivateGetAlgoOrder({ clientAlgoId });
+            noteSuccess();
+            // Doc response is a single object { algoId, clientAlgoId, algoStatus,
+            // ... }. Defensive: some CCXT/proxy layers wrap singletons in an array.
+            let row;
+            if (Array.isArray(raw)) {
+                const arr = raw;
+                row = arr.find(o => String(o.clientAlgoId ?? '') === clientAlgoId)
+                    ?? (arr.length === 1 ? arr[0] : undefined);
+            }
+            else if (raw && typeof raw === 'object') {
+                row = raw;
+            }
+            if (!row)
+                return null;
+            const status = row.algoStatus;
+            if (status == null || String(status).trim() === '')
+                return null;
+            return String(status).toUpperCase();
+        }
+        catch (err) {
+            // Not-found / aged-out / 429 / network / ban / pace all collapse here.
+            // noteBinanceError is a no-op for BinanceBannedError (gate already
+            // open) and arms the gate for real Binance errors — same pattern as
+            // every other read. Best-effort: return null, never a verdict.
+            noteBinanceError(err);
+            logger.warn(TAG, `queryAlgoOrderStatus(${clientAlgoId}) → null/unknown (NOT a verdict): ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Fetch historical fills (trades) for a symbol via GET /fapi/v1/userTrades.
+     *  Used by the REST gap-filler (rest-gap-filler.ts) to backfill any fills
+     *  that landed during a WS blind window — when the user-data stream was
+     *  between reconnects, ORDER_TRADE_UPDATE events for that interval are
+     *  unreachable from the WS side. Binance requires a symbol per call; the
+     *  gap-filler iterates over every symbol it's seen this session.
+     *
+     *  Returns raw CCXT trade objects (permissive shape — caller extracts the
+     *  fields it needs). `since` is epoch milliseconds. Binance caps `limit` at
+     *  1000 per request. Falls back to [] on error so the caller keeps going
+     *  rather than aborting the whole reconnect flow.
+     *
+     *  `opts.endTime` (epoch ms) bounds the upper end of the window. CCXT 4.5.x
+     *  reads it from params (`safeInteger2(params, 'until', 'endTime')`) and maps
+     *  it onto the `/fapi/v1/userTrades` `endTime` query param; the gap-filler's
+     *  startup deep-fill passes it to chunk a multi-day lookback into the ≤7-day
+     *  windows Binance requires (the span between startTime and endTime cannot
+     *  exceed 7 days). Without it, CCXT auto-clamps a `since` older than 7 days to
+     *  `since + 7d` for linear futures, so only the first week would ever return.
+     *
+     *  Spec: https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api/Account-Trade-List */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchMyTrades(symbol, since, limit = 500, opts) {
+        // Legacy error-tolerant surface: [] on any failure so best-effort callers
+        // (reconnect gap-fill, active probe) keep going. Callers that must
+        // distinguish "read failed" from "genuinely no trades" use
+        // fetchMyTradesOrNull below — the [] here is NOT safe for cursor/window
+        // bookkeeping (an error-as-empty reads as "window exhausted").
+        return (await this.fetchMyTradesOrNull(symbol, since, limit, opts)) ?? [];
+    }
+    /** Null-returning variant of fetchMyTrades — the null≠empty contract
+     *  (same rule as getPositionsOrNull / fetchOpenOrders):
+     *    - array (possibly empty) ONLY on a successful response — a real `[]`
+     *      means Binance CONFIRMS no trades in the queried range;
+     *    - `null` on ANY non-answer (ban/pace, 429, network, garbled non-array
+     *      body). Callers must treat null as "trades UNKNOWN" and must NOT
+     *      advance a pagination cursor or mark a backfill window complete.
+     *
+     *  `opts.fromId` pages by Binance trade id (ascending, inclusive) instead
+     *  of by time. Doc-verified (Account-Trade-List, 2026-07-02): "The
+     *  parameter fromId cannot be sent with startTime or endTime", so a fromId
+     *  call must omit `since`/`endTime` — enforced here rather than silently
+     *  sending a request Binance rejects. Weight is 5 in all variants (same
+     *  endpoint), so the existing ban-gate context accounting is unchanged. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchMyTradesOrNull(symbol, since, limit = 500, opts) {
+        if (opts?.fromId != null && (since != null || opts?.endTime != null)) {
+            throw new Error('fetchMyTradesOrNull: fromId cannot be combined with since/endTime (Binance rejects the combination)');
+        }
+        try {
+            assertNotBanned('fetchMyTrades');
+            const params = {};
+            if (opts?.endTime != null)
+                params.endTime = opts.endTime;
+            if (opts?.fromId != null)
+                params.fromId = opts.fromId;
+            const raw = await this.exchange.fetchMyTrades(symbol, since, limit, params);
+            noteSuccess();
+            // null≠empty: a non-array body is a garbled non-answer, NOT "no trades".
+            return Array.isArray(raw) ? raw : null;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.warn(TAG, `fetchMyTrades(${symbol}, since=${since}) failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Fetch order book depth (same data as public, validates auth path). */
+    async fetchOrderBook(symbol, limit = 20) {
+        try {
+            assertNotBanned('fetchOrderBook');
+            const raw = await this.exchange.fetchOrderBook(symbol, limit);
+            noteSuccess();
+            return {
+                bids: (raw.bids ?? []).map((l) => [l[0], l[1]]),
+                asks: (raw.asks ?? []).map((l) => [l[0], l[1]]),
+                timestamp: raw.timestamp ?? Date.now(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOrderBook(${symbol}) failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Fetch ticker. Returns null on error. */
+    async fetchTicker(symbol) {
+        try {
+            assertNotBanned('fetchTicker');
+            const raw = await this.exchange.fetchTicker(symbol);
+            noteSuccess();
+            return {
+                symbol: raw.symbol,
+                last: raw.last ?? 0,
+                bid: raw.bid ?? 0,
+                ask: raw.ask ?? 0,
+                baseVolume: raw.baseVolume ?? 0,
+                quoteVolume: raw.quoteVolume ?? 0,
+                change: raw.change ?? 0,
+                percentage: raw.percentage ?? 0,
+                timestamp: raw.timestamp ?? Date.now(),
+                datetime: raw.datetime ?? new Date().toISOString(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTicker(${symbol}) failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Submit a real order to the exchange.
+     * Used in micro-live and live modes only. NOT called in shadow mode.
+     *
+     * @param params — extra CCXT params forwarded to Binance (e.g. newClientOrderId, reduceOnly, positionSide).
+     */
+    async createOrder(symbol, side, type, amount, price, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params) {
+        // Order submission is intentionally NOT assertNotBanned-gated (orders
+        // must always reach the exchange — kill/flatten/bracket-arming can never
+        // be blocked). But it MUST still ARM the shared gate on a 429/418 so the
+        // *read* pollers back off — otherwise an order that trips the IP limit
+        // leaves every poller hammering into the ban (CLAUDE.md ban-gate
+        // contract). Catch → noteBinanceError → rethrow (preserve the throw).
+        let raw;
+        try {
+            raw = await this.exchange.createOrder(symbol, type, side, amount, price, params ?? {});
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
+        return {
+            id: String(raw.id),
+            symbol: raw.symbol,
+            side: raw.side,
+            type: raw.type,
+            status: raw.status,
+            amount: raw.amount ?? amount,
+            filled: raw.filled ?? 0,
+            remaining: raw.remaining ?? amount,
+            average: raw.average ?? null,
+            price: raw.price ?? price ?? null,
+            cost: raw.cost ?? 0,
+            fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+            timestamp: raw.timestamp ?? Date.now(),
+            datetime: raw.datetime ?? new Date().toISOString(),
+            timeInForce: raw.timeInForce ?? 'GTC',
+        };
+    }
+    /** Fetch a single order by ID. Used for fill polling and idempotency checks. */
+    async fetchOrder(orderId, symbol) {
+        try {
+            // Pre-gate: OrderPoller calls this every 5s. During an active 418
+            // an ungated poll keeps hitting Binance and EXTENDS the ban. Throwing
+            // here (→ caught → null) makes the poller skip the tick instead.
+            assertNotBanned('fetchOrder');
+            const raw = await this.exchange.fetchOrder(orderId, symbol);
+            noteSuccess();
+            return {
+                id: String(raw.id),
+                symbol: raw.symbol ?? symbol ?? '',
+                side: (raw.side ?? 'buy'),
+                type: (raw.type ?? 'limit'),
+                status: raw.status,
+                amount: raw.amount ?? 0,
+                filled: raw.filled ?? 0,
+                remaining: raw.remaining ?? 0,
+                average: raw.average ?? null,
+                price: raw.price ?? null,
+                cost: raw.cost ?? 0,
+                fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+                timestamp: raw.timestamp ?? Date.now(),
+                datetime: raw.datetime ?? new Date().toISOString(),
+                timeInForce: raw.timeInForce ?? 'GTC',
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOrder(${orderId}) failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Fetch a single order by clientOrderId. Used for idempotency recovery
+     * after network timeouts — check if the order went through before retrying.
+     */
+    async fetchOrderByClientId(clientOrderId, symbol) {
+        try {
+            // Pre-gate: never hammer Binance during a ban. Caveat: during a ban
+            // this returns null (= "not found"), so an idempotency caller could
+            // resubmit. Accepted tradeoff — extending the IP ban for everyone is
+            // worse, and the resubmit path is itself reduce-only/bounded.
+            assertNotBanned('fetchOrder');
+            const raw = await this.exchange.fetchOrder(undefined, symbol, {
+                origClientOrderId: clientOrderId,
+            });
+            noteSuccess();
+            return {
+                id: String(raw.id),
+                symbol: raw.symbol ?? symbol,
+                side: (raw.side ?? 'buy'),
+                type: (raw.type ?? 'limit'),
+                status: raw.status,
+                amount: raw.amount ?? 0,
+                filled: raw.filled ?? 0,
+                remaining: raw.remaining ?? 0,
+                average: raw.average ?? null,
+                price: raw.price ?? null,
+                cost: raw.cost ?? 0,
+                fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+                timestamp: raw.timestamp ?? Date.now(),
+                datetime: raw.datetime ?? new Date().toISOString(),
+                timeInForce: raw.timeInForce ?? 'GTC',
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            // Order not found is expected when checking idempotency — don't log as error
+            logger.info(TAG, `fetchOrderByClientId(${clientOrderId}) not found or failed: ${formatError(err)}`);
+            return null;
+        }
+    }
+    /** Cancel a real order on the exchange. Binance Futures splits orders across
+     *  two endpoints — regular (`/fapi/v1/order`) and algo/conditional
+     *  (`/fapi/v1/algoOrder`). Bracket SL/TP live in the algo bucket.
+     *  The caller usually can't tell which bucket a given id belongs to, so we
+     *  try regular first, then fall back to algo by algoId on "not found".
+     *  Symbol is resolved from open-orders snapshot if the caller omits it. */
+    async cancelOrder(orderId, symbol) {
+        const looksAlreadyGone = (msg) => msg.includes('-2011') || msg.includes('-2013') ||
+            /unknown order/i.test(msg) || /does not exist/i.test(msg);
+        let resolvedSymbol = symbol;
+        let hint;
+        if (!resolvedSymbol) {
+            // fetchOpenOrders() already merges regular + algo buckets, so a single
+            // probe is enough to locate the order and its symbol. If a TRUSTED
+            // (non-null) list doesn't contain it, the order is not open — treat the
+            // cancel as an idempotent no-op rather than throwing "symbol required".
+            const open = await this.fetchOpenOrders();
+            if (open === null) {
+                // null = order state UNKNOWN (read failed / weight-paced / banned),
+                // NOT "order gone". Fabricating status:'canceled' here reported a
+                // still-working live order as cancelled exactly when Binance was
+                // shedding us. Same null≠empty rule as cancelAllOrders below: only a
+                // trusted list licenses the idempotent not-found fabrication.
+                throw new Error(`cancelOrder(${orderId}): fetchOpenOrders returned null (order state unknown) — ` +
+                    'cannot locate the order to cancel; refusing to fabricate a cancelled status');
+            }
+            const match = open.find((o) => o.id === orderId);
+            if (match?.symbol) {
+                resolvedSymbol = match.symbol;
+                hint = match;
+            }
+            else {
+                logger.info(TAG, `cancelOrder(${orderId}): not in open-orders snapshot — already cancelled/filled`);
+                return this.fabricateCanceledOrder(orderId, '', undefined);
+            }
+        }
+        try {
+            const raw = await this.exchange.cancelOrder(orderId, resolvedSymbol);
+            return this.normalizeCanceledOrder(raw, resolvedSymbol);
+        }
+        catch (err) {
+            const msg = formatError(err);
+            if (!looksAlreadyGone(msg)) {
+                noteBinanceError(err);
+                throw err;
+            }
+            // Fall through to algo cancel.
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ex = this.exchange;
+        if (typeof ex.fapiPrivateDeleteAlgoOrder !== 'function') {
+            logger.info(TAG, `cancelOrder(${orderId}): already cancelled/filled (no algo endpoint)`);
+            return this.fabricateCanceledOrder(orderId, resolvedSymbol, hint);
+        }
+        let marketId;
+        try {
+            marketId = ex.marketId(resolvedSymbol);
+        }
+        catch {
+            marketId = resolvedSymbol.replace('/', '').split(':')[0];
+        }
+        this.logAlgoCancelChokepoint(`cancelOrder(algoId=${orderId})`, marketId);
+        try {
+            await ex.fapiPrivateDeleteAlgoOrder({ symbol: marketId, algoId: orderId });
+            logger.info(TAG, `cancelOrder(${orderId}): cancelled via algo endpoint`);
+            return this.fabricateCanceledOrder(orderId, resolvedSymbol, hint);
+        }
+        catch (algoErr) {
+            const algoMsg = formatError(algoErr);
+            if (looksAlreadyGone(algoMsg)) {
+                logger.info(TAG, `cancelOrder(${orderId}): already cancelled/filled`);
+                return this.fabricateCanceledOrder(orderId, resolvedSymbol, hint);
+            }
+            noteBinanceError(algoErr);
+            throw algoErr;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    normalizeCanceledOrder(raw, fallbackSymbol) {
+        return {
+            id: String(raw.id),
+            symbol: raw.symbol ?? fallbackSymbol ?? '',
+            side: (raw.side ?? 'buy'),
+            type: (raw.type ?? 'limit'),
+            status: 'canceled',
+            amount: raw.amount ?? 0,
+            filled: raw.filled ?? 0,
+            remaining: raw.remaining ?? 0,
+            average: raw.average ?? null,
+            price: raw.price ?? null,
+            cost: raw.cost ?? 0,
+            fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+            timestamp: raw.timestamp ?? Date.now(),
+            datetime: raw.datetime ?? new Date().toISOString(),
+            timeInForce: raw.timeInForce ?? 'GTC',
+        };
+    }
+    fabricateCanceledOrder(orderId, symbol, hint) {
+        return {
+            id: orderId,
+            symbol,
+            side: hint?.side ?? 'buy',
+            type: hint?.type ?? 'market',
+            status: 'canceled',
+            amount: hint?.amount ?? 0,
+            filled: hint?.filled ?? 0,
+            remaining: hint?.remaining ?? 0,
+            average: hint?.average ?? null,
+            price: hint?.price ?? null,
+            cost: hint?.cost ?? 0,
+            fee: { cost: 0, currency: 'USDT' },
+            timestamp: Date.now(),
+            datetime: new Date().toISOString(),
+            timeInForce: 'GTC',
+        };
+    }
+    /**
+     * Submit a bracket leg (STOP_MARKET or TAKE_PROFIT_MARKET). Sibling of
+     * `createOrder` that widens the `type` parameter to the Binance-specific
+     * trigger-order types. Used by BracketManager to attach SL/TP to an
+     * already-open position.
+     */
+    async createBracketOrder(symbol, type, side, amount, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    params) {
+        // Order path: NOT pre-gated (bracket arming must never be blocked — a
+        // naked position is worse than a ban) but MUST arm the shared gate on a
+        // 429/418 so the read pollers back off. Catch → note → rethrow.
+        let raw;
+        try {
+            // Binance ignores `price` on market-type triggers; pass undefined.
+            raw = await this.exchange.createOrder(symbol, type, side, amount, undefined, params);
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
+        return {
+            id: String(raw.id),
+            symbol: raw.symbol ?? symbol,
+            side: (raw.side ?? side),
+            // Normalise the bracket types into our narrower CcxtOrder.type so downstream
+            // readers don't need to know about STOP_MARKET/TAKE_PROFIT_MARKET. The
+            // bracket identity is carried by the clientOrderId.
+            type: 'market',
+            status: (raw.status ?? 'open'),
+            amount: raw.amount ?? amount,
+            filled: raw.filled ?? 0,
+            remaining: raw.remaining ?? amount,
+            average: raw.average ?? null,
+            price: raw.price ?? null,
+            cost: raw.cost ?? 0,
+            fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+            timestamp: raw.timestamp ?? Date.now(),
+            datetime: raw.datetime ?? new Date().toISOString(),
+            timeInForce: raw.timeInForce ?? 'GTC',
+        };
+    }
+    /**
+     * Cancel an order by its clientOrderId (not exchange id). Idempotent:
+     * "order does not exist" is treated as success since the intent was to
+     * remove the order. Binance returns -2011 when the order is already gone.
+     *
+     * Tries the regular-order cancel first, then the algo-order cancel on
+     * failure, because Binance Futures splits the two endpoints and we can't
+     * tell from the clientOrderId alone which bucket the order landed in.
+     */
+    /** MANDATORY ALGO-CANCEL CHOKEPOINT TRACE (2026-05-16, widened after the
+     *  Dropbox-revert blinded the cancelOrderByClientId-only tracer).
+     *
+     *  EVERY bracket SL/TP is a Binance *algo* order; EVERY cancel of one that
+     *  reaches the exchange goes through `fapiPrivateDeleteAlgoOrder` — no
+     *  matter which higher-level method ordered it (cancelOrder by algoId,
+     *  cancelOrderByClientId by cid, cancelSymbolBracketOrders, cancelBrackets,
+     *  modify_*, the reconciler, the agent, anything). Logging the caller stack
+     *  at THIS one REST chokepoint makes the next bracket disappearance
+     *  unambiguous, and — critically — if a bracket leg goes `X:CANCELED` on
+     *  the user-data WS with NO chokepoint log around that timestamp, then it
+     *  was NOT cancelled by our code at all (Binance-side auto-cancel — a
+     *  fundamentally different fix). Pure observability, zero behaviour change.
+     *  Remove once the proven source is fixed and soaked. */
+    logAlgoCancelChokepoint(via, marketId) {
+        const stack = new Error('algo-cancel-trace').stack ?? '(no stack)';
+        logger.warn(TAG, `ALGO-CANCEL CHOKEPOINT — fapiPrivateDeleteAlgoOrder about to fire ` +
+            `(via ${via}, symbol=${marketId}). If this id is an rc-*-{s,t} ` +
+            `bracket leg, this is the cancel that strips protection. ` +
+            `Caller stack follows:\n${stack}`);
+    }
+    async cancelOrderByClientId(clientOrderId, symbol) {
+        // ---- MANDATORY BRACKET-CANCEL ATTRIBUTION (2026-05-16) --------------
+        // Every bracket-protection cancel in the entire plugin funnels through
+        // this one method. All prior fixes failed because each cancel path logs
+        // NOTHING on success, so the rogue silent canceller could only be
+        // INFERRED (and was, wrongly, repeatedly). This logs the exact caller
+        // stack for ANY rc-*-{s,t} (stop/target protection-leg) cancel — zero
+        // behaviour change, pure observability — so the very next time a live
+        // position's bracket disappears, the journal names the precise function
+        // that ordered it instead of leaving us to guess. Remove once the
+        // proven source is fixed and soaked.
+        if (isBracketCid(clientOrderId)) {
+            const stack = new Error('bracket-cancel-trace').stack ?? '(no stack)';
+            logger.warn(TAG, `BRACKET-CANCEL ATTRIBUTION — cancelOrderByClientId(${clientOrderId}, ` +
+                `${symbol}) was called. This cancels a STOP/TP protection leg. ` +
+                `Caller stack follows:\n${stack}`);
+        }
+        const looksAlreadyGone = (msg) => msg.includes('-2011') || msg.includes('-2013') ||
+            /unknown order/i.test(msg) || /does not exist/i.test(msg);
+        // Try regular-order cancel first.
+        let regularErr;
+        try {
+            await this.exchange.cancelOrder(undefined, symbol, {
+                origClientOrderId: clientOrderId,
+            });
+            return;
+        }
+        catch (err) {
+            const msg = formatError(err);
+            if (looksAlreadyGone(msg)) {
+                // Maybe it's an algo order instead — fall through to algo cancel.
+                regularErr = err;
+            }
+            else {
+                noteBinanceError(err);
+                throw err;
+            }
+        }
+        // Fall back to algo-order cancel by clientAlgoId.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            if (typeof ex.fapiPrivateDeleteAlgoOrder !== 'function') {
+                // Older CCXT without algo support — treat regular "gone" as success.
+                logger.info(TAG, `cancelOrderByClientId(${clientOrderId}): already cancelled/filled (no algo endpoint)`);
+                return;
+            }
+            let marketId;
+            try {
+                marketId = ex.marketId(symbol);
+            }
+            catch {
+                marketId = symbol.replace('/', '').split(':')[0];
+            }
+            this.logAlgoCancelChokepoint(`cancelOrderByClientId(cid=${clientOrderId})`, marketId);
+            await ex.fapiPrivateDeleteAlgoOrder({
+                symbol: marketId,
+                clientAlgoId: clientOrderId,
+            });
+            logger.info(TAG, `cancelOrderByClientId(${clientOrderId}): cancelled via algo endpoint`);
+        }
+        catch (algoErr) {
+            const algoMsg = formatError(algoErr);
+            if (looksAlreadyGone(algoMsg)) {
+                logger.info(TAG, `cancelOrderByClientId(${clientOrderId}): already cancelled/filled`);
+                return;
+            }
+            // Neither endpoint worked. Surface the original regular error so callers
+            // see the most informative message.
+            noteBinanceError(algoErr);
+            throw regularErr ?? algoErr;
+        }
+    }
+    /** Cancel all orders on the exchange for a symbol (or everything, if omitted).
+     *  Covers BOTH regular orders and algo/conditional orders via per-order
+     *  cancellation through `cancelOrderByClientId`, which internally falls
+     *  back across both buckets.
+     *
+     *  **Bracket protection is preserved by default.** Orders whose
+     *  clientOrderId parses as a bracket stop/target (`rc-<16hex>-s` or `-t`)
+     *  are NEVER cancelled by this method — otherwise a kill-switch fire or an
+     *  agent-initiated `cancel_all_orders` would strip exchange-side protection
+     *  off open positions and leave them naked. This was the root cause of
+     *  the 2026-04-21 naked-position incident (4 live positions ran without
+     *  stops for hours after kill-switch cancels swept their brackets).
+     *
+     *  Callers that explicitly need to cancel brackets (e.g. `closePosition`
+     *  after flattening the position) must go through
+     *  `BracketManager.cancelBrackets(symbol)` which is symbol-scoped and
+     *  tracks the cancellation in the ledger. */
+    async cancelAllOrders(symbol) {
+        try {
+            // fetchOpenOrders merges regular + algo — every open order in either
+            // bucket is visible here with its clientOrderId.
+            const open = await this.fetchOpenOrders(symbol);
+            if (open === null) {
+                // null = order state UNKNOWN (read failed / weight-paced / banned),
+                // NOT "no orders". This method cancels per-order (bracket
+                // preservation), so without the list it cannot do its job — throw so
+                // the emergency caller's retry loop escalates loudly instead of
+                // reporting a silent "0 cancelled" success while orders are live.
+                throw new Error('cancelAllOrders: fetchOpenOrders returned null (order state unknown) — cannot enumerate orders to cancel');
+            }
+            const all = open;
+            const cancelable = [];
+            let preservedBrackets = 0;
+            for (const o of all) {
+                if (!o.clientOrderId) {
+                    // No clientOrderId (rare; manual orders from the Binance UI) — we
+                    // can't identify it as a bracket protective order, but we also
+                    // can't cancel it via cancelOrderByClientId. Skip with a warning.
+                    logger.warn(TAG, `cancelAllOrders: order without clientOrderId skipped (id=${o.id} symbol=${o.symbol})`);
+                    continue;
+                }
+                const parsed = parseBracketCid(o.clientOrderId);
+                if (parsed && (parsed.role === 'stop' || parsed.role === 'target')) {
+                    preservedBrackets++;
+                    continue;
+                }
+                cancelable.push(o);
+            }
+            if (cancelable.length === 0) {
+                if (preservedBrackets > 0) {
+                    logger.info(TAG, `cancelAllOrders: nothing to cancel; preserved ${preservedBrackets} bracket protective order(s)`);
+                }
+                return;
+            }
+            // Cancel each non-bracket order per-order. cancelOrderByClientId tries
+            // the regular endpoint first and falls back to the algo endpoint, so
+            // this one call covers either order type. A bulk sweep (the previous
+            // implementation) couldn't do the bracket-preservation filtering.
+            for (const o of cancelable) {
+                if (!o.symbol || !o.clientOrderId)
+                    continue;
+                try {
+                    await this.cancelOrderByClientId(o.clientOrderId, o.symbol);
+                }
+                catch (err) {
+                    logger.warn(TAG, `cancelAllOrders: cancel ${o.clientOrderId} (${o.symbol}) failed: ${formatError(err)}`);
+                }
+            }
+            if (preservedBrackets > 0) {
+                logger.info(TAG, `cancelAllOrders: cancelled ${cancelable.length}, preserved ${preservedBrackets} bracket protective order(s)`);
+            }
+            else {
+                logger.info(TAG, `cancelAllOrders: cancelled ${cancelable.length} order(s)`);
+            }
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `cancelAllOrders failed: ${formatError(err)}`);
+            throw err;
+        }
+    }
+    /** Disable Binance's per-symbol `countdownCancelAll` "dead-man's-switch"
+     *  (POST /fapi/v1/countdownCancelAll, countdownTime=0).
+     *
+     *  ROOT-CAUSE FIX 2026-05-16. A countdownCancelAll timer was armed on this
+     *  account from OUTSIDE our codebase (verified: nothing in plugin/skill/
+     *  scripts/OpenClaw-gateway/ccxt ever sets it). When armed, Binance purges
+     *  EVERY open order for the symbol when the countdown lapses — server-side,
+     *  empty reason, NOT via the cancel endpoint — which is why every bracket
+     *  (both order forms, all symbols) was auto-cancelled ~17-53s after
+     *  placement and no instrumentation ever caught a caller. Proven decisively:
+     *  a clean order placed with the switch disabled survived 5 min when every
+     *  churned bracket died in ~25s. countdownTime=0 is Binance's documented
+     *  DISABLE value; purely protective (cannot cancel/modify/close anything),
+     *  idempotent, harmless no-op if none is armed. We proactively disable it
+     *  per active symbol so an externally-armed switch can never again strip
+     *  protection. Best-effort + safety-critical: like order paths it is NOT
+     *  pre-gated (must never be blocked) but arms the ban gate on error. */
+    async disableCountdownCancelAll(symbol) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ex = this.exchange;
+        if (typeof ex.fapiPrivatePostCountdownCancelAll !== 'function') {
+            logger.warn(TAG, `disableCountdownCancelAll(${symbol}): CCXT lacks fapiPrivatePostCountdownCancelAll — cannot neutralise the kill-switch; check ccxt version`);
+            return;
+        }
+        let marketId;
+        try {
+            marketId = ex.marketId(symbol);
+        }
+        catch {
+            marketId = symbol.replace('/', '').split(':')[0];
+        }
+        try {
+            await ex.fapiPrivatePostCountdownCancelAll({ symbol: marketId, countdownTime: 0 });
+        }
+        catch (err) {
+            // Never throw into the bracket-attach path — a failed disable must not
+            // block protection placement. Arm the gate on 429/418 like order paths.
+            noteBinanceError(err);
+            logger.warn(TAG, `disableCountdownCancelAll(${marketId}) failed (non-fatal): ${formatError(err)}`);
+        }
+    }
+    /** Translate a Binance market ID (e.g. `BTCUSDT`) back to the unified
+     *  CCXT symbol (e.g. `BTC/USDT:USDT`, with the `:SETTLE` suffix stripped
+     *  to match the rest of the system's un-suffixed format). Used when parsing
+     *  user-data WebSocket events — Binance sends raw market IDs, but the
+     *  plugin's state store + downstream consumers use unified symbols.
+     *  Falls back to the raw id if the market isn't in CCXT's cache. */
+    symbolFromMarketId(marketId) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            const raw = ex.markets_by_id?.[marketId];
+            // markets_by_id can return a single market or an array (shared ids).
+            const market = Array.isArray(raw) ? raw[0] : raw;
+            const unified = typeof market?.symbol === 'string' ? market.symbol : null;
+            if (unified) {
+                // Strip `:SETTLE` so every consumer sees the same format. See
+                // memory/feedback_symbol_normalize_boundary.md.
+                return unified.replace(/:[A-Z]+$/, '');
+            }
+        }
+        catch { /* fall through */ }
+        return marketId;
+    }
+    /** Create a user-data listenKey via POST /fapi/v1/listenKey. The returned
+     *  key is the authentication token for the user-data WebSocket stream
+     *  (`wss://fstream.binance.com/private/ws/<listenKey>`). Keys expire after 60 min
+     *  of inactivity — callers must schedule `keepAliveListenKey` every ~25 min. */
+    async createListenKey() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ex = this.exchange;
+        if (typeof ex.fapiPrivatePostListenKey !== 'function') {
+            throw new Error('CCXT missing fapiPrivatePostListenKey — check ccxt version');
+        }
+        try {
+            // Gate listenKey ops too: a POST during an active 418 ban EXTENDS the
+            // ban (Binance extends on ANY request while banned). Better to fail the
+            // mint fast and let UserDataStream back off than to keep the ban alive.
+            assertNotBanned('createListenKey');
+            const res = await ex.fapiPrivatePostListenKey();
+            noteSuccess();
+            const key = typeof res?.listenKey === 'string' ? res.listenKey : null;
+            if (!key)
+                throw new Error('listenKey missing from Binance response');
+            return key;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
+    }
+    /** Keep-alive the current listenKey via PUT /fapi/v1/listenKey. Must be
+     *  called within 60 min of the last keep-alive; 25-min cadence gives a 2x
+     *  safety margin. Binance does not require the key to be passed — the
+     *  endpoint acts on whichever key the API key last minted. */
+    async keepAliveListenKey() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ex = this.exchange;
+        if (typeof ex.fapiPrivatePutListenKey !== 'function') {
+            throw new Error('CCXT missing fapiPrivatePutListenKey — check ccxt version');
+        }
+        try {
+            assertNotBanned('keepAliveListenKey');
+            await ex.fapiPrivatePutListenKey();
+            noteSuccess();
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
+    }
+    /** Close the current listenKey via DELETE /fapi/v1/listenKey. Polite
+     *  teardown on graceful shutdown; Binance will otherwise expire the key
+     *  after 60 min of inactivity. */
+    async closeListenKey() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ex = this.exchange;
+        if (typeof ex.fapiPrivateDeleteListenKey !== 'function') {
+            throw new Error('CCXT missing fapiPrivateDeleteListenKey — check ccxt version');
+        }
+        try {
+            // During a ban, skip the polite DELETE entirely — it would extend the
+            // ban. The key expires on its own after 60 min of inactivity anyway.
+            assertNotBanned('closeListenKey');
+            await ex.fapiPrivateDeleteListenKey();
+            noteSuccess();
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
+    }
+    /** Whether this instance is connected to testnet. */
+    isTestnet() {
+        return this.testnet;
+    }
+    /** Get the underlying CCXT exchange instance (for loadMarkets, position mode detection, etc.). */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getExchange() {
+        return this.exchange;
+    }
+    /**
+     * Get rate-limit headers from the last exchange response.
+     * CCXT stores these on the exchange instance after each request.
+     * Returns empty object if not available.
+     */
+    getLastResponseHeaders() {
+        try {
+            // CCXT stores last response headers in exchange.last_response_headers (Python)
+            // or exchange.lastResponseHeaders (JS). Try both patterns.
+            const headers = this.exchange.last_response_headers
+                ?? this.exchange.lastResponseHeaders
+                ?? {};
+            // Normalize keys to lowercase
+            const result = {};
+            for (const [k, v] of Object.entries(headers)) {
+                result[k.toLowerCase()] = String(v);
+            }
+            return result;
+        }
+        catch {
+            return {};
+        }
+    }
+}