@reefclaw/openclaw-plugin 0.1.0

package/live/exchange-info-cache.d.ts

@@ -0,0 +1,35 @@
+export interface SymbolRules {
+    minNotional: number;
+    minQty: number;
+    stepSize: number;
+    tickSize: number;
+    maxQty: number;
+    pricePrecision: number;
+    amountPrecision: number;
+}
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    roundedAmount: number;
+    roundedPrice?: number;
+}
+/**
+ * Normalize symbol format for consistent lookups.
+ * Tools use "BTC/USDT", CCXT futures markets are "BTC/USDT:USDT".
+ * This function tries both formats to find a match.
+ */
+export declare function normalizeSymbol(symbol: string, knownSymbols: Set<string>): string;
+export declare class ExchangeInfoCache {
+    private rules;
+    /** Set of all known symbols for normalization lookups. */
+    private knownSymbols;
+    /** Load market info from CCXT exchange instance. */
+    load(exchange: any): Promise<void>;
+    /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
+    getRules(symbol: string): SymbolRules | undefined;
+    /** Validate and round order parameters before submission. */
+    validate(symbol: string, amount: number, price?: number, lastPrice?: number): ValidationResult;
+    /** Round value to step size and precision. */
+    private roundToStep;
+    get size(): number;
+}

package/live/exchange-info-cache.js

@@ -0,0 +1,119 @@
+// Exchange info cache — caches per-symbol trading rules (min notional, lot sizes, tick sizes).
+// Loaded once on startup from CCXT loadMarkets(), used to validate and round orders before submission.
+import { logger } from '../logger.js';
+const TAG = 'exchange-info';
+/**
+ * Normalize symbol format for consistent lookups.
+ * Tools use "BTC/USDT", CCXT futures markets are "BTC/USDT:USDT".
+ * This function tries both formats to find a match.
+ */
+export function normalizeSymbol(symbol, knownSymbols) {
+    // Exact match first
+    if (knownSymbols.has(symbol))
+        return symbol;
+    // Try adding :USDT suffix (most common futures pattern)
+    const withSuffix = `${symbol}:USDT`;
+    if (knownSymbols.has(withSuffix))
+        return withSuffix;
+    // Try removing :USDT suffix
+    const withoutSuffix = symbol.replace(/:USDT$/, '');
+    if (knownSymbols.has(withoutSuffix))
+        return withoutSuffix;
+    // No match — return as-is (will fail validation with "Unknown symbol")
+    return symbol;
+}
+export class ExchangeInfoCache {
+    rules = new Map();
+    /** Set of all known symbols for normalization lookups. */
+    knownSymbols = new Set();
+    /** Load market info from CCXT exchange instance. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async load(exchange) {
+        const info = await exchange.loadMarkets(true); // force refresh
+        for (const [symbol, market] of Object.entries(info)) {
+            const m = market;
+            // Only cache futures (swap) markets
+            if (m.type !== 'swap')
+                continue;
+            const limits = m.limits;
+            const precision = m.precision;
+            const rules = {
+                minNotional: limits?.cost?.min ?? 5,
+                minQty: limits?.amount?.min ?? 0.001,
+                stepSize: precision?.amount != null ? Math.pow(10, -precision.amount) : 0.001,
+                tickSize: precision?.price != null ? Math.pow(10, -precision.price) : 0.01,
+                maxQty: limits?.amount?.max ?? Infinity,
+                pricePrecision: precision?.price ?? 2,
+                amountPrecision: precision?.amount ?? 3,
+            };
+            // Store under both "BTC/USDT:USDT" and "BTC/USDT" keys for lookup flexibility
+            this.rules.set(symbol, rules);
+            this.knownSymbols.add(symbol);
+            const shortSymbol = symbol.replace(/:USDT$/, '');
+            if (shortSymbol !== symbol && !this.rules.has(shortSymbol)) {
+                this.rules.set(shortSymbol, rules);
+                this.knownSymbols.add(shortSymbol);
+            }
+        }
+        logger.info(TAG, `Loaded exchange rules for ${this.knownSymbols.size} symbols`);
+    }
+    /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
+    getRules(symbol) {
+        return this.rules.get(symbol) ?? this.rules.get(normalizeSymbol(symbol, this.knownSymbols));
+    }
+    /** Validate and round order parameters before submission. */
+    validate(symbol, amount, price, lastPrice) {
+        const normalized = normalizeSymbol(symbol, this.knownSymbols);
+        const rules = this.rules.get(normalized);
+        if (!rules)
+            return { valid: false, error: `Unknown symbol: ${symbol}`, roundedAmount: amount };
+        const roundedAmount = this.roundToStep(amount, rules.stepSize, rules.amountPrecision);
+        const roundedPrice = price != null
+            ? this.roundToStep(price, rules.tickSize, rules.pricePrecision)
+            : undefined;
+        if (roundedAmount < rules.minQty) {
+            // Include the requested amount + the rule context. Without this, sub-step
+            // requests floor to 0 and the agent reads "Amount 0 below min 0.001"
+            // as a validator bug rather than as "your size is below the exchange
+            // minimum". Surface the dollar minimum too when we know the price —
+            // tells the agent exactly how much to size up.
+            const refPrice = roundedPrice ?? price ?? lastPrice;
+            const minNotionalAtPrice = refPrice != null && refPrice > 0
+                ? ` (~$${(rules.minQty * refPrice).toFixed(2)})`
+                : '';
+            const requestedDesc = roundedAmount === amount
+                ? `${roundedAmount}`
+                : `${amount} (rounded to ${roundedAmount} by step ${rules.stepSize})`;
+            return {
+                valid: false,
+                error: `Amount ${requestedDesc} below min ${rules.minQty}${minNotionalAtPrice} for ${symbol}`,
+                roundedAmount,
+            };
+        }
+        if (roundedAmount > rules.maxQty) {
+            return { valid: false, error: `Amount ${roundedAmount} above max ${rules.maxQty} for ${symbol}`, roundedAmount };
+        }
+        // Check min notional (order value)
+        const refPrice = roundedPrice ?? lastPrice;
+        if (refPrice != null && refPrice > 0) {
+            const notional = roundedAmount * refPrice;
+            if (notional < rules.minNotional) {
+                return {
+                    valid: false,
+                    error: `Order notional $${notional.toFixed(2)} below minimum $${rules.minNotional} for ${symbol}`,
+                    roundedAmount,
+                    roundedPrice,
+                };
+            }
+        }
+        return { valid: true, roundedAmount, roundedPrice };
+    }
+    /** Round value to step size and precision. */
+    roundToStep(value, stepSize, precision) {
+        const stepped = Math.floor(value / stepSize) * stepSize;
+        return Number(stepped.toFixed(precision));
+    }
+    get size() {
+        return this.rules.size;
+    }
+}

