@reefclaw/openclaw-plugin 0.1.0

package/ccxt/binance-private.d.ts

@@ -0,0 +1,325 @@
+import type { CcxtOrder, CcxtBalance, CcxtPosition, CcxtTicker, ExchangeConfig } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+/** Result of API permission validation. */
+export interface PermissionCheckResult {
+    canReadBalance: boolean;
+    canReadPositions: boolean;
+    canTrade: boolean;
+    errors: string[];
+}
+export declare class BinancePrivateApi {
+    private exchange;
+    private testnet;
+    constructor(credentials: ExchangeConfig);
+    /**
+     * Validate API key permissions by making test API calls.
+     * Best-effort — never throws.
+     */
+    validatePermissions(): Promise<PermissionCheckResult>;
+    /** Fetch real account balance. Returns null on error. */
+    fetchBalance(): Promise<CcxtBalance | 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.
+     */
+    fetchTransfers(startMs: number, endMs: number): Promise<Array<{
+        tranId: string;
+        time: number;
+        amount: number;
+        asset: string;
+    }>>;
+    /**
+     * 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
+     */
+    fetchRealizedPnlSince(sinceMs: number): Promise<number | 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
+     */
+    fetchTodayIncomeBreakdown(sinceMs: number, opts?: {
+        forced?: boolean;
+    }): Promise<{
+        realizedPnlGross: number;
+        netNonTransfer: number;
+    } | 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
+     */
+    fetchRecentTradedSymbols(sinceMs: number): Promise<string[]>;
+    /** Fetch real open positions. Returns null on error. */
+    fetchPositions(symbol?: string): Promise<CcxtPosition[] | 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`. */
+    fetchOpenOrders(symbol?: string): Promise<CcxtOrder[] | 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. */
+    private fetchOpenAlgoOrders;
+    /** 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. */
+    queryAlgoOrderStatus(clientAlgoId: string): Promise<string | 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 */
+    fetchMyTrades(symbol: string, since?: number, limit?: number, opts?: {
+        endTime?: number;
+    }): Promise<any[]>;
+    /** 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. */
+    fetchMyTradesOrNull(symbol: string, since?: number, limit?: number, opts?: {
+        endTime?: number;
+        fromId?: number;
+    }): Promise<any[] | null>;
+    /** Fetch order book depth (same data as public, validates auth path). */
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    /** Fetch ticker. Returns null on error. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | 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).
+     */
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, params?: Record<string, any>): Promise<CcxtOrder>;
+    /** Fetch a single order by ID. Used for fill polling and idempotency checks. */
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    /**
+     * Fetch a single order by clientOrderId. Used for idempotency recovery
+     * after network timeouts — check if the order went through before retrying.
+     */
+    fetchOrderByClientId(clientOrderId: string, symbol: string): Promise<CcxtOrder | 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. */
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    private normalizeCanceledOrder;
+    private fabricateCanceledOrder;
+    /**
+     * 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.
+     */
+    createBracketOrder(symbol: string, type: 'STOP_MARKET' | 'TAKE_PROFIT_MARKET', side: 'buy' | 'sell', amount: number, params: Record<string, any>): Promise<CcxtOrder>;
+    /**
+     * 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. */
+    private logAlgoCancelChokepoint;
+    cancelOrderByClientId(clientOrderId: string, symbol: string): Promise<void>;
+    /** 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. */
+    cancelAllOrders(symbol?: string): Promise<void>;
+    /** 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. */
+    disableCountdownCancelAll(symbol: string): Promise<void>;
+    /** 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: string): string;
+    /** 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. */
+    createListenKey(): Promise<string>;
+    /** 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. */
+    keepAliveListenKey(): Promise<void>;
+    /** 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. */
+    closeListenKey(): Promise<void>;
+    /** Whether this instance is connected to testnet. */
+    isTestnet(): boolean;
+    /** Get the underlying CCXT exchange instance (for loadMarkets, position mode detection, etc.). */
+    getExchange(): any;
+    /**
+     * 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(): Record<string, string>;
+}