package/live/fact-subscriber.d.ts

@@ -0,0 +1,78 @@
+import type { MarketContext } from '@reefclaw/shared';
+export interface ParsedEvent {
+    id?: number;
+    event: string;
+    data: string;
+}
+/**
+ * Incremental SSE parser. Feed raw text; returns the complete events plus the
+ * unparsed remainder (a partial event still arriving at the buffer tail). Pure.
+ */
+export declare function parseSse(buffer: string): {
+    events: ParsedEvent[];
+    remainder: string;
+};
+export interface FactSubscriberOptions {
+    /** Intel base URL, e.g. https://intel.reefclaw.com */
+    baseUrl: string;
+    /** rc_ connection token. */
+    token: string;
+    symbols: string[];
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Base reconnect delay (ms). Doubles per consecutive failure with ±20%
+     *  jitter up to reconnectCapMs — a fixed delay would hard-loop a 401/404
+     *  (token misconfig / stream disabled) at max rate forever. */
+    reconnectDelayMs?: number;
+    /** Reconnect backoff cap (ms, default 60s). */
+    reconnectCapMs?: number;
+    /** Abort + reconnect when a LIVE connection delivers no bytes for this
+     *  long (default 30s = 6× the broadcaster's 5s cadence). Without this, a
+     *  silently stalled stream (no close, no RST) leaves `reader.read()`
+     *  pending forever while the evaluator keeps serving ever-staler facts —
+     *  same class as the user-data-stream / routed-WS staleness watchdogs. */
+    stallThresholdMs?: number;
+    /** Injected for tests. */
+    now?: () => number;
+}
+export declare class FactSubscriber {
+    private readonly opts;
+    private readonly latest;
+    /** Per-symbol wall-clock receipt time of the latest fact (now()-based). */
+    private readonly latestAt;
+    private buffer;
+    private lastEventId;
+    private running;
+    private controller;
+    private applied;
+    private errors;
+    private stalls;
+    private consecutiveFailures;
+    /** 0 = no live connection; otherwise last byte-activity time. */
+    private lastChunkAt;
+    private watchdog;
+    private readonly now;
+    constructor(opts: FactSubscriberOptions);
+    /** Latest streamed context for a symbol — what the evaluator reads. */
+    getLatest(symbol: string): MarketContext | null;
+    /** When the latest fact for a symbol ARRIVED (receipt clock, not the
+     *  context's own timestamp). Null when no fact has ever arrived. Callers
+     *  use this to refuse stale facts (LocalSignalService.getSnapshot). */
+    getLatestFactAt(symbol: string): number | null;
+    getStats(): {
+        applied: number;
+        errors: number;
+        stalls: number;
+        lastEventId: number | undefined;
+        symbols: number;
+    };
+    /** Apply one parsed event: deserialize a `fact` and store it as the latest
+     *  context for its symbol. No I/O — exposed for tests. */
+    applyEvent(ev: ParsedEvent): void;
+    /** Feed a raw text chunk; handles events split across chunk boundaries. */
+    ingest(chunk: string): void;
+    start(): void;
+    stop(): void;
+    private backoffMs;
+    private loop;
+}

package/live/fact-subscriber.js

@@ -0,0 +1,182 @@
+// Plugin-side fact stream subscriber — facts-out (docs/FACTS_OUT_ARCHITECTURE.md)
+// step 4. Connects to the intel broadcaster's SSE endpoint
+// (/api/facts/subscribe), maintains the latest MarketContext per symbol, and
+// feeds it to the LocalStrategyEvaluator (PR #45). Reconnects with Last-Event-ID.
+//
+// Uses the SAME matched (de)serializer the broadcaster uses (shared via the sync
+// manifest), so the wire round-trip is byte-identical — the Date fields are
+// rehydrated rather than left as strings.
+//
+// NOT wired into the heartbeat yet — built + tested standalone. The parse /
+// apply core is pure and unit-tested; the fetch loop is thin plumbing.
+import { deserializeContext } from '../signals/serialize-context.js';
+/**
+ * Incremental SSE parser. Feed raw text; returns the complete events plus the
+ * unparsed remainder (a partial event still arriving at the buffer tail). Pure.
+ */
+export function parseSse(buffer) {
+    const events = [];
+    let sep;
+    // Events are terminated by a blank line ("\n\n").
+    while ((sep = buffer.indexOf('\n\n')) !== -1) {
+        const raw = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        let id;
+        let event = 'message';
+        const dataLines = [];
+        for (const line of raw.split('\n')) {
+            if (line.startsWith('id:')) {
+                const v = Number(line.slice(3).trim());
+                if (Number.isFinite(v))
+                    id = v;
+            }
+            else if (line.startsWith('event:')) {
+                event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                dataLines.push(line.slice(5).replace(/^ /, ''));
+            }
+            // ":" comment lines and unknown fields are ignored, per the SSE spec.
+        }
+        events.push({ id, event, data: dataLines.join('\n') });
+    }
+    return { events, remainder: buffer };
+}
+export class FactSubscriber {
+    opts;
+    latest = new Map();
+    /** Per-symbol wall-clock receipt time of the latest fact (now()-based). */
+    latestAt = new Map();
+    buffer = '';
+    lastEventId;
+    running = false;
+    controller = null;
+    applied = 0;
+    errors = 0;
+    stalls = 0;
+    consecutiveFailures = 0;
+    /** 0 = no live connection; otherwise last byte-activity time. */
+    lastChunkAt = 0;
+    watchdog = null;
+    now;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Latest streamed context for a symbol — what the evaluator reads. */
+    getLatest(symbol) {
+        return this.latest.get(symbol) ?? null;
+    }
+    /** When the latest fact for a symbol ARRIVED (receipt clock, not the
+     *  context's own timestamp). Null when no fact has ever arrived. Callers
+     *  use this to refuse stale facts (LocalSignalService.getSnapshot). */
+    getLatestFactAt(symbol) {
+        return this.latestAt.get(symbol) ?? null;
+    }
+    getStats() {
+        return {
+            applied: this.applied,
+            errors: this.errors,
+            stalls: this.stalls,
+            lastEventId: this.lastEventId,
+            symbols: this.latest.size,
+        };
+    }
+    /** Apply one parsed event: deserialize a `fact` and store it as the latest
+     *  context for its symbol. No I/O — exposed for tests. */
+    applyEvent(ev) {
+        if (ev.id !== undefined)
+            this.lastEventId = ev.id;
+        if (ev.event !== 'fact')
+            return;
+        try {
+            const ctx = deserializeContext(ev.data);
+            this.latest.set(ctx.symbol, ctx);
+            this.latestAt.set(ctx.symbol, this.now());
+            this.applied++;
+        }
+        catch {
+            this.errors++;
+        }
+    }
+    /** Feed a raw text chunk; handles events split across chunk boundaries. */
+    ingest(chunk) {
+        this.buffer += chunk;
+        const { events, remainder } = parseSse(this.buffer);
+        this.buffer = remainder;
+        for (const ev of events)
+            this.applyEvent(ev);
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const stallMs = this.opts.stallThresholdMs ?? 30_000;
+        this.watchdog = setInterval(() => {
+            if (!this.running || this.lastChunkAt === 0)
+                return;
+            if (this.now() - this.lastChunkAt > stallMs) {
+                this.stalls++;
+                this.lastChunkAt = 0; // one abort per stall — reset until reconnect
+                this.controller?.abort();
+            }
+        }, Math.max(1_000, Math.floor(stallMs / 3)));
+        this.watchdog.unref?.();
+        void this.loop();
+    }
+    stop() {
+        this.running = false;
+        if (this.watchdog) {
+            clearInterval(this.watchdog);
+            this.watchdog = null;
+        }
+        this.controller?.abort();
+    }
+    backoffMs() {
+        const base = this.opts.reconnectDelayMs ?? 3_000;
+        const cap = this.opts.reconnectCapMs ?? 60_000;
+        const exp = Math.min(base * 2 ** Math.min(this.consecutiveFailures, 10), cap);
+        return Math.round(exp * (0.8 + Math.random() * 0.4)); // ±20% jitter
+    }
+    async loop() {
+        const doFetch = this.opts.fetchImpl ?? fetch;
+        const url = `${this.opts.baseUrl}/api/facts/subscribe?symbols=${encodeURIComponent(this.opts.symbols.join(','))}`;
+        while (this.running) {
+            this.controller = new AbortController();
+            let gotData = false;
+            try {
+                const headers = {
+                    Authorization: `Bearer ${this.opts.token}`,
+                    Accept: 'text/event-stream',
+                };
+                if (this.lastEventId !== undefined)
+                    headers['Last-Event-ID'] = String(this.lastEventId);
+                const resp = await doFetch(url, { headers, signal: this.controller.signal });
+                if (!resp.ok || !resp.body)
+                    throw new Error(`fact stream HTTP ${resp.status}`);
+                this.buffer = '';
+                this.lastChunkAt = this.now(); // arm the stall watchdog
+                const reader = resp.body.getReader();
+                const decoder = new TextDecoder();
+                while (this.running) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    this.lastChunkAt = this.now();
+                    gotData = true;
+                    this.ingest(decoder.decode(value, { stream: true }));
+                }
+            }
+            catch {
+                if (!this.running)
+                    return;
+                this.errors++;
+            }
+            this.lastChunkAt = 0; // no live connection — watchdog idle
+            if (!this.running)
+                return;
+            this.consecutiveFailures = gotData ? 0 : this.consecutiveFailures + 1;
+            await new Promise((r) => setTimeout(r, this.backoffMs()));
+        }
+    }
+}

package/live/intent-journal.d.ts

@@ -0,0 +1,42 @@
+export interface OrderIntent {
+    clientOrderId: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit';
+    amount: number;
+    price?: number;
+    createdAt: string;
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    exchangeOrderId?: string;
+    error?: string;
+    resolvedAt?: string;
+}
+export declare class IntentJournal {
+    private readonly filePath;
+    private intents;
+    /** `basePath` overrides the storage root (default `~/.openclaw/plugins`).
+     *  Tests pass a temp dir to keep runs hermetic; production omits it.
+     *  `OPENCLAW_HOME` env var, when set, also reroutes the default base. */
+    constructor(pluginId?: string, opts?: {
+        basePath?: string;
+    });
+    /** Record a new order intent BEFORE submitting to exchange. */
+    recordIntent(intent: Omit<OrderIntent, 'createdAt' | 'status'>): OrderIntent;
+    /** Update intent status after exchange response. */
+    updateIntent(clientOrderId: string, update: Partial<Pick<OrderIntent, 'status' | 'exchangeOrderId' | 'error'>>): void;
+    /** Get all unresolved intents (pending or submitted). */
+    getUnresolved(): OrderIntent[];
+    /** Get intent by clientOrderId. */
+    getIntent(clientOrderId: string): OrderIntent | undefined;
+    /** Get the journal file path. */
+    getFilePath(): string;
+    /** Load existing intents from JSONL file. Later entries override earlier ones (last-write-wins). */
+    private loadExisting;
+    /** Append a line to the JSONL file. */
+    private appendLine;
+    /**
+     * Compact the journal — rewrite with only the latest state of each intent.
+     * Call periodically (e.g., daily) to prevent unbounded file growth.
+     */
+    compact(): void;
+}

package/live/intent-journal.js

@@ -0,0 +1,122 @@
+// Order intent journal — append-only JSONL file for crash recovery and idempotency.
+// Every live order intent is written BEFORE submission. On network timeout,
+// check exchange by clientOrderId before retry. On restart, resolve all pending intents.
+import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'intent-journal';
+export class IntentJournal {
+    filePath;
+    intents = new Map();
+    /** `basePath` overrides the storage root (default `~/.openclaw/plugins`).
+     *  Tests pass a temp dir to keep runs hermetic; production omits it.
+     *  `OPENCLAW_HOME` env var, when set, also reroutes the default base. */
+    constructor(pluginId, opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        const dir = join(base, pluginId ?? 'reefclaw-paper-trading');
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        this.filePath = join(dir, 'order-intents.jsonl');
+        this.loadExisting();
+    }
+    /** Record a new order intent BEFORE submitting to exchange. */
+    recordIntent(intent) {
+        const full = {
+            ...intent,
+            createdAt: new Date().toISOString(),
+            status: 'pending',
+        };
+        this.intents.set(full.clientOrderId, full);
+        this.appendLine(full);
+        logger.info(TAG, `Intent recorded: ${full.clientOrderId} ${full.side} ${full.amount} ${full.symbol}`);
+        return full;
+    }
+    /** Update intent status after exchange response. */
+    updateIntent(clientOrderId, update) {
+        const intent = this.intents.get(clientOrderId);
+        if (!intent) {
+            logger.warn(TAG, `Intent not found for update: ${clientOrderId}`);
+            return;
+        }
+        if (update.status)
+            intent.status = update.status;
+        if (update.exchangeOrderId)
+            intent.exchangeOrderId = update.exchangeOrderId;
+        if (update.error)
+            intent.error = update.error;
+        if (update.status === 'confirmed' || update.status === 'failed') {
+            intent.resolvedAt = new Date().toISOString();
+        }
+        this.appendLine(intent);
+    }
+    /** Get all unresolved intents (pending or submitted). */
+    getUnresolved() {
+        return Array.from(this.intents.values()).filter(i => i.status === 'pending' || i.status === 'submitted');
+    }
+    /** Get intent by clientOrderId. */
+    getIntent(clientOrderId) {
+        return this.intents.get(clientOrderId);
+    }
+    /** Get the journal file path. */
+    getFilePath() {
+        return this.filePath;
+    }
+    // ---- Internal ----
+    /** Load existing intents from JSONL file. Later entries override earlier ones (last-write-wins). */
+    loadExisting() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const content = readFileSync(this.filePath, 'utf-8');
+            const lines = content.split('\n').filter(l => l.trim());
+            for (const line of lines) {
+                try {
+                    const intent = JSON.parse(line);
+                    if (intent.clientOrderId) {
+                        this.intents.set(intent.clientOrderId, intent);
+                    }
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+            const unresolved = this.getUnresolved();
+            if (unresolved.length > 0) {
+                logger.warn(TAG, `Loaded ${this.intents.size} intents, ${unresolved.length} unresolved`);
+            }
+            else {
+                logger.info(TAG, `Loaded ${this.intents.size} intents, all resolved`);
+            }
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to load intent journal: ${formatError(err)}`);
+        }
+    }
+    /** Append a line to the JSONL file. */
+    appendLine(intent) {
+        try {
+            appendFileSync(this.filePath, JSON.stringify(intent) + '\n');
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to write intent: ${formatError(err)}`);
+        }
+    }
+    /**
+     * Compact the journal — rewrite with only the latest state of each intent.
+     * Call periodically (e.g., daily) to prevent unbounded file growth.
+     */
+    compact() {
+        try {
+            const lines = Array.from(this.intents.values())
+                .map(i => JSON.stringify(i))
+                .join('\n') + '\n';
+            writeFileSync(this.filePath, lines);
+            logger.info(TAG, `Compacted journal: ${this.intents.size} intents`);
+        }
+        catch (err) {
+            logger.error(TAG, `Failed to compact journal: ${formatError(err)}`);
+        }
+    }
+}

package/live/listen-key-manager.d.ts

@@ -0,0 +1,70 @@
+import { EventEmitter } from 'node:events';
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+/** Injectable timer/clock deps — makes fake-timer tests trivial. */
+export interface ListenKeyTimerDeps {
+    setTimeout: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
+    now: () => number;
+}
+export interface ListenKeyManagerOptions {
+    /** Defaults to 25 * 60_000 (25 min). */
+    refreshIntervalMs?: number;
+    /** How many consecutive keep-alive failures before emitting 'keyKeepAliveFailed'.
+     *  Defaults to 3 — transient network failures self-recover; a sustained
+     *  failure probably means the key is gone and the parent must reconnect. */
+    maxConsecutiveFailures?: number;
+    /** Timer injection for tests. Defaults to real setTimeout/Date. */
+    timers?: Partial<ListenKeyTimerDeps>;
+}
+/** Emitted events. Callers should treat 'keyKeepAliveFailed' as "drop the WS
+ *  and restart from scratch" — the current key is presumed dead. */
+export type ListenKeyEvents = {
+    /** Fresh key minted via POST /fapi/v1/listenKey. Fires on start() and
+     *  after every successful re-mint. */
+    keyMinted: (listenKey: string) => void;
+    /** A keep-alive (PUT) succeeded. Informational — mostly for observability. */
+    keyRefreshed: () => void;
+    /** Consecutive keep-alive failures reached `maxConsecutiveFailures`. The
+     *  parent should treat the stream as dead and reconnect from scratch. */
+    keyKeepAliveFailed: (reason: string) => void;
+};
+/** Lightweight typed emitter — EventEmitter with a phantom type. */
+export declare class ListenKeyManager extends EventEmitter {
+    private readonly api;
+    private readonly refreshIntervalMs;
+    private readonly maxConsecutiveFailures;
+    private readonly timers;
+    private currentKey;
+    private keyMintedAt;
+    private refreshTimer;
+    private consecutiveFailures;
+    private running;
+    constructor(api: BinancePrivateApi, options?: ListenKeyManagerOptions);
+    /** Mint a listenKey and start the refresh loop. Returns the minted key.
+     *  Throws if the first POST fails — caller decides how to back off. */
+    start(): Promise<string>;
+    /** Stop the refresh loop and best-effort close the key. Idempotent.
+     *  For GRACEFUL shutdown only — a reconnect-driven teardown must use
+     *  `stopKeepAlive()` instead (see below). */
+    stop(): Promise<void>;
+    /** Stop the refresh loop WITHOUT the DELETE — for reconnect-driven closes.
+     *  Binance returns the SAME active listenKey on a re-POST and merely
+     *  extends its validity (doc-verified 2026-07-02: "Doing a POST on an
+     *  account with an active listenKey will return the currently active
+     *  listenKey and extend its validity for 60 minutes"), so an in-flight
+     *  DELETE racing the reconnect's POST can land AFTER it and invalidate the
+     *  key the fresh socket just authenticated with — a silent dead stream.
+     *  Skipping the DELETE is safe: an unused key expires on its own after
+     *  60 min of no keep-alive. Synchronous + idempotent. */
+    stopKeepAlive(): void;
+    /** Current listenKey, or null if stopped. */
+    getKey(): string | null;
+    /** Age in ms since the key was last minted. Null if stopped. Useful for
+     *  observability dashboards — a key far beyond refreshIntervalMs but still
+     *  alive means Binance is tolerating us past the nominal window. */
+    getKeyAge(): number | null;
+    /** Number of consecutive failed keep-alive probes. Exposed for diagnostics. */
+    getConsecutiveFailures(): number;
+    private scheduleRefresh;
+    private refresh;
+}