@nemesis-oss/binance-sdk 1.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,318 +1,1945 @@
-import { F as FuturesMarket, B as BinanceClient } from './index-D2T_Rhwj.js';
-export { A as Account, a as AccountAsset, b as AccountAssetSchema, c as AccountPosition, d as AccountPositionSchema, e as AccountSchema, f as AggTrade, g as AggTradeSchema, h as AggTradesResponseSchema, i as AlgoOrder, j as AlgoOrderResponseSchema, k as AlgoOrderSchema, l as AlgoOrdersResponseSchema, m as ApiTradingStatus, n as ApiTradingStatusSchema, o as AuthMode, p as AvgPrice, q as AvgPriceSchema, r as Balance, s as BalanceSchema, t as BalancesResponseSchema, u as BaseWS, v as BaseWSOptions, w as BatchOrdersItem, x as BatchOrdersItemSchema, y as BatchOrdersResponseSchema, z as BinanceClientOptions, C as BookTicker, D as BookTickerSchema, E as BracketOrderParams, G as ClosePositionParams, H as CommissionRate, I as CommissionRateSchema, J as ContractType, K as CountdownCancelAll, L as CountdownCancelAllSchema, M as CreateOrderParams, N as CreateOrderParamsSchema, O as DepthSnapshot, P as DepthSnapshotSchema, Q as ExchangeInfo, R as ExchangeInfoSchema, S as ExchangeSymbol, T as ExchangeSymbolSchema, U as FeeBurnStatus, V as FeeBurnStatusSchema, W as FundingRate, X as FundingRateHistorySchema, Y as FundingRateSchema, Z as FuturesAccount, _ as FuturesData, $ as FuturesDataEndpoints, a0 as FuturesMarketWS, a1 as FuturesOps, a2 as FuturesToolkit, a3 as FuturesTrading, a4 as FuturesUserWS, a5 as FuturesUserWSOptions, a6 as HttpClient, a7 as HttpClientOptions, a8 as HttpMethod, a9 as Income, aa as IncomeHistoryResponseSchema, ab as IncomeSchema, ac as Kline, ad as KlineInterval, ae as KlineIntervalSchema, af as KlineSchema, ag as KlinesResponseSchema, ah as LeverageBracket, ai as LeverageBracketResponseSchema, aj as LeverageBracketSchema, ak as LeverageChange, al as LeverageChangeSchema, am as ListenKey, an as ListenKeySchema, ao as LongShortRatioEntry, ap as LongShortRatioEntrySchema, aq as LongShortRatioSchema, ar as MarginTypeChange, as as MarginTypeChangeSchema, at as MarkPriceSpeed, au as MarketDataBase, av as ModifyOrderParams, aw as ModifyOrderParamsSchema, ax as MultiAssetsMargin, ay as MultiAssetsMarginSchema, az as NewOrderAck, aA as NewOrderAckSchema, aB as OpenInterest, aC as OpenInterestHistEntry, aD as OpenInterestHistEntrySchema, aE as OpenInterestHistSchema, aF as OpenInterestSchema, aG as Order, aH as OrderModifyHistoryEntry, aI as OrderModifyHistoryEntrySchema, aJ as OrderModifyHistorySchema, aK as OrderResponseSchema, aL as OrderSchema, aM as OrdersResponseSchema, aN as PositionMarginChange, aO as PositionMarginChangeSchema, aP as PositionMarginHistoryEntry, aQ as PositionMarginHistoryEntrySchema, aR as PositionMarginHistorySchema, aS as PositionMode, aT as PositionModeSchema, aU as PositionRisk, aV as PositionRiskResponseSchema, aW as PositionRiskSchema, aX as PositionSizing, aY as PremiumIndex, aZ as PremiumIndexSchema, a_ as RateLimitOrder, a$ as RateLimitOrderResponseSchema, b0 as RateLimitOrderSchema, b1 as SizePositionParams, b2 as SpotAccount, b3 as SpotAccountInfo, b4 as SpotAccountSchema, b5 as SpotBalance, b6 as SpotBalanceSchema, b7 as SpotBalanceUpdate, b8 as SpotBalanceUpdateSchema, b9 as SpotExecutionReport, ba as SpotExecutionReportSchema, bb as SpotListStatus, bc as SpotListStatusSchema, bd as SpotMarket, be as SpotMarketWS, bf as SpotOCOOrderAck, bg as SpotOCOOrderAckResponseSchema, bh as SpotOCOOrderAckSchema, bi as SpotOCOOrdersResponseSchema, bj as SpotOrder, bk as SpotOrderResponseSchema, bl as SpotOrderSchema, bm as SpotOrdersResponseSchema, bn as SpotOutboundAccountPosition, bo as SpotOutboundAccountPositionSchema, bp as SpotTrade, bq as SpotTradeSchema, br as SpotTradesResponseSchema, bs as SpotTrading, bt as SpotUserDataEvent, bu as SpotUserDataStream, bv as SpotUserWS, bw as SpotUserWSOptions, bx as SymbolRules, by as TakerLongShortRatioEntry, bz as TakerLongShortRatioEntrySchema, bA as TakerLongShortRatioSchema, bB as Ticker24hr, bC as Ticker24hrSchema, bD as TickerPrice, bE as TickerPriceSchema, bF as ToolContext, bG as ToolDefinition, bH as Trade, bI as TradeSchema, bJ as TradesResponseSchema, bK as UserDataAccountUpdate, bL as UserDataAccountUpdateSchema, bM as UserDataEvent, bN as UserDataMarginCall, bO as UserDataMarginCallSchema, bP as UserDataOrderTradeUpdate, bQ as UserDataOrderTradeUpdateSchema, bR as UserDataStream, bS as UserTrade, bT as UserTradeSchema, bU as UserTradesResponseSchema, bV as WsApi, bW as WsApiOptions, bX as WsApiResponse, bY as WsApiResponseSchema, bZ as accountTools, b_ as createFuturesToolkit, b$ as createPaperContext, c0 as derivedTools, c1 as floorToStep, c2 as formatToDecimals, c3 as getBufferedWsEvents, c4 as marketDataTools, c5 as paperTools, c6 as parseSpotUserDataEvent, c7 as parseUserDataEvent, c8 as roundToStep, c9 as spotTools, ca as stepDecimals, cb as symbolRulesFrom, cc as textResult, cd as toAnthropicTool, ce as toJsonSchema, cf as toMCPTool, cg as toOpenAITool, ch as toToolList, ci as toolkitToFormats, cj as tradingTools, ck as wsTools } from './index-D2T_Rhwj.js';
-import { z } from 'zod';
+import { B as BinanceClient, a as BinanceClientOptions, C as CoreContext, E as ExecutionAdapter, P as PaperTradingEngine, b as CreateOrderParams, O as OrderKey, c as OrderShape, U as UserStreamLike, d as ExecutionReportShape, e as ExecutionFill, f as EventBus, W as WsConnection, g as WsConnectionOptions, h as ExecutionManager, i as BookLevel, j as OrderBookMetrics, D as DiffInput, k as BookSnapshotInput, l as UsdmSurface, S as SpotSurface, m as CoinMSurface, n as WsFamily, R as ReconnectPolicy, F as FuturesMarketWS, o as SpotMarketWS, p as CoinMMarketWS, q as WsConnectionStats, r as SubscribeOptions, s as Subscription, t as PaperTradingOptions, u as FuturesToolkitOptions } from './index-C06A22Dz.js';
+export { A as Account, v as AccountAsset, w as AccountAssetSchema, x as AccountPosition, y as AccountPositionSchema, z as AccountSchema, G as AccountSnapshot, H as AccountSnapshotSchema, I as AggTrade, J as AggTradeSchema, K as AggTradesResponseSchema, L as AlgoOrder, M as AlgoOrderResponseSchema, N as AlgoOrderSchema, Q as AlgoOrdersResponseSchema, T as ApiKeyPermissions, V as ApiKeyPermissionsSchema, X as ApiTradingStatus, Y as ApiTradingStatusSchema, Z as AssetDetail, _ as AssetDetailSchema, $ as AuditAction, a0 as AuditOutcome, a1 as AuditRecord, a2 as AuditSink, a3 as AuthMode, a4 as AvgPrice, a5 as AvgPriceSchema, a6 as Balance, a7 as BalanceSchema, a8 as BalancesResponseSchema, a9 as BaseWS, aa as BaseWSOptions, ab as BatchOrdersItem, ac as BatchOrdersItemSchema, ad as BatchOrdersResponseSchema, ae as BinanceUsdmFeeModel, af as BookTicker, ag as BookTickerSchema, ah as BookView, ai as BorrowRepayParams, aj as BorrowRepayParamsSchema, ak as BorrowRepayRecordEntry, al as BorrowRepayRecordEntrySchema, am as BorrowRepayRecordResponse, an as BorrowRepayRecordResponseSchema, ao as BorrowRepayResult, ap as BorrowRepayResultSchema, aq as BracketOrderParams, ar as CircuitBreakerState, as as ClosePositionParams, at as CoinMAccount, au as CoinMAccountAsset, av as CoinMAccountAssetSchema, aw as CoinMAccountInfo, ax as CoinMAccountPosition, ay as CoinMAccountPositionSchema, az as CoinMAccountSchema, aA as CoinMBalance, aB as CoinMBalanceResponseSchema, aC as CoinMBalanceSchema, aD as CoinMCommissionRate, aE as CoinMCommissionRateSchema, aF as CoinMContractType, aG as CoinMCreateOrderParams, aH as CoinMCreateOrderParamsSchema, aI as CoinMIncome, aJ as CoinMIncomeHistoryResponseSchema, aK as CoinMIncomeSchema, aL as CoinMLeverageBracket, aM as CoinMLeverageBracketResponseSchema, aN as CoinMLeverageBracketSchema, aO as CoinMLeverageChange, aP as CoinMLeverageChangeSchema, aQ as CoinMMarginTypeChange, aR as CoinMMarginTypeChangeSchema, aS as CoinMMarkPriceSpeed, aT as CoinMMarket, aU as CoinMOpenInterestHistEntry, aV as CoinMOpenInterestHistEntrySchema, aW as CoinMOpenInterestHistSchema, aX as CoinMOrder, aY as CoinMOrderResponseSchema, aZ as CoinMOrderSchema, a_ as CoinMOrdersResponseSchema, a$ as CoinMPositionMarginChange, b0 as CoinMPositionMarginChangeSchema, b1 as CoinMPositionMode, b2 as CoinMPositionModeSchema, b3 as CoinMPositionRisk, b4 as CoinMPositionRiskResponseSchema, b5 as CoinMPositionRiskSchema, b6 as CoinMTrading, b7 as CoinMUserDataStream, b8 as CoinMUserTrade, b9 as CoinMUserTradeSchema, ba as CoinMUserTradesResponseSchema, bb as CoinMUserWS, bc as CoinMUserWSOptions, bd as CommissionRate, be as CommissionRateSchema, bf as CompositeModel, bg as ContractType, bh as CoreTransportOptions, bi as CountdownCancelAll, bj as CountdownCancelAllSchema, bk as CreateOrderParamsSchema, bl as Credentials, bm as CrossMarginAccount, bn as CrossMarginAccountSchema, bo as Decimal, bp as DecimalInput, bq as DepositAddress, br as DepositAddressSchema, bs as DepositHistoryEntry, bt as DepositHistoryEntrySchema, bu as DepositHistoryResponseSchema, bv as DepthSnapshot, bw as DepthSnapshotSchema, bx as DustConversionResult, by as DustConversionResultSchema, bz as DustLogEntry, bA as DustLogEntrySchema, bB as DustLogResponse, bC as DustLogResponseSchema, bD as Endpoints, bE as Environment, bF as EventBusOptions, bG as ExchangeInfo, bH as ExchangeInfoSchema, bI as ExchangeSymbol, bJ as ExchangeSymbolSchema, bK as Execution, bL as ExecutionBackend, bM as ExecutionContext, bN as ExecutionGateway, bO as ExecutionGatewayOptions, bP as ExecutionManagerOptions, bQ as ExecutionModel, bR as ExecutionQuote, bS as ExecutionUnknownError, bT as FanOutAuditSink, bU as FeeBurnStatus, bV as FeeBurnStatusSchema, bW as FeeModel, bX as FeeQuote, bY as FundingAsset, bZ as FundingAssetSchema, b_ as FundingAssetsResponseSchema, b$ as FundingRate, c0 as FundingRateHistorySchema, c1 as FundingRateSchema, c2 as FuturesAccount, c3 as FuturesData, c4 as FuturesDataEndpoints, c5 as FuturesExecutionAdapter, c6 as FuturesMarket, c7 as FuturesNamespace, c8 as FuturesOps, c9 as FuturesToolkit, ca as FuturesTrading, cb as FuturesUserWS, cc as FuturesUserWSOptions, cd as FuturesWsApiClient, ce as HttpClient, cf as HttpClientOptions, cg as HttpMethod, ch as InMemoryAuditSink, ci as Income, cj as IncomeHistoryResponseSchema, ck as IncomeSchema, cl as InstantFillModel, cm as IsolatedMarginAccount, cn as IsolatedMarginAccountSchema, co as IsolatedMarginAsset, cp as IsolatedMarginAssetSchema, cq as IsolatedMarginSymbol, cr as IsolatedMarginSymbolSchema, cs as IsolatedTransferParams, ct as IsolatedTransferParamsSchema, cu as Kline, cv as KlineInterval, cw as KlineIntervalSchema, cx as KlineSchema, cy as KlinesResponseSchema, cz as LatencyModel, cA as LeverageBracket, cB as LeverageBracketResponseSchema, cC as LeverageBracketSchema, cD as LeverageChange, cE as LeverageChangeSchema, cF as ListenKey, cG as ListenKeySchema, cH as LongShortRatioEntry, cI as LongShortRatioEntrySchema, cJ as LongShortRatioSchema, cK as MarginAccount, cL as MarginAssetBalance, cM as MarginAssetBalanceSchema, cN as MarginCreateOrderParams, cO as MarginCreateOrderParamsSchema, cP as MarginForceLiquidationEntry, cQ as MarginForceLiquidationEntrySchema, cR as MarginForceLiquidationResponse, cS as MarginForceLiquidationResponseSchema, cT as MarginInterestHistoryEntry, cU as MarginInterestHistoryEntrySchema, cV as MarginInterestHistoryResponse, cW as MarginInterestHistoryResponseSchema, cX as MarginNamespace, cY as MarginOrder, cZ as MarginOrderResponseSchema, c_ as MarginOrderSchema, c$ as MarginOrdersResponseSchema, d0 as MarginPriceIndex, d1 as MarginPriceIndexSchema, d2 as MarginTrade, d3 as MarginTradeSchema, d4 as MarginTradesResponseSchema, d5 as MarginTrading, d6 as MarginTransferResult, d7 as MarginTransferResultSchema, d8 as MarginTypeChange, d9 as MarginTypeChangeSchema, da as MarkPriceSpeed, db as MarketDataBase, dc as MaxBorrowable, dd as MaxBorrowableSchema, de as MaxTransferable, df as MaxTransferableSchema, dg as ModifyOrderParams, dh as ModifyOrderParamsSchema, di as MultiAssetsMargin, dj as MultiAssetsMarginSchema, dk as NewOrderAck, dl as NewOrderAckSchema, dm as OpenInterest, dn as OpenInterestHistEntry, dp as OpenInterestHistEntrySchema, dq as OpenInterestHistSchema, dr as OpenInterestSchema, ds as Order, dt as OrderBook, du as OrderBookEngine, dv as OrderBookEngineOptions, dw as OrderBookModel, dx as OrderModifyHistoryEntry, dy as OrderModifyHistoryEntrySchema, dz as OrderModifyHistorySchema, dA as OrderResponseSchema, dB as OrderSchema, dC as OrdersResponseSchema, dD as PaperAccount, dE as PaperOrder, dF as PaperPosition, dG as PaperPositionSide, dH as PartialFillModel, dI as PositionMarginChange, dJ as PositionMarginChangeSchema, dK as PositionMarginHistoryEntry, dL as PositionMarginHistoryEntrySchema, dM as PositionMarginHistorySchema, dN as PositionMode, dO as PositionModeSchema, dP as PositionRisk, dQ as PositionRiskResponseSchema, dR as PositionRiskSchema, dS as PositionSizing, dT as PremiumIndex, dU as PremiumIndexSchema, dV as RateLimitOrder, dW as RateLimitOrderResponseSchema, dX as RateLimitOrderSchema, dY as RateLimitTracker, dZ as RateLimitTrackerOptions, d_ as RateLimitUsage, d$ as RawLevel, e0 as ReconciliationState, e1 as RestHost, e2 as RetryPolicy, e3 as RiskGateway, e4 as RiskGatewayOptions, e5 as RiskStatus, e6 as SdkEvent, e7 as SdkEventListener, e8 as SdkLogger, e9 as SignatureAlgorithm, ea as Signer, eb as SignerOptions, ec as SizePositionParams, ed as SlippageModel, ee as SpotAccount, ef as SpotAccountInfo, eg as SpotAccountSchema, eh as SpotBalance, ei as SpotBalanceSchema, ej as SpotBalanceUpdate, ek as SpotBalanceUpdateSchema, el as SpotExecutionAdapter, em as SpotExecutionReport, en as SpotExecutionReportSchema, eo as SpotListStatus, ep as SpotListStatusSchema, eq as SpotMarket, er as SpotOCOOrderAck, es as SpotOCOOrderAckResponseSchema, et as SpotOCOOrderAckSchema, eu as SpotOCOOrdersResponseSchema, ev as SpotOrder, ew as SpotOrderResponseSchema, ex as SpotOrderSchema, ey as SpotOrdersResponseSchema, ez as SpotOutboundAccountPosition, eA as SpotOutboundAccountPositionSchema, eB as SpotTrade, eC as SpotTradeSchema, eD as SpotTradesResponseSchema, eE as SpotTrading, eF as SpotUserDataEvent, eG as SpotUserDataStream, eH as SpotUserWS, eI as SpotUserWSOptions, eJ as SpotWsApi, eK as SpotWsApiClient, eL as SpotWsApiOptions, eM as StreamAuditSink, eN as SubAccount, eO as SubAccountDepositAddress, eP as SubAccountDepositAddressSchema, eQ as SubAccountDepositHistoryEntry, eR as SubAccountDepositHistoryEntrySchema, eS as SubAccountDepositHistoryResponseSchema, eT as SubAccountEnableResult, eU as SubAccountEnableResultSchema, eV as SubAccountEntry, eW as SubAccountEntrySchema, eX as SubAccountFuturesSummary, eY as SubAccountFuturesSummarySchema, eZ as SubAccountListResponse, e_ as SubAccountListResponseSchema, e$ as SubAccountMarginAccount, f0 as SubAccountMarginAccountSchema, f1 as SubAccountSpotAsset, f2 as SubAccountSpotAssetSchema, f3 as SubAccountSpotAssetsResponse, f4 as SubAccountSpotAssetsResponseSchema, f5 as SubAccountSpotSummary, f6 as SubAccountSpotSummaryEntry, f7 as SubAccountSpotSummaryEntrySchema, f8 as SubAccountSpotSummarySchema, f9 as SubAccountStatus, fa as SubAccountStatusResponseSchema, fb as SubAccountStatusSchema, fc as SubAccountUniversalTransferEntry, fd as SubAccountUniversalTransferEntrySchema, fe as SubAccountUniversalTransferHistoryResponse, ff as SubAccountUniversalTransferHistoryResponseSchema, fg as SubAccountUniversalTransferParams, fh as SubAccountUniversalTransferParamsSchema, fi as SubAccountUniversalTransferResult, fj as SubAccountUniversalTransferResultSchema, fk as SubscriptionState, fl as SymbolRules, fm as TakerLongShortRatioEntry, fn as TakerLongShortRatioEntrySchema, fo as TakerLongShortRatioSchema, fp as TakerMakerFeeModel, fq as Ticker24hr, fr as Ticker24hrSchema, fs as TickerPrice, ft as TickerPriceSchema, fu as ToolContext, fv as ToolDefinition, fw as Trade, fx as TradeFeeEntry, fy as TradeFeeEntrySchema, fz as TradeFeeResponseSchema, fA as TradeSchema, fB as TradesResponseSchema, fC as TradingPolicy, fD as TradingPolicyOptions, fE as TransferType, fF as TransferTypeSchema, fG as UniversalTransferHistoryEntry, fH as UniversalTransferHistoryEntrySchema, fI as UniversalTransferHistoryResponse, fJ as UniversalTransferHistoryResponseSchema, fK as UniversalTransferParams, fL as UniversalTransferParamsSchema, fM as UniversalTransferResult, fN as UniversalTransferResultSchema, fO as UserAsset, fP as UserAssetSchema, fQ as UserAssetsResponseSchema, fR as UserDataAccountUpdate, fS as UserDataAccountUpdateSchema, fT as UserDataEvent, fU as UserDataMarginCall, fV as UserDataMarginCallSchema, fW as UserDataOrderTradeUpdate, fX as UserDataOrderTradeUpdateSchema, fY as UserDataStream, fZ as UserTrade, f_ as UserTradeSchema, f$ as UserTradesResponseSchema, g0 as VirtualSubAccountResult, g1 as VirtualSubAccountResultSchema, g2 as WS_FAMILY_LIMITS, g3 as WS_PLATFORM_DEFAULTS, g4 as Wallet, g5 as WithdrawHistoryEntry, g6 as WithdrawHistoryEntrySchema, g7 as WithdrawHistoryResponseSchema, g8 as WithdrawParams, g9 as WithdrawParamsSchema, ga as WithdrawResult, gb as WithdrawResultSchema, gc as WsAggTradePayload, gd as WsAggTradePayloadSchema, ge as WsApi, gf as WsApiClient, gg as WsApiClientOptions, gh as WsApiClientState, gi as WsApiOptions, gj as WsApiResponse, gk as WsApiResponseSchema, gl as WsApiSurface, gm as WsAssetIndexPayload, gn as WsAssetIndexPayloadSchema, go as WsBookTickerPayload, gp as WsBookTickerPayloadSchema, gq as WsCompositeIndexPayload, gr as WsCompositeIndexPayloadSchema, gs as WsConnectionState, gt as WsDepthUpdatePayload, gu as WsDepthUpdatePayloadSchema, gv as WsFamilyLimits, gw as WsFamilyStreams, gx as WsForceOrderPayload, gy as WsForceOrderPayloadSchema, gz as WsKlinePayload, gA as WsKlinePayloadSchema, gB as WsMarkPricePayload, gC as WsMarkPricePayloadSchema, gD as WsMiniTickerPayload, gE as WsMiniTickerPayloadSchema, gF as WsPlatform, gG as WsPlatformOptions, gH as WsPlatformStats, gI as WsRequestOptions, gJ as WsRollingWindowTickerPayload, gK as WsRollingWindowTickerPayloadSchema, gL as WsSpotAvgPricePayload, gM as WsSpotAvgPricePayloadSchema, gN as WsStreamPayload, gO as WsTicker24hrPayload, gP as WsTicker24hrPayloadSchema, gQ as WsTradePayload, gR as WsTradePayloadSchema, gS as accountTools, gT as auditRecordFromExecution, gU as createFuturesToolkit, gV as createPaperContext, gW as createWsPlatform, gX as dec, gY as derivedTools, gZ as executionTools, g_ as familyLimits, g$ as floorToStep, h0 as formatToDecimals, h1 as forwardEventsToLogger, h2 as getBufferedWsEvents, h3 as isExecutionAdapter, h4 as marketDataTools, h5 as paperTools, h6 as parseSpotUserDataEvent, h7 as parseUserDataEvent, h8 as parseWsPayload, h9 as resolveEnvironment, ha as roundToStep, hb as spotTools, hc as stepDecimals, hd as sum, he as symbolRulesFrom, hf as textResult, hg as toAnthropicTool, hh as toJsonSchema, hi as toMCPTool, hj as toOpenAITool, hk as toToolList, hl as toolkitToFormats, hm as tradingTools, hn as vwap, ho as wsTools } from './index-C06A22Dz.js';
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import 'node:events';
-
-type Environment = 'live' | 'testnet' | 'demo';
-interface Endpoints {
-    restRoot: string;
-    restFapi: string;
-    restFuturesData: string;
-    restSpot: string;
-    wsMarket: string;
-    wsUser: string;
-    wsApi: string;
-    wsSpotMarket: string;
-    wsSpotUser: string;
-}
-declare function resolveEnvironment(options?: {
-    testnet?: boolean;
-    demo?: boolean;
-    apiBase?: string;
-    wsBase?: string;
-    wsUserBase?: string;
-    wsApiBase?: string;
-}): {
-    env: Environment;
-    endpoints: Endpoints;
+import 'axios';
+import 'zod';
+
+/**
+ * Single source of truth for the package version string.
+ *
+ * Read by:
+ *  - {@link ./index.js} — re-exports as the public `VERSION` constant.
+ *  - {@link ../mcp/server.js} — the MCP server identifies itself with this
+ *    value when negotiating with hosts (was previously hard-coded as
+ *    `'2.0.0'`, which drifted from `package.json`).
+ *
+ * Update in lockstep with the `version` field in `package.json` and the
+ * `[Unreleased]` / latest release section in `CHANGELOG.md`.
+ */
+declare const VERSION = "3.0.0";
+
+/**
+ * Standalone product clients.
+ *
+ * `BinanceClient` is the full multi-product surface; these factories give
+ * focused callers just their product plus the shared lifecycle helpers
+ * (`syncTime`, `close`), constructed from the same client underneath — no
+ * duplicated wiring, no divergent behavior:
+ *
+ * ```ts
+ * import { createSpotClient, createUSDMClient } from '@nemesis-oss/binance-sdk';
+ *
+ * const spot = createSpotClient({ apiKey, apiSecret });
+ * await spot.syncTime();
+ * const books = await spot.market.depth('BTCUSDT', 20);
+ * spot.close();
+ *
+ * const usdm = createUSDMClient({ apiKey, apiSecret });
+ * await usdm.execution.placeOrder({ symbol: 'BTCUSDT', ... });
+ * ```
+ */
+/** The spot product surface plus shared lifecycle helpers. */
+type SpotClient$1 = BinanceClient['spot'] & {
+    /** Sync local clocks against every REST host (mitigates -1021). */
+    syncTime(): Promise<void>;
+    /** Close all websockets and user streams created for this client. */
+    close(): void;
+    /** Rate-limit usage snapshots, per REST host. */
+    getRateLimitUsage(): ReturnType<BinanceClient['getRateLimitUsage']>;
 };
+/** The USDⓈ-M futures product surface plus shared lifecycle helpers. */
+type USDMClient$1 = BinanceClient['futures'] & {
+    syncTime(): Promise<void>;
+    close(): void;
+    getRateLimitUsage(): ReturnType<BinanceClient['getRateLimitUsage']>;
+};
+/** The COIN-M futures product surface plus shared lifecycle helpers. */
+type CoinMClient$1 = BinanceClient['coinm'] & {
+    syncTime(): Promise<void>;
+    close(): void;
+    getRateLimitUsage(): ReturnType<BinanceClient['getRateLimitUsage']>;
+};
+/** A spot-only client (market, account, trading, execution, ws, wsApi). */
+declare function createSpotClient(options?: BinanceClientOptions): SpotClient$1;
+/** A USDⓈ-M futures-only client (market, data, account, trading, ops, execution, ws, wsApi). */
+declare function createUSDMClient(options?: BinanceClientOptions): USDMClient$1;
+/** A COIN-M futures-only client (market, account, trading, ws). */
+declare function createCoinMClient(options?: BinanceClientOptions): CoinMClient$1;
+
+/**
+ * Lossless JSON parsing for Binance payloads.
+ *
+ * `JSON.parse` coerces every integer to a JS double, silently corrupting values
+ * above Number.MAX_SAFE_INTEGER (2^53 - 1). Binance identifiers (orderId,
+ * tradeId, updateId, transaction IDs) are the classic casualties: two distinct
+ * exchange IDs can compare equal after parsing.
+ *
+ * `parseJsonLossless` pre-passes the raw text and quotes any integer literal
+ * whose magnitude exceeds the safe range, so oversized IDs surface as decimal
+ * *strings* instead of silently-corrupted numbers. Values within the safe range
+ * keep their original type, which keeps all existing Zod schemas valid.
+ */
+declare function parseJsonLossless(text: string): unknown;
+/** Type-safe wrapper for callers that know the payload shape. */
+declare function parseJsonLosslessAs<T>(text: string): T;
+/**
+ * Deep-walks a parsed payload converting long integer *strings* back into
+ * numbers only when they are safe — useful when the caller wants uniform
+ * `number` types for fields that are practically always small.
+ */
+declare function normalizeIntStrings<T>(value: T): T;
+
+/**
+ * Product identifiers — the canonical set v3 namespaces address. Grows as
+ * products are migrated onto the platform (Options, Portfolio Margin, …).
+ */
+type ProductId = 'spot' | 'usdm' | 'coinm' | 'margin' | 'wallet' | 'subaccount' | 'convert';
+/**
+ * v3 product boundary.
+ *
+ * A product client is anything constructed from a shared {@link CoreContext}
+ * that owns its product's surface. The contract is deliberately tiny —
+ * products differ wildly in surface, but every one of them:
+ *
+ *  - declares its `product` id (routing key for the contract catalog,
+ *    observability dimensions, and coverage accounting);
+ *  - carries the core context it was built from (so callers can reach the
+ *    shared transports, credentials and events without globals);
+ *  - closes the product's own resources (websockets, listen-key timers).
+ *
+ * The raw API layer (`client.futures.usdm.trading.createOrder`) and the
+ * domain execution layer (`client.futures.usdm.execution.placeOrder`) both
+ * live inside product clients — API fidelity and trading infrastructure are
+ * siblings, not alternatives.
+ */
+interface ProductClient {
+    /** Canonical product id ('usdm', 'spot', …). */
+    readonly product: ProductId;
+    /** The shared runtime this product was constructed from. */
+    readonly core: CoreContext;
+    /**
+     * Close this product's resources (WS connections, keep-alive timers).
+     * Safe to call more than once.
+     */
+    close(): void;
+}
+/**
+ * Factory signature for lazy product construction on a multi-product
+ * facade: receives the shared context, returns the cached product surface.
+ */
+type ProductFactory<T> = (core: CoreContext) => T;
+/** True when a value satisfies the v3 product boundary. */
+declare function isProductClient(value: unknown): value is ProductClient;
+
+/**
+ * Paper execution backend: routes orders through the local
+ * {@link PaperTradingEngine} simulator instead of the exchange, behind the
+ * exact same {@link ExecutionAdapter} interface the live products use.
+ *
+ * The point is *identical semantics*: `placeOrder` returns the same
+ * `Execution` envelope, `reconcile()` runs the same matrix, fetches of
+ * unknown orders fail with the same `-2013` Binance error the exchange would
+ * return, and fills stream in as execution reports just like a user-data
+ * stream would deliver them. Code written against the paper backend can be
+ * switched to live by changing one configuration value.
+ *
+ * The simulator fills instantly (per its execution model), so:
+ *  - `createOrder` resolves with the fill already booked;
+ *  - `fetchOrder` replays the stored record (reconciliation succeeds);
+ *  - `cancelOrder` mirrors the exchange's `-2011` for orders no longer on
+ *    the book, which the ExecutionManager reconciles into a terminal
+ *    CANCELED execution — the same path live takes.
+ */
+declare class PaperExecutionAdapter implements ExecutionAdapter {
+    private readonly engine;
+    private readonly options;
+    readonly product = "paper";
+    /** clientOrderId → raw order record, the simulator's "matching engine" view. */
+    private readonly orders;
+    /**
+     * Report listeners. Paper backends routinely have several consumers — the
+     * execution manager's ledger *and* (v3) the platform's paper session that
+     * translates fills into user-stream frames — so `onReport` fans out to
+     * every registered listener instead of replacing the previous one.
+     */
+    private readonly reportHandlers;
+    constructor(engine: PaperTradingEngine, options?: {
+        commissionAsset?: string;
+    });
+    /** The underlying simulator (account, positions, order history). */
+    get simulator(): PaperTradingEngine;
+    createOrder(submission: CreateOrderParams): Promise<Record<string, unknown>>;
+    fetchOrder(symbol: string, key: OrderKey): Promise<Record<string, unknown>>;
+    /**
+     * Every order record the simulator holds, client-order-id keyed — the
+     * authoritative "REST view" a paper-mode reconciliation pass folds into the
+     * v3 platform's order tracker (live reconciliation reads `/openOrders`).
+     */
+    listOrderRecords(): Record<string, unknown>[];
+    cancelOrder(symbol: string, key: OrderKey): Promise<Record<string, unknown>>;
+    toOrderShape(raw: Record<string, unknown>): OrderShape;
+    /** Paper has no user-data stream; attach is a no-op. */
+    setUserStream(_ws: UserStreamLike | null): void;
+    /** Register a report listener; every listener fires for every fill (additive). */
+    onReport(handler: (report: ExecutionReportShape) => void): void;
+}
 
-type PaperPositionSide = 'LONG' | 'SHORT' | 'NONE';
-interface PaperPosition {
+/**
+ * v3 execution platform — shared domain types.
+ *
+ * Milestone 3 turns execution from a per-call concern into a platform: the
+ * user-data stream becomes a managed session (listen-key lifecycle, keep-alive,
+ * rotation), order and position state become live feeds updated by that stream,
+ * and retry decisions become an explicit, classified contract instead of an
+ * implicit code path. These types are the vocabulary all three pieces share.
+ */
+/**
+ * Binance order lifecycle statuses — the union of REST and user-stream values
+ * across USDⓈ-M and Spot. The trailing `string` intersection keeps the union
+ * open: Binance adds statuses (e.g. `EXPIRED_IN_MATCH` for STP) without
+ * breaking compilation, while known values still autocomplete.
+ */
+type OrderStatus = 'NEW' | 'PARTIALLY_FILLED' | 'FILLED' | 'CANCELED' | 'PENDING_CANCEL' | 'REJECTED' | 'EXPIRED' | 'EXPIRED_IN_MATCH' | 'PARTIALLY_CANCELED' | 'LIQUIDATED' | (string & Record<never, never>);
+/**
+ * True when the status is a terminal order state — no further execution
+ * reports or REST polls can change the outcome (late events for a terminal
+ * order are protocol noise; trackers stop mutating terminal records).
+ */
+declare function isTerminalOrderStatus(status: string): boolean;
+/**
+ * Live view of one order, folded from every source that observes it:
+ * user-stream execution reports, REST order queries, and the execution
+ * manager's submissions. All prices and quantities are exact decimal strings
+ * (see `core/decimal`) — never binary floats.
+ *
+ * Unlike the {@link import('../types.js').Execution} ledger entry (which
+ * follows one *intent*), the OrderRecord follows one *order* — including
+ * orders placed outside this SDK (by hand, by another bot, by the UI): the
+ * user stream reports them all.
+ */
+interface OrderRecord {
+    /** Exchange reconciliation key (same field the execution manager derives). */
+    clientOrderId: string;
+    /** Exchange-assigned id, once any source has reported it. */
+    exchangeOrderId?: number;
     symbol: string;
-    side: PaperPositionSide;
-    entryPrice: number;
-    quantity: number;
-    leverage: number;
-    /** Margin currently allocated to this position, released proportionally as it is reduced. */
-    margin: number;
-    unrealizedPnl: number;
-    openedAt: number;
+    side: string;
+    type: string;
+    status: OrderStatus;
+    /** Requested quantity when a source reported it, else null. */
+    originalQuantity: string | null;
+    /** Cumulative executed quantity — decimal string. */
+    executedQuantity: string;
+    /**
+     * Cumulative quote volume — decimal string. USDⓈ-M execution reports do not
+     * carry it; the fold computes `executedQuantity × averagePrice` as an
+     * estimate, exactly like the execution ledger does.
+     */
+    cumulativeQuoteQuantity: string | null;
+    /** Volume-weighted average fill price — decimal string or null. */
+    averagePrice: string | null;
+    /** Individual fills, appended once per trade, deduplicated by trade id. */
+    fills: ExecutionFill[];
+    positionSide?: string;
+    reduceOnly?: boolean;
+    timeInForce?: string;
+    /** Epoch ms when this order was first observed by any source. */
+    firstSeenAt: number;
+    /** Epoch ms of the last applied update. */
+    updatedAt: number;
+}
+/**
+ * One fully-normalized order observation — the unit the tracker folds into
+ * {@link OrderRecord}. Produced from either a user-stream event or a REST
+ * order view by the platform normalizers.
+ */
+interface OrderUpdate {
+    clientOrderId: string;
+    exchangeOrderId?: number;
+    symbol: string;
+    side: string;
+    type: string;
+    status: string;
+    originalQuantity: string | null;
+    executedQuantity: string;
+    cumulativeQuoteQuantity: string | null;
+    averagePrice: string | null;
+    /** The trade this update carries, when it reports one (fill quantity > 0). */
+    lastFill: ExecutionFill | null;
+    positionSide?: string;
+    reduceOnly?: boolean;
+    timeInForce?: string;
+    /** Epoch ms of the observation (event transaction time or REST time). */
+    updateTime: number;
+    source: 'user-stream' | 'rest';
+    /** The raw event/response this was normalized from, for auditing. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Live view of one position (USDⓈ-M), folded from `ACCOUNT_UPDATE` user-stream
+ * events. Keyed by `symbol` + `positionSide` — one-way mode reports `BOTH`,
+ * hedge mode reports `LONG` and `SHORT` separately.
+ */
+interface PositionRecord {
+    symbol: string;
+    /** 'BOTH' (one-way mode) | 'LONG' | 'SHORT' (hedge mode). */
+    positionSide: string;
+    /** Signed position amount — decimal string (negative for shorts). */
+    positionAmount: string;
+    /** Average entry price — decimal string. */
+    entryPrice: string;
+    /** Unrealized PnL as of the last event — decimal string (stream value; refresh via REST for precision). */
+    unrealizedPnl: string | null;
+    /** 'isolated' | 'cross' when reported, else null. */
+    marginType: string | null;
+    /** Isolated-position wallet balance when reported, else null. */
+    isolatedWallet: string | null;
+    /** Epoch ms of the last applied event. */
+    updatedAt: number;
 }
-interface PaperOrder {
-    orderId: number;
+/**
+ * One normalized position change — an `ACCOUNT_UPDATE` position entry
+ * (`a.P[i]`), decimal strings everywhere.
+ */
+interface PositionUpdate {
     symbol: string;
-    side: 'BUY' | 'SELL';
-    type: 'MARKET' | 'LIMIT';
+    positionSide: string;
+    positionAmount: string;
+    entryPrice: string;
+    unrealizedPnl: string | null;
+    marginType: string | null;
+    isolatedWallet: string | null;
+    updateTime: number;
+    /** The raw `a.P` entry this was normalized from. */
+    raw: Record<string, unknown>;
+}
+/** Consumer-visible lifecycle of a managed {@link UserStreamSession}. */
+type UserSessionState = 'idle' | 'starting' | 'live' | 'reconnecting' | 'closed';
+/**
+ * REST listen-key lifecycle the session drives. Product adapters implement
+ * this over the shared `HttpClient` (USDⓈ-M `/fapi/v1/listenKey`, Spot
+ * `/api/v3/userDataStream`) — swap it out for a captive/mock backend in tests.
+ */
+interface ListenKeyApi {
+    /** Create a fresh listen key. */
+    create(): Promise<string>;
+    /**
+     * Renew a listen key. Binance disconnects user streams after 60 minutes
+     * without renewal; the session calls this roughly every 30 minutes.
+     */
+    keepAlive(listenKey: string): Promise<void>;
+    /** Delete a listen key (server-side stream teardown). Best-effort. */
+    close?(listenKey: string): Promise<void>;
+}
+/**
+ * Result of one {@link ExecutionPlatform.reconcile} pass: how many REST (or
+ * simulator) views were folded into the trackers. A *view count*, not a
+ * change count — folding a view does not always mutate a record (the stream
+ * may have reported the same state already).
+ */
+interface ReconciliationSummary {
+    /** Order views folded (open orders from REST, or the simulator's history). */
+    orders: number;
+    /** Position records folded (position-risk REST rows, or simulator positions). */
+    positions: number;
+    /** Epoch ms of the snapshot this pass folded. */
+    fetchedAt: number;
+}
+/**
+ * Execution platform defaults. Keep-alive runs at the documented 30-minute
+ * cadence; a key is rotated after 3 consecutive keep-alive failures (dead
+ * key) or 6 reconnect attempts without an OPEN (network partition or the
+ * key expired server-side mid-outage).
+ */
+declare const EXECUTION_PLATFORM_DEFAULTS: {
+    /** Listen-key renewal cadence (Binance kills keys after 60 min). */
+    readonly keepAliveIntervalMs: number;
+    /** Consecutive keep-alive failures before the key is rotated. */
+    readonly keepAliveFailuresBeforeRotation: 3;
+    /**
+     * Reconnect attempts (with backoff) before the key is rotated — the escape
+     * hatch for "server accepts nothing on this key anymore".
+     */
+    readonly reconnectAttemptsBeforeRotation: 6;
+    /** Retained order records before the oldest are evicted. */
+    readonly maxTrackedOrders: 5000;
+    /** Default wait for an order to reach a terminal status. */
+    readonly terminalTimeoutMs: 30000;
+};
+/**
+ * What a retry of a failed order operation means, semantically:
+ *
+ *  - `'safe'` — the failure proves no order side effect occurred; retrying is
+ *    free of double-execution risk (order never reached the engine, request
+ *    was throttled before processing, target of a cancel already gone).
+ *  - `'idempotent'` — the target backend enforces the idempotency key, so a
+ *    retry with the same key cannot double-execute. The live exchange never
+ *    earns this label (Binance does not enforce `newClientOrderId`
+ *    uniqueness); it is reserved for backends that do (e.g. a paper engine
+ *    keyed by intent).
+ *  - `'reconciliation-required'` — the outcome is unknown: the request may or
+ *    may not have reached the engine. Retrying blind risks doubling the
+ *    position; the caller must reconcile first (the execution manager's
+ *    `reconcile()`, or `GET /fapi/v1/order` by clientOrderId).
+ *  - `'never-retry'` — a definitive rejection or a programming error: the
+ *    same request will fail the same way (filters, margin, permissions).
+ */
+type RetrySafety = 'safe' | 'idempotent' | 'reconciliation-required' | 'never-retry';
+/** Result of classifying an error for retry semantics. */
+interface RetryClassification {
+    safety: RetrySafety;
+    /** Human-readable justification, stable enough for dashboards. */
+    reason: string;
+}
+
+/** Options for {@link OrderTracker}. */
+interface OrderTrackerOptions {
+    /** Observability bus; `execution.order.*` events are published to it. */
+    events?: EventBus;
+    /** Retained records before the oldest are evicted. Default 5000. */
+    maxRecords?: number;
+}
+/**
+ * Live order-state feed.
+ *
+ * One {@link OrderRecord} per order, folded from every source that observes
+ * it: user-stream execution reports (all orders on the account — including
+ * orders placed outside this SDK), REST order views, and anything else a
+ * caller pushes through `applyUpdate`. Records hold exact decimal strings and
+ * per-trade fills deduplicated by trade id.
+ *
+ * ```ts
+ * const orders = platform.orders;
+ * orders.on('update', (record) => log(record.status));
+ *
+ * await platform.startUserSession();          // feed goes live
+ * const final = await orders.waitForTerminal('nbsdk-abc');  // promise form
+ * ```
+ *
+ * The tracker is a *view*, not a ledger: it keeps no intents and drives no
+ * requests — the execution manager owns submission/reconciliation, this owns
+ * "what does the account's order book look like right now".
+ */
+declare class OrderTracker extends EventEmitter {
+    private readonly records;
+    private readonly byExchangeId;
+    private readonly maxRecords;
+    private readonly events?;
+    constructor(options?: OrderTrackerOptions);
+    /**
+     * Dispatch one raw user-data frame. Recognized execution reports
+     * (`ORDER_TRADE_UPDATE`, spot `executionReport`) fold into records;
+     * everything else is ignored — the session feeds this its full event flow.
+     */
+    applyUserEvent(event: unknown): void;
+    /** Fold a REST order view (create ack / query / cancel result). */
+    applyOrderShape(shape: OrderShape): void;
+    /** Fold one normalized observation and emit the updated record. */
+    applyUpdate(update: OrderUpdate): void;
+    /** Current record for a client order id (defensive copy). */
+    get(clientOrderId: string): OrderRecord | undefined;
+    /** Current record for an exchange order id (defensive copy). */
+    getByExchangeId(orderId: number): OrderRecord | undefined;
+    /** All tracked records (defensive copies), insertion order. */
+    all(): OrderRecord[];
+    /** Records that have not reached a terminal status. */
+    open(): OrderRecord[];
+    /**
+     * Resolve with the record once its status is terminal. Rejects if the order
+     * is unknown, or on timeout. Safe to call repeatedly for the same order.
+     */
+    waitForTerminal(clientOrderId: string, timeoutMs?: number): Promise<OrderRecord>;
+    /** Number of tracked records (cheap). */
+    get size(): number;
+    private evictOverflow;
+    private evict;
+    private copy;
+}
+
+/** Options for {@link PositionTracker}. */
+interface PositionTrackerOptions {
+    /** Observability bus; `execution.position.*` events are published to it. */
+    events?: EventBus;
+}
+/**
+ * Live position-state feed (USDⓈ-M).
+ *
+ * Folds `ACCOUNT_UPDATE` user-stream events into one {@link PositionRecord}
+ * per `symbol` + `positionSide` (one-way mode reports `BOTH`; hedge mode
+ * reports `LONG` and `SHORT`). Every amount is an exact decimal string — the
+ * signed position amount distinguishes direction, so a short is a negative
+ * amount, never a separate flag.
+ *
+ * ```ts
+ * const positions = platform.positions;
+ * positions.on('update', (p) => log(p.symbol, p.positionAmount));
+ * await platform.startUserSession();     // feed goes live
+ * positions.get('BTCUSDT');              // current one-way position
+ * positions.nonZero();                   // exposure view
+ * ```
+ *
+ * The unrealized PnL is the stream's own mark at event time; strategies that
+ * need a current mark should combine it with the mark-price stream rather
+ * than polling this field.
+ */
+declare class PositionTracker extends EventEmitter {
+    private readonly positions;
+    private readonly events?;
+    constructor(options?: PositionTrackerOptions);
+    /**
+     * Dispatch one raw user-data frame. `ACCOUNT_UPDATE` position entries fold
+     * into records; everything else is ignored.
+     */
+    applyUserEvent(event: unknown): void;
+    /** Fold one normalized position update and emit the updated record. */
+    applyUpdate(update: PositionUpdate): void;
+    /**
+     * Current position for a symbol. In one-way mode pass no side (or 'BOTH');
+     * in hedge mode pass 'LONG' or 'SHORT'. Defensive copy.
+     */
+    get(symbol: string, positionSide?: string): PositionRecord | undefined;
+    /** All tracked positions (defensive copies), insertion order. */
+    all(): PositionRecord[];
+    /** Positions with a non-zero amount — the actual exposure view. */
+    nonZero(): PositionRecord[];
+    /** Number of tracked positions (cheap). */
+    get size(): number;
+}
+
+/**
+ * v3 execution platform — REST reconciliation pass.
+ *
+ * The user stream sees the present and the future, never the past: an order
+ * placed before `startUserSession()` (by hand, by another bot, by a previous
+ * process of this SDK) never appears in it, and after a partition the stream
+ * resumes without replaying what was missed. `reconcile()` closes that gap
+ * the same way the execution manager does for single intents — by folding an
+ * authoritative REST snapshot into the trackers:
+ *
+ *   - `GET /fapi/v1/openOrders` (USDⓈ-M, one call) / per-symbol Spot
+ *     `GET /api/v3/openOrders` → `OrderTracker.applyOrderShape`
+ *   - `GET /fapi/v2/positionRisk` (USDⓈ-M) → `PositionTracker.applyUpdate`
+ *
+ * Paper mode reconciles against the simulator's own book instead — the same
+ * fold, the same events, zero network. Every fold emits the identical
+ * `order.updated` / `position.updated` events a stream fold emits, so
+ * consumers cannot tell which path updated a record.
+ */
+/** Options for a reconciliation pass. */
+interface ReconcileOptions {
+    /**
+     * Restrict the pass to these symbols. Required for live Spot (its
+     * `openOrders` route needs a symbol); optional for USDⓈ-M (one call covers
+     * the whole account, and the position fold filters to these symbols).
+     */
+    symbols?: string[];
+}
+/** Everything a reconciliation pass needs, provided by the platform. */
+interface ReconcileTarget {
+    product: 'usdm' | 'spot';
+    /** Shared transports — the same hosts, weight budgets and mocks as always. */
+    core: Pick<CoreContext, 'events' | 'http'>;
+    /** Paper wiring; presence switches the pass to the simulator's book. */
+    paper?: {
+        engine: PaperTradingEngine;
+        adapter: PaperExecutionAdapter;
+    };
+    orders: OrderTracker;
+    positions: PositionTracker;
+}
+/**
+ * Run one reconciliation pass — see the module doc. Returns how many views
+ * were folded; throws only on transport failure (the caller decides whether
+ * that is fatal — for a startup gap-fill it usually is not).
+ */
+declare function reconcileExecutionPlatform(target: ReconcileTarget, options?: ReconcileOptions): Promise<ReconciliationSummary>;
+/**
+ * `GET /fapi/v1/openOrders` row (and the paper adapter's raw records, which
+ * mirror it) → decimal-string {@link OrderShape} for the tracker's REST fold.
+ */
+declare function orderShapeFromUsdmOpenOrder(raw: Record<string, unknown>): OrderShape;
+/**
+ * `GET /fapi/v2/positionRisk` row → {@link PositionUpdate}. Binance reports
+ * one row per symbol × positionSide, including zero-size rows — folding a
+ * zero row is the correct "authoritative flat" semantics.
+ */
+declare function positionUpdatesFromPositionRisk(raw: Record<string, unknown>, fetchedAt: number): PositionUpdate[];
+/** `GET /api/v3/openOrders` row → decimal-string {@link OrderShape}. */
+declare function orderShapeFromSpotOpenOrder(raw: Record<string, unknown>): OrderShape;
+
+/**
+ * Pure normalization for the execution platform: raw user-data frames and
+ * REST order views become decimal-string {@link OrderUpdate}s and
+ * {@link PositionUpdate}s, which the trackers fold. Product field-name
+ * differences (USDⓈ-M `ORDER_TRADE_UPDATE.o` vs Spot `executionReport`, spot
+ * `Z` cumulative quote vs none on futures) end here — nothing downstream
+ * knows which product an update came from.
+ *
+ * Normalization always reads the *raw frame* strings, never the
+ * schema-transformed numbers: Binance transmits exact decimals precisely
+ * because binary floats cannot represent them, so coercing through `Number`
+ * and back would corrupt values like `123.456` at exactly the fields money
+ * math depends on. Zod runs as a validation-only pass (see
+ * {@link createUserEventParser}); the raw string survives to `Decimal`.
+ */
+/** Parse one raw user-data frame — validates, then returns the frame untouched. */
+type UserEventParser = (raw: unknown) => unknown;
+/**
+ * Build the per-product frame parser for a user-data session. The typed Zod
+ * schemas run as a *validation* pass — a frame that parses is known-good
+ * Binance shape; the raw frame (decimal strings intact) is returned untouched
+ * so normalization keeps exact decimals. Frames with unknown-but-valid `e`
+ * types (new Binance events, e.g. `TRADE_LITE`) pass through unvalidated;
+ * shapeless frames throw and the session surfaces them as errors.
+ */
+declare function createUserEventParser(product: 'usdm' | 'spot'): UserEventParser;
+
+/** Tuning for {@link UserStreamSession}. */
+interface UserStreamSessionOptions {
+    /** Product label used in events and errors ('usdm' | 'spot' | …). */
+    product: string;
+    /** REST listen-key lifecycle the session drives. */
+    listenKeyApi: ListenKeyApi;
+    /** User-data stream base URL (the listen key is appended as the path). */
+    userStreamUrl: string;
+    /** Observability bus; `execution.session.*` events are published to it. */
+    events?: EventBus;
+    /** Connection label; defaults to `userSession:<product>`. */
+    name?: string;
+    /** Keep-alive cadence. Default 30 minutes. */
+    keepAliveIntervalMs?: number;
+    /** Consecutive keep-alive failures before key rotation. Default 3. */
+    keepAliveFailuresBeforeRotation?: number;
+    /** Reconnect attempts before key rotation. Default 6. */
+    reconnectAttemptsBeforeRotation?: number;
+    /**
+     * A connection that opens and dies within this window *without delivering
+     * a single frame* counts as a flap. Default 10s.
+     */
+    flapWindowMs?: number;
+    /** Consecutive flaps before key rotation. Default 5. */
+    flapFailuresBeforeRotation?: number;
+    /** Frame parser; defaults to the product's (usdm → futures, else spot). */
+    parseEvent?: UserEventParser;
+    /** Injectable WebSocket factory for tests. */
+    socketFactory?: (url: string) => WebSocket;
+    /** Called once when the session is closed by the user (or `close()`). */
+    onClose?: () => void;
+    /** Connection-level passthrough (reconnect tuning, rotation window, …). */
+    connection?: Partial<Omit<WsConnectionOptions, 'buildUrl' | 'name' | 'events' | 'socketFactory'>>;
+}
+/**
+ * Managed user-data stream session.
+ *
+ * v2 (and the v3 M1 product clients) left the listen-key dance to the caller:
+ * create the key, schedule the 30-minute keep-alive, notice when the key dies,
+ * restart. Every consumer reimplemented it, and the failure modes (key expiry
+ * mid-run, keep-alive failing silently, zombie sockets) were exactly the kind
+ * of thing that loses fills.
+ *
+ * The session owns the whole lifecycle over a {@link WsConnection}:
+ *
+ *  - `start()` creates the key, connects, and schedules keep-alive;
+ *  - keep-alive failures are counted — after 3 in a row the key is rotated
+ *    (a fresh key is created and the connection swapped onto it);
+ *  - a connection that cannot re-establish after 6 backoff attempts gets its
+ *    key rotated too (the escape hatch for "the key died while we were
+ *    partitioned");
+ *  - the 24-hour server-side kill is preempted by the connection's own 23-hour
+ *    rotation (same listen key, per Binance's renewal semantics);
+ *  - `close()` stops everything and deletes the key server-side, best-effort.
+ *
+ * The session is also a drop-in user stream for the execution manager: it
+ * emits `userData` with each parsed (validated, raw-decimal-preserving) frame,
+ * so `executionManager.setUserStream(session)` immediately routes live
+ * execution reports into the intent ledger.
+ *
+ * ```ts
+ * const session = new UserStreamSession({
+ *   product: 'usdm',
+ *   listenKeyApi,
+ *   userStreamUrl: core.endpoints.wsUser,
+ *   events: core.events,
+ * });
+ * const key = await session.start();
+ * session.on('userData', (event) => { /* e: ORDER_TRADE_UPDATE … *\/ });
+ * session.close();
+ * ```
+ */
+declare class UserStreamSession extends WsConnection {
+    private readonly api;
+    private readonly userStreamUrl;
+    private readonly parse;
+    private readonly sessionProduct;
+    private readonly keepAliveIntervalMs;
+    private readonly keepAliveFailuresBeforeRotation;
+    private readonly reconnectAttemptsBeforeRotation;
+    private readonly flapWindowMs;
+    private readonly flapFailuresBeforeRotation;
+    private readonly sessionEvents?;
+    private listenKeyValue;
+    private keepAliveTimer;
+    private keepAliveFailures;
+    private rotating;
+    private sessionStateValue;
+    private startPromise;
+    private readonly onClose?;
+    /** Epoch ms of the last 'open'; flap detection. */
+    private openedAtMs;
+    /** Inbound frames since the last 'open'; flap detection. */
+    private framesSinceOpen;
+    /** Consecutive open-then-die-without-frames cycles. */
+    private flapFailures;
+    constructor(options: UserStreamSessionOptions);
+    /** Product this session serves ('usdm' | 'spot' | …). */
+    get product(): string;
+    /** Consumer-visible session state. */
+    get sessionState(): UserSessionState;
+    /** The live listen key, or null before start / after close. */
+    get listenKey(): string | null;
+    /**
+     * Start the session: create a listen key, connect, schedule keep-alive.
+     * Idempotent — concurrent or repeated calls share one start; returns the
+     * listen key.
+     */
+    start(): Promise<string>;
+    /**
+     * Close the session: stop keep-alive, tear the connection down, delete the
+     * listen key server-side (best-effort). Safe to call repeatedly and from
+     * any state.
+     */
+    close(): void;
+    protected handleRawMessage(text: string): void;
+    private scheduleNextKeepAlive;
+    private keepAliveTick;
+    /**
+     * Rotate onto a fresh listen key: create it, swap `listenKeyValue`, and
+     * force the connection to re-establish on the new key. Guarded so overlapping
+     * triggers (keep-alive failure + reconnect storm) rotate once.
+     */
+    private rotateListenKey;
+    private setSessionState;
+    /** Narrowing-safe terminal check (crosses `await` boundaries). */
+    private isClosed;
+    private emitSessionEvent;
+}
+
+/**
+ * v3 paper backend — the simulator behind the execution-platform boundary.
+ *
+ * Milestone 3's execution platform gave live trading a managed session and
+ * order/position feeds. Milestone 4 puts the **paper simulator behind the
+ * same boundary**: a {@link PaperSession} emits the exact user-data frames a
+ * live session would (`ORDER_TRADE_UPDATE` for fills, `ACCOUNT_UPDATE` for
+ * the position the fill produced), so the platform's trackers, the
+ * `waitForTerminal()` promise API and the reconciliation semantics behave
+ * *identically* whether orders route to the exchange or to the simulator.
+ * Strategy code written against the paper platform runs unchanged live.
+ */
+/** Options for {@link PaperSession}. */
+interface PaperSessionOptions {
+    /** The simulator whose fills become user-data frames. */
+    engine: PaperTradingEngine;
+    /** Report source — the adapter orders flow through (one per engine). */
+    adapter: PaperExecutionAdapter;
+    /** Observability bus; `execution.session.*` events mirror the live session. */
+    events?: EventBus;
+    /** Called once when the session is closed by the user (or `close()`). */
+    onClose?: () => void;
+}
+/**
+ * A user-data stream session with no network: simulator fills, replayed as
+ * exchange-shaped user-data frames.
+ *
+ * The contract is the one the platform (and the execution manager) already
+ * consume: `start()` goes live, `close()` is terminal, frames arrive on
+ * `userData`. There is no listen key, no keep-alive, no rotation — nothing to
+ * rotate, because the "server" is an in-process {@link PaperTradingEngine}.
+ * Fill → frame translation is synchronous: by the time `placeOrder()` resolves,
+ * the trackers have already folded the fill.
+ *
+ * ```ts
+ * const session = new PaperSession({ engine, adapter });
+ * await session.start();
+ * session.on('userData', (event) => {
+ *   // { e: 'ORDER_TRADE_UPDATE', … } / { e: 'ACCOUNT_UPDATE', … }
+ * });
+ * ```
+ */
+declare class PaperSession extends EventEmitter implements UserStreamLike {
+    private readonly engine;
+    private readonly adapter;
+    private readonly sessionEvents?;
+    private readonly onClose?;
+    private sessionStateValue;
+    private readonly reportListener;
+    constructor(options: PaperSessionOptions);
+    /** Consumer-visible lifecycle: `idle` → `live` → `closed`. */
+    get sessionState(): UserSessionState;
+    /** Alias for {@link sessionState} — reads naturally next to book/tracker states. */
+    get state(): UserSessionState;
+    /**
+     * The listen key a live session would carry — always null here: the
+     * simulator *is* the server, there is nothing to register.
+     */
+    get listenKey(): string | null;
+    /** True while simulator fills flow into `userData`. */
+    get isLive(): boolean;
+    /**
+     * Session-contract member: resolve once frames are being delivered. For a
+     * live paper session that is immediate — the simulator delivers
+     * synchronously, there is no socket handshake to wait for.
+     */
+    waitForOpen(_timeoutMs?: number): Promise<void>;
+    /**
+     * Start the session: attach the fill listener. Idempotent; no I/O — the
+     * listen-key create/connect/keep-alive dance has no paper equivalent.
+     */
+    start(): Promise<PaperSession>;
+    /** Close the session (detach the fill listener). Terminal; safe repeatedly. */
+    close(): void;
+    /** Translate one simulator fill into the frames a live session would send. */
+    private onFill;
+}
+/**
+ * Simulator fill → USDⓈ-M `ORDER_TRADE_UPDATE` frame. Field-for-field the
+ * live shape (`o.c`, `o.X`, `o.z`, `o.ap`, …), decimal strings everywhere —
+ * `OrderTracker.applyUserEvent` cannot tell it from a real fill.
+ */
+declare function paperOrderTradeUpdateFrame(report: ExecutionReportShape, atMs?: number): Record<string, unknown>;
+/**
+ * Simulator position → USDⓈ-M `ACCOUNT_UPDATE` frame. One-way mode semantics
+ * (`ps: 'BOTH'`) with a *signed* amount, the way Binance reports it: a short
+ * is a negative `pa`, never a separate flag.
+ */
+declare function paperAccountUpdateFrame(symbol: string, position: {
+    side: string;
     quantity: number;
-    price: number;
-    status: 'FILLED';
-    filledQuantity: number;
-    avgFillPrice: number;
-    /** Realized PnL booked by this order, if it reduced or closed a position. */
-    realizedPnl: number;
-    createdAt: number;
-}
-interface PaperAccount {
-    /** Wallet balance: starts at initialBalance and moves only with realized PnL. */
-    balance: number;
-    /** Wallet balance minus margin currently locked in open positions. */
-    availableBalance: number;
-    /** balance + unrealized PnL. */
-    totalWalletBalance: number;
-    realizedPnl: number;
+    entryPrice: number;
     unrealizedPnl: number;
-    positions: Record<string, PaperPosition>;
-    orders: PaperOrder[];
-}
-interface PaperTradingOptions {
-    initialBalance?: number;
-    /** Injectable so tests and offline callers can supply their own price source. */
-    market?: FuturesMarket;
-}
-/**
- * In-memory simulator for USD-M futures fills. Prices come from the live public
- * market endpoints; nothing is ever sent to the exchange.
- *
- * Accounting model: `balance` moves only on realized PnL. Opening a position locks
- * `notional / leverage` of margin out of `availableBalance`; reducing it releases
- * that margin pro-rata and books the realized PnL. Orders fill instantly at the
- * current mark for MARKET, or at the stated limit price for LIMIT — there is no
- * order book simulation, slippage or funding.
- */
-declare class PaperTradingEngine {
-    private readonly account;
-    private readonly market;
-    private orderIdCounter;
-    constructor(options?: PaperTradingOptions);
-    /** Current mark price for any tradeable symbol. */
-    getMarketPrice(symbol: string): Promise<number>;
-    private positionFor;
-    placeOrder(params: {
-        symbol: string;
-        side: 'BUY' | 'SELL';
-        type: 'MARKET' | 'LIMIT';
-        quantity: number;
-        price?: number;
-        leverage?: number;
-    }): Promise<PaperOrder>;
-    /**
-     * Apply a fill to a position, returning the realized PnL it booked.
-     * Handles extend, partial reduce, full close, and a flip through zero.
-     */
-    private applyFill;
-    private openExposure;
-    /** Reduce a position, releasing margin pro-rata and booking realized PnL. */
-    private reduceExposure;
-    private markToMarket;
-    private recomputeTotals;
-    /** Refresh unrealized PnL for every open position against live prices. */
-    updatePositions(): Promise<void>;
-    getAccountInfo(): PaperAccount;
-    getPosition(symbol: string): PaperPosition | undefined;
-    getAllPositions(): Record<string, PaperPosition>;
-    /** Open positions only — the zero-size entries left behind by closed trades are filtered out. */
-    getOpenPositions(): PaperPosition[];
-    getOrderHistory(symbol?: string): PaperOrder[];
-}
-
-declare const WsKlinePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"kline">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    k: z.ZodObject<{
-        t: z.ZodNumber;
-        T: z.ZodNumber;
-        s: z.ZodString;
-        i: z.ZodString;
-        o: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        c: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        h: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        l: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        v: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        n: z.ZodNumber;
-        x: z.ZodBoolean;
-        q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        V: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        Q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-type WsKlinePayload = z.infer<typeof WsKlinePayloadSchema>;
-declare const WsAggTradePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"aggTrade">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    a: z.ZodNumber;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    f: z.ZodNumber;
-    l: z.ZodNumber;
-    T: z.ZodNumber;
-    m: z.ZodBoolean;
-}, z.core.$strip>;
-type WsAggTradePayload = z.infer<typeof WsAggTradePayloadSchema>;
-declare const WsTradePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"trade">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    t: z.ZodNumber;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    T: z.ZodNumber;
-    m: z.ZodBoolean;
-}, z.core.$strip>;
-type WsTradePayload = z.infer<typeof WsTradePayloadSchema>;
-declare const WsDepthUpdatePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"depthUpdate">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    U: z.ZodNumber;
-    u: z.ZodNumber;
-    T: z.ZodOptional<z.ZodNumber>;
-    pu: z.ZodOptional<z.ZodNumber>;
-    b: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    a: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-}, z.core.$strip>;
-type WsDepthUpdatePayload = z.infer<typeof WsDepthUpdatePayloadSchema>;
-declare const WsTicker24hrPayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"24hrTicker">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    P: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    c: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    o: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    h: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    l: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    v: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-}, z.core.$strip>;
-type WsTicker24hrPayload = z.infer<typeof WsTicker24hrPayloadSchema>;
-declare const WsBookTickerPayloadSchema: z.ZodObject<{
-    u: z.ZodNumber;
-    s: z.ZodString;
-    b: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    B: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    a: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    A: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-}, z.core.$strip>;
-type WsBookTickerPayload = z.infer<typeof WsBookTickerPayloadSchema>;
-declare const WsMarkPricePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"markPriceUpdate">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    i: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    P: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    r: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    T: z.ZodNumber;
-}, z.core.$strip>;
-type WsMarkPricePayload = z.infer<typeof WsMarkPricePayloadSchema>;
-declare const WsMiniTickerPayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"24hrMiniTicker">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    c: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    o: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    h: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    l: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    v: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-}, z.core.$strip>;
-type WsMiniTickerPayload = z.infer<typeof WsMiniTickerPayloadSchema>;
-declare const WsForceOrderPayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"forceOrder">;
-    E: z.ZodNumber;
-    o: z.ZodObject<{
-        s: z.ZodString;
-        S: z.ZodString;
-        o: z.ZodString;
-        f: z.ZodString;
-        q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        ap: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        X: z.ZodString;
-        l: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        z: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        T: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-type WsForceOrderPayload = z.infer<typeof WsForceOrderPayloadSchema>;
-declare const WsCompositeIndexPayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"compositeIndex">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    c: z.ZodArray<z.ZodObject<{
-        b: z.ZodString;
-        q: z.ZodString;
-        w: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-        p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type WsCompositeIndexPayload = z.infer<typeof WsCompositeIndexPayloadSchema>;
-declare const WsAssetIndexPayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"assetIndex">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    i: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    b: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    a: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-}, z.core.$strip>;
-type WsAssetIndexPayload = z.infer<typeof WsAssetIndexPayloadSchema>;
-declare const WsRollingWindowTickerPayloadSchema: z.ZodObject<{
-    e: z.ZodEnum<{
-        "1hTicker": "1hTicker";
-        "4hTicker": "4hTicker";
-        "1dTicker": "1dTicker";
-        "7dTicker": "7dTicker";
-        "30dTicker": "30dTicker";
-    }>;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    p: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    P: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    o: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    h: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    l: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    c: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    v: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    q: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    O: z.ZodNumber;
-    C: z.ZodNumber;
-}, z.core.$strip>;
-type WsRollingWindowTickerPayload = z.infer<typeof WsRollingWindowTickerPayloadSchema>;
-declare const WsSpotAvgPricePayloadSchema: z.ZodObject<{
-    e: z.ZodLiteral<"avgPrice">;
-    E: z.ZodNumber;
-    s: z.ZodString;
-    i: z.ZodString;
-    w: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-    T: z.ZodNumber;
-}, z.core.$strip>;
-type WsSpotAvgPricePayload = z.infer<typeof WsSpotAvgPricePayloadSchema>;
-type WsStreamPayload = WsKlinePayload | WsAggTradePayload | WsTradePayload | WsDepthUpdatePayload | WsTicker24hrPayload | WsBookTickerPayload | WsMarkPricePayload | WsMiniTickerPayload | WsForceOrderPayload | WsCompositeIndexPayload | WsAssetIndexPayload | WsRollingWindowTickerPayload | WsSpotAvgPricePayload;
-declare function parseWsPayload(streamName: string, raw: unknown): WsStreamPayload;
+} | undefined, atMs?: number): Record<string, unknown>;
+/**
+ * Format a simulator float as a clean decimal string. The simulator's
+ * internal arithmetic is IEEE-754 (by design — it is a model, not a ledger),
+ * so raw `String(number)` would leak representation noise (`0.1 + 0.2` →
+ * `0.30000000000000004`). Twelve significant digits strips that noise while
+ * staying far finer than any Binance tick; the boundary stays decimal-exact
+ * from here on (trackers, `Decimal`, ledger math).
+ */
+declare function decimalString(value: number): string;
+
+/** Session tuning accepted by {@link ExecutionPlatform.startUserSession}. */
+type UserSessionTuning = Pick<UserStreamSessionOptions, 'keepAliveIntervalMs' | 'keepAliveFailuresBeforeRotation' | 'reconnectAttemptsBeforeRotation' | 'connection' | 'socketFactory'>;
+/** Paper backend wiring: which simulator sits in the "server" seat. */
+interface PaperBackendOptions {
+    /** The simulator whose fills the session replays as user-data frames. */
+    engine: PaperTradingEngine;
+    /** Report source — the adapter orders flow through. */
+    adapter: PaperExecutionAdapter;
+}
+/** Either session flavor a platform can hold: live (listen key) or paper. */
+type PlatformUserSession = UserStreamSession | PaperSession;
+/** Options for {@link ExecutionPlatform}. */
+interface ExecutionPlatformOptions {
+    /** Product the platform serves — decides listen-key REST routes and WS URL. */
+    product: 'usdm' | 'spot';
+    /**
+     * Shared runtime: REST hosts (listen-key calls), resolved endpoints (user
+     * WS URL) and the observability bus. Same context every product client
+     * holds — one weight budget, one event stream.
+     */
+    core: Pick<CoreContext, 'endpoints' | 'events' | 'http'>;
+    /**
+     * Execution manager to auto-attach when a session starts: its intent ledger
+     * then tracks live fills from the stream (`setUserStream`), and detaches
+     * when the session closes.
+     */
+    executionManager?: ExecutionManager;
+    /** Order-record retention; default 5000. */
+    maxTrackedOrders?: number;
+    /**
+     * Paper backend wiring. When set, the platform runs in paper mode:
+     * `startUserSession()` opens a {@link PaperSession} (no listen key, no
+     * socket) that replays simulator fills as user-data frames, and
+     * `reconcile()` folds the simulator's own state. See
+     * {@link createPaperExecutionPlatform} for the assembled runtime.
+     */
+    paper?: PaperBackendOptions;
+}
+/**
+ * v3 execution platform — one product's live trading state.
+ *
+ * Milestone 3 composition root: a managed user-data stream session, the
+ * order/position feeds it drives, and the semantic retry classifier, all over
+ * a shared {@link CoreContext}. The raw API layer (`trading.createOrder`) and
+ * the intent layer (`execution.placeOrder`) stay where they were; the platform
+ * adds the *account view* — what is live right now, fed by the exchange
+ * itself:
+ *
+ * ```ts
+ * const usdm = new USDMClient(core);
+ * await usdm.executionPlatform.startUserSession();
+ *
+ * await usdm.execution.placeOrder({ symbol: 'BTCUSDT', side: 'BUY', … });
+ * // execution ledger now updates from the stream, and:
+ * usdm.executionPlatform.orders.get('nbsdk-…');      // live OrderRecord
+ * usdm.executionPlatform.positions.get('BTCUSDT');  // live PositionRecord
+ * usdm.executionPlatform.classify(err).safety;       // 'reconciliation-required'
+ * ```
+ *
+ * Milestone 4 adds two capabilities on the same boundary:
+ *  - **`reconcile()`** — a REST snapshot (open orders + position risk) folded
+ *    into the trackers: the startup gap-fill for orders that existed before
+ *    the stream went live, and the recovery pass after a disconnect.
+ *  - **paper mode** — with the `paper` option (see
+ *    {@link createPaperExecutionPlatform}) the session, trackers and
+ *    reconcile semantics run against the local simulator instead.
+ *
+ * Standalone use (any product wiring, custom listen-key backends for tests):
+ *
+ * ```ts
+ * const platform = new ExecutionPlatform({ product: 'usdm', core });
+ * ```
+ */
+declare class ExecutionPlatform {
+    readonly product: 'usdm' | 'spot';
+    readonly orders: OrderTracker;
+    readonly positions: PositionTracker;
+    private readonly core;
+    private readonly executionManager?;
+    private readonly paperBackend?;
+    private sessionValue;
+    constructor(options: ExecutionPlatformOptions);
+    /** The live user-data stream session, or null before `startUserSession`. */
+    get userSession(): PlatformUserSession | null;
+    /**
+     * The live session when it is a listen-key session (REST-wired products).
+     * Null in paper mode — the paper session carries no listen key.
+     */
+    get liveUserSession(): UserStreamSession | null;
+    /** True when the platform runs against the paper simulator. */
+    get isPaper(): boolean;
+    /** True once a session has been started (cheap, no I/O). */
+    hasUserSession(): boolean;
+    /**
+     * Start the managed user-data stream: create the listen key, connect, run
+     * the 30-minute keep-alive, rotate on failure. The platform's order and
+     * position feeds go live immediately, and the attached execution manager
+     * (when one was provided) begins tracking live fills.
+     *
+     * In paper mode there is nothing to connect: the returned
+     * {@link PaperSession} replays simulator fills as user-data frames through
+     * the exact same `userData` contract — the trackers go live identically.
+     */
+    startUserSession(tuning?: UserSessionTuning): Promise<PlatformUserSession>;
+    /** Classify an error for retry semantics — see {@link classifyRetrySafety}. */
+    classify(error: unknown): RetryClassification;
+    /**
+     * Fold a REST snapshot of the account into the trackers — the gap-fill the
+     * user stream cannot provide: orders that existed *before* the session went
+     * live, and the authoritative position state after any disconnect.
+     *
+     * Live mode pulls `GET /fapi/v1/openOrders` (or per-symbol Spot
+     * `openOrders`) and `GET /fapi/v2/positionRisk` over the shared core
+     * transports; paper mode folds the simulator's own book. Returns how many
+     * views were folded; every fold emits the same `order.updated` /
+     * `position.updated` events stream folds do.
+     *
+     * ```ts
+     * await platform.startUserSession();
+     * const summary = await platform.reconcile();   // startup gap-fill
+     * summary.orders; summary.positions;
+     * ```
+     */
+    reconcile(options?: ReconcileOptions): Promise<ReconciliationSummary>;
+    /** Close the session (stop keep-alive, disconnect, delete the key). Trackers keep their records. */
+    close(): void;
+    /** Shared wiring for both session flavors: feed the trackers, remember it. */
+    private attachSession;
+}
+
+/**
+ * v3 state platform — managed local book.
+ *
+ * The pure {@link OrderBook} owns the L2 algorithm (snapshot + diff + gap
+ * detection, exact-decimal levels). {@link ManagedBook} owns the *lifecycle*
+ * around it: the canonical Binance sync dance (buffer diffs while the REST
+ * snapshot is in flight, apply the tail that overlaps the snapshot), a
+ * consumer-visible sync state, events, and the `waitForSync()` promise —
+ * the same ergonomics the execution platform's trackers have.
+ */
+/** Consumer-visible lifecycle of one managed book. */
+type ManagedBookState = 'syncing' | 'live' | 'desynced' | 'closed';
+/** Event payload for `update` — a cheap top-of-book summary. */
+interface BookUpdateEvent {
+    symbol: string;
+    lastUpdateId: number | null;
+    bestBid: string | null;
+    bestAsk: string | null;
+}
+/** Event payload for `desync` / `resynced` / `synced`. */
+interface BookSyncEvent {
+    symbol: string;
+    /** Last applied update id (null before the first snapshot). */
+    lastUpdateId: number | null;
+    /** Desync reason, when known (`sequence-gap` | `interrupted` | `snapshot-stream-race`). */
+    reason?: string;
+    /** Diffs applied straight from the pre-snapshot buffer, when > 0. */
+    buffered?: number;
+}
+/** Options for {@link ManagedBook}. */
+interface ManagedBookOptions {
+    /** Diffs buffered while the snapshot is in flight before the oldest drop. */
+    maxBufferedDiffs?: number;
+}
+/**
+ * One symbol's live book, managed end to end.
+ *
+ * ```ts
+ * const book = await engine.watch('BTCUSDT');   // resolves once synced
+ * book.state;               // 'live'
+ * book.bestBid;             // { price: '42150.10', quantity: '2.5' } — exact
+ * book.metrics();           // spread, microprice, imbalance, depth…
+ * book.on('update', (e) => log(e.bestBid));
+ * await book.waitForSync(); // after a desync, resolves on recovery
+ * ```
+ *
+ * The book is a *view* over the platform's pooled WS subscription and the
+ * REST snapshot route — it never opens a socket or issues a request itself
+ * (the {@link BookEngine} drives it).
+ */
+declare class ManagedBook extends EventEmitter {
+    readonly symbol: string;
+    private readonly book;
+    private stateValue;
+    /** Diffs received before the first snapshot, applied (filtered) after it. */
+    private readonly diffBuffer;
+    private readonly maxBufferedDiffs;
+    constructor(symbol: string, options?: ManagedBookOptions);
+    /** Consumer-visible sync state. */
+    get state(): ManagedBookState;
+    /** True while the local book mirrors the exchange book. */
+    get isSynced(): boolean;
+    /** Best bid level (exact decimal strings) or null when the bid side is empty. */
+    get bestBid(): BookLevel | null;
+    /** Best ask level (exact decimal strings) or null when the ask side is empty. */
+    get bestAsk(): BookLevel | null;
+    /** Mid price (exact decimal string) or null when one-sided. */
+    get midPrice(): string | null;
+    /** Top-of-book metrics (spread, microprice, imbalance, depth, …). */
+    metrics(depthPct?: number): OrderBookMetrics;
+    /** Bid levels (best first), for display/snapshotting. */
+    bids(limit: number): BookLevel[];
+    /** Ask levels (best first), for display/snapshotting. */
+    asks(limit: number): BookLevel[];
+    /** Last applied update id (null before the first snapshot). */
+    get lastUpdateId(): number | null;
+    /**
+     * Resolve once the book is synced. Rejects on timeout or terminal close.
+     * Safe to call repeatedly; also the recovery signal after a desync.
+     */
+    waitForSync(timeoutMs?: number): Promise<void>;
+    /** Terminal close — the engine calls this on unwatch/engine close. */
+    close(): void;
+    /**
+     * Feed one depth diff. Before the first snapshot the diff buffers (the
+     * canonical Binance sync algorithm); after it, a failed apply means a
+     * sequence gap — the book desyncs and the engine must resnapshot.
+     * @internal
+     */
+    receiveDiff(diff: DiffInput): void;
+    /**
+     * Apply a REST snapshot, then the buffered diff tail that overlaps it.
+     * This is the only path from `syncing`/`desynced` back to `live`.
+     * @internal
+     */
+    applySnapshot(snapshot: BookSnapshotInput): void;
+    /**
+     * Mark the book desynced without a gap event — the engine knows the stream
+     * was interrupted (a reconnect implies missed diffs by construction).
+     * @internal
+     */
+    markInterrupted(reason?: string): void;
+    private applyLiveDiff;
+    private emitUpdate;
+}
+
+/**
+ * v3 state platform — multi-symbol local book manager.
+ *
+ * The v2 `OrderBookEngine` wired books to a connection-centric WS class and
+ * re-ran the snapshot after subscribing. The v3 engine keeps the pure L2
+ * algorithm (it lives in `OrderBook`, unchanged) and rebuilds everything
+ * around it on the platform surfaces:
+ *
+ *  - streams come from the **pooled WS platform** (`core.ws.usdm/spot`) —
+ *    connection placement, renewal and reconnects are the platform's problem;
+ *  - snapshots come from the **shared REST transports** (`core.http(...)`) —
+ *    same weight budget, same mocks, same environment as everything else;
+ *  - the sync algorithm is the canonical Binance one: diffs buffer while the
+ *    first snapshot is in flight, and the tail that overlaps the snapshot
+ *    applies on top of it — no blind window, no resubscribe dance;
+ *  - an interrupted subscription marks the book desynced *immediately* (the
+ *    missed-diffs fact is known before any frame says so) and a resync with
+ *    backoff repairs it.
+ *
+ * ```ts
+ * const engine = new BookEngine({ core, product: 'usdm' });
+ * const book = await engine.watch('BTCUSDT');  // resolves once synced
+ * book.bestBid;                                 // exact decimal strings
+ * await engine.unwatch('BTCUSDT');
+ * engine.close();
+ * ```
+ */
+/** Options for {@link BookEngine}. */
+interface BookEngineOptions {
+    product: 'usdm' | 'spot';
+    /** Shared runtime: pooled WS subscriptions + REST snapshot transports. */
+    core: Pick<CoreContext, 'http' | 'events' | 'ws'>;
+    /** Diff update speed; default `100ms`. */
+    updateSpeed?: '100ms' | '500ms';
+    /** REST snapshot depth (levels); default 1000. */
+    snapshotLimit?: number;
+    /** Backoff between resync attempts after a desync. Default 1000ms. */
+    resyncDelayMs?: number;
+    /** Per-book tuning (diff buffer size). */
+    book?: ManagedBookOptions;
+}
+/**
+ * Manages {@link ManagedBook}s across symbols on one product's stream family.
+ *
+ * Books are per-engine and per-symbol (a second `watch` of a live symbol
+ * returns the existing book). The engine holds no sockets of its own — every
+ * subscription rides the pooled platform connection, so depth streams share
+ * connections with everything else the context runs.
+ */
+declare class BookEngine {
+    readonly product: 'usdm' | 'spot';
+    private readonly core;
+    private readonly updateSpeed;
+    private readonly snapshotLimit;
+    private readonly resyncDelayMs;
+    private readonly bookOptions?;
+    private readonly events?;
+    private readonly books;
+    private readonly subscriptions;
+    /** Symbols with a resync in flight (dedup per symbol). */
+    private readonly resyncing;
+    private readonly messageHandler;
+    private closed;
+    constructor(options: BookEngineOptions);
+    /**
+     * Start maintaining a local book for `symbol`: subscribe the pooled depth
+     * stream, buffer diffs, fetch the REST snapshot, apply the overlap, go
+     * live. Resolves once the book is synced; throws (after unsubscribing)
+     * when the snapshot cannot be fetched.
+     */
+    watch(symbol: string): Promise<ManagedBook>;
+    /**
+     * Stop maintaining a symbol: close the book and release its subscription
+     * (refcounted — the server-level UNSUBSCRIBE fires only for the last
+     * consumer). Idempotent; unknown symbols are a no-op.
+     */
+    unwatch(symbol: string): Promise<void>;
+    /** The managed book for a symbol, if watching. */
+    getBook(symbol: string): ManagedBook | undefined;
+    /** All watched symbols (insertion order). */
+    symbols(): string[];
+    /** True while the engine is usable (not terminally closed). */
+    get isClosed(): boolean;
+    /** Close every book and release every subscription. Terminal; idempotent. */
+    close(): void;
+    /** The pooled stream family this product's depth streams ride on. */
+    private family;
+    /** Snapshot host: `fapi` (USDⓈ-M `/fapi/v1/depth`) or `spot` (`/api/v3/depth`). */
+    private snapshotHttp;
+    /** Fetch + apply one REST snapshot for a symbol. */
+    private snapshot;
+    /** One depth frame off the pooled subscription → the book for its symbol. */
+    private onDepthFrame;
+    /** Delayed, deduplicated resync after a desync. */
+    private scheduleResync;
+}
+
+/**
+ * v3 USDⓈ-M futures product client.
+ *
+ * The full product surface over a shared {@link CoreContext} — identical
+ * wiring to `client.futures` on the multi-product facade (same construction
+ * path, same `ExecutionManager`, same WS URLs), but standing alone:
+ *
+ * ```ts
+ * const usdm = new USDMClient(new CoreContext({ apiKey, apiSecret }));
+ * await usdm.core.syncTime();                  // shared clock sync
+ * const fill = await usdm.execution.placeOrder({
+ *   symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.01',
+ * });
+ * usdm.ws.bookTicker('BTCUSDT', handler);      // product WS surface
+ * usdm.close();                                // product-scoped cleanup
+ * ```
+ *
+ * What the v3 boundary adds over the v2 `createUSDMClient()` factory: the
+ * core context is caller-visible (`usdm.core`) — transports, credentials
+ * and the event bus are reachable without globals, and two product clients
+ * can share one context (one weight budget, one observability stream).
+ */
+declare class USDMClient implements ProductClient {
+    readonly product: "usdm";
+    readonly core: CoreContext;
+    private readonly surface;
+    private listenKeyValue;
+    private keepAliveInterval;
+    private executionPlatformValue;
+    private bookEngineValue;
+    private closed;
+    constructor(core: CoreContext);
+    get market(): UsdmSurface['market'];
+    get data(): UsdmSurface['data'];
+    get account(): UsdmSurface['account'];
+    get trading(): UsdmSurface['trading'];
+    get ops(): UsdmSurface['ops'];
+    /** Idempotent order placement with transport-failure reconciliation. */
+    get execution(): UsdmSurface['execution'];
+    get userStream(): UsdmSurface['userStream'];
+    get ws(): UsdmSurface['ws'];
+    get wsUser(): UsdmSurface['wsUser'];
+    get wsApi(): UsdmSurface['wsApi'];
+    /**
+     * The v3 execution platform: managed user-data stream session, live
+     * order/position feeds, and semantic retry classification. Lazily built —
+     * a REST-only caller never pays for it.
+     *
+     * ```ts
+     * await usdm.executionPlatform.startUserSession();
+     * usdm.executionPlatform.orders.get('nbsdk-…');
+     * usdm.executionPlatform.positions.get('BTCUSDT');
+     * ```
+     */
+    get executionPlatform(): ExecutionPlatform;
+    /**
+     * The v3 state platform for USDⓈ-M: managed local L2 books over the pooled
+     * WS platform + shared REST snapshot transports. Lazily built — a
+     * stream-only or REST-only caller never pays for it.
+     *
+     * ```ts
+     * const book = await usdm.books.watch('BTCUSDT');  // resolves once synced
+     * book.bestBid;                                     // exact decimal strings
+     * book.metrics();                                   // spread, imbalance, …
+     * await usdm.books.unwatch('BTCUSDT');
+     * ```
+     */
+    get books(): BookEngine;
+    /**
+     * Start the listen-key user-data stream: creates the key, schedules the
+     * 30-minute keep-alive, and opens the user WS. Scoped to this product —
+     * unlike the multi-product facade, no other product's sockets are touched.
+     */
+    startUserStream(): Promise<string>;
+    /** Close the user stream (timer, socket, and listen-key deletion). */
+    closeUserStream(): void;
+    /** Close this product's resources. Safe to call more than once. */
+    close(): void;
+}
+
+/**
+ * v3 Spot product client.
+ *
+ * The full Spot product surface over a shared {@link CoreContext} — identical
+ * wiring to `client.spot` on the multi-product facade (same construction
+ * path, same `ExecutionManager`, same WS URLs), but standing alone:
+ *
+ * ```ts
+ * const spot = new SpotClient(new CoreContext({ apiKey, apiSecret }));
+ * await spot.core.syncTime();                  // shared clock sync
+ * const fill = await spot.execution.placeOrder({
+ *   symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.01',
+ * });
+ * spot.ws.bookTicker('BTCUSDT', handler);      // product WS surface
+ * spot.close();                                 // product-scoped cleanup
+ * ```
+ *
+ * What the v3 boundary adds over the v2 `createSpotClient()` factory: the
+ * core context is caller-visible (`spot.core`) — transports, credentials
+ * and the event bus are reachable without globals, and two product clients
+ * can share one context (one weight budget, one observability stream). It
+ * also owns the v3 execution platform and the v3 state engine for Spot.
+ */
+declare class SpotClient implements ProductClient {
+    readonly product: "spot";
+    readonly core: CoreContext;
+    private readonly surface;
+    private listenKeyValue;
+    private keepAliveInterval;
+    private executionPlatformValue;
+    private bookEngineValue;
+    private closed;
+    constructor(core: CoreContext);
+    get market(): SpotSurface['market'];
+    get account(): SpotSurface['account'];
+    get trading(): SpotSurface['trading'];
+    /** Idempotent order placement with transport-failure reconciliation. */
+    get execution(): SpotSurface['execution'];
+    get userStream(): SpotSurface['userStream'];
+    get ws(): SpotSurface['ws'];
+    get wsUser(): SpotSurface['wsUser'];
+    get wsApi(): SpotSurface['wsApi'];
+    /**
+     * The v3 execution platform for Spot: managed user-data stream session,
+     * live order feeds, and semantic retry classification. Lazily built —
+     * a REST-only caller never pays for it.
+     *
+     * ```ts
+     * await spot.executionPlatform.startUserSession();
+     * spot.executionPlatform.orders.get('nbsdk-…');
+     * ```
+     */
+    get executionPlatform(): ExecutionPlatform;
+    /**
+     * The v3 state platform for Spot: managed local L2 books over the pooled
+     * WS platform + shared REST snapshot transports. Lazily built — a
+     * stream-only or REST-only caller never pays for it.
+     *
+     * ```ts
+     * const book = await spot.books.watch('BTCUSDT');  // resolves once synced
+     * book.bestBid;                                     // exact decimal strings
+     * book.metrics();                                   // spread, imbalance, …
+     * await spot.books.unwatch('BTCUSDT');
+     * ```
+     */
+    get books(): BookEngine;
+    /**
+     * Start the listen-key user-data stream: creates the key, schedules the
+     * 30-minute keep-alive, and opens the user WS. Scoped to this product —
+     * unlike the multi-product facade, no other product's sockets are touched.
+     */
+    startUserStream(): Promise<string>;
+    /** Close the user stream (timer, socket, and listen-key deletion). */
+    closeUserStream(): void;
+    /** Close this product's resources. Safe to call more than once. */
+    close(): void;
+}
+
+/**
+ * v3 COIN-M futures product client.
+ *
+ * The full COIN-M product surface over a shared {@link CoreContext} —
+ * identical wiring to `client.coinm` on the multi-product facade (same
+ * construction path, same resources, same WS URLs), but standing alone:
+ *
+ * ```ts
+ * const coinm = new CoinMClient(new CoreContext({ apiKey, apiSecret }));
+ * await coinm.core.syncTime();                  // shared clock sync
+ * const quote = await coinm.market.markPrice('BTCUSD_PERP');
+ * coinm.ws.bookTicker('BTCUSD_PERP', handler);   // product WS surface
+ * coinm.close();                                 // product-scoped cleanup
+ * ```
+ *
+ * What the v3 boundary adds over the v2 `createCoinMClient()` factory: the
+ * core context is caller-visible (`coinm.core`) — transports, credentials
+ * and the event bus are reachable without globals, and two product clients
+ * can share one context (one weight budget, one observability stream).
+ *
+ * **Note on the v3 execution platform / state engine:** COIN-M does not yet
+ * have its own `ExecutionPlatform` or `BookEngine` — those modules are
+ * currently wired for `'usdm' | 'spot'` only. The full surface (`market`,
+ * `account`, `trading`, `execution`, `userStream`, `ws`, `wsUser`) is here
+ * and runs over the shared transports; the managed user-data session and
+ * the L2 book engine for COIN-M are the next follow-up. Until then, the
+ * manual `startUserStream()` path (listen key + 30-minute keep-alive +
+ * user WS) is the way to consume COIN-M user data through this client.
+ */
+declare class CoinMClient implements ProductClient {
+    readonly product: "coinm";
+    readonly core: CoreContext;
+    private readonly surface;
+    private listenKeyValue;
+    private keepAliveInterval;
+    private closed;
+    constructor(core: CoreContext);
+    get market(): CoinMSurface['market'];
+    get account(): CoinMSurface['account'];
+    get trading(): CoinMSurface['trading'];
+    get userStream(): CoinMSurface['userStream'];
+    get ws(): CoinMSurface['ws'];
+    get wsUser(): CoinMSurface['wsUser'];
+    /**
+     * Start the listen-key user-data stream: creates the key, schedules the
+     * 30-minute keep-alive, and opens the user WS. Scoped to this product —
+     * unlike the multi-product facade, no other product's sockets are touched.
+     */
+    startUserStream(): Promise<string>;
+    /** Close the user stream (timer, socket, and listen-key deletion). */
+    closeUserStream(): void;
+    /** Close this product's resources. Safe to call more than once. */
+    close(): void;
+}
+
+/**
+ * Endpoint registry — machine-readable map of every REST endpoint this SDK
+ * implements, the single source of truth consumed by:
+ *
+ *  - `docs/endpoint-map/*.md` (generated by scripts/generate-endpoint-map.ts)
+ *  - `llms.txt` / `llms-full.txt` (agent-facing docs, also generated)
+ *  - tooling/CI (coverage accounting vs. Binance's published API surface)
+ *
+ * Registry entries are hand-curated but mechanically *checked*: the
+ * `scripts/generate-endpoint-map.ts` script greps `src/resources` for live
+ * `http.<verb>(...)` calls and fails when a registered endpoint is not
+ * actually implemented (or vice versa), so the map cannot drift silently.
+ */
+type EndpointAuth = 'public' | 'apiKey' | 'signed';
+type EndpointMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+interface EndpointEntry {
+    /** Binance product family. */
+    product: 'spot' | 'usdm' | 'coinm' | 'margin' | 'wallet' | 'subaccount';
+    /** SDK surface implementing it, e.g. `futures.trading.createOrder`. */
+    operation: string;
+    method: EndpointMethod;
+    path: string;
+    authentication: EndpointAuth;
+    /** Documented request weight where known (IP weight unless noted). */
+    weight?: number;
+    /** Resource class + method implementing the call. */
+    implementedBy: string;
+}
+/** Every implemented endpoint, across all products. */
+declare const ENDPOINT_REGISTRY: readonly EndpointEntry[];
+interface EndpointQuery {
+    product?: EndpointEntry['product'];
+    method?: EndpointMethod;
+    authentication?: EndpointAuth;
+    pathPrefix?: string;
+}
+declare function listEndpoints(query?: EndpointQuery): readonly EndpointEntry[];
+declare function findEndpoint(path: string, method?: EndpointMethod): EndpointEntry | undefined;
+/** Per-product coverage counts for docs/CI. */
+declare function endpointCounts(): Record<string, number>;
+
+/**
+ * API contract layer — the machine-readable view of the Binance REST surface
+ * this SDK implements.
+ *
+ * The registry (src/registry) already lists every endpoint (operation, method,
+ * path, authentication, implementer). This layer is the *contract* consumers
+ * build on top of that list:
+ *
+ *  - normalized **security schemes** (`none` / `apiKey` / `signature`) instead
+ *    of ad-hoc auth strings;
+ *  - **declared request weights** for the endpoints where Binance documents a
+ *    param-independent weight — informational only, response headers
+ *    (`X-MBX-USED-WEIGHT-*`) remain the source of truth for accounting;
+ *  - **path canonicalization** so a bare resource path (`/order`) resolves to
+ *    the registry's canonical form (`/api/v3/order`) using the HttpClient's
+ *    base URL — this is what lets the observability bus attach contract
+ *    metadata to every `http.request.*` event;
+ *  - a single query API (`getContract`, `findContract`, `listContracts`) for
+ *    tooling, docs generation and agent-facing surfaces.
+ *
+ * This is the stepping stone toward a fully generated contract layer (OpenAPI
+ * spec → typed clients); the query surface below is deliberately shaped so a
+ * generated implementation can replace the hand-curated backing store without
+ * changing any consumer.
+ */
+
+/** Normalized security scheme an endpoint requires. */
+type EndpointSecurityScheme = 'none' | 'apiKey' | 'signature';
+/**
+ * A single endpoint's contract: registry entry + normalized security scheme +
+ * declared weight (where Binance documents a param-independent one).
+ */
+interface EndpointContract extends EndpointEntry {
+    security: EndpointSecurityScheme;
+    /** Documented request weight where param-independent; see file docs. */
+    declaredWeight?: number;
+}
+/**
+ * Resolve a resource-supplied path against an HttpClient base URL to the
+ * registry's canonical path. Bare paths (`/order`) are prefixed with the base
+ * URL's own path segment (`https://…/api/v3` → `/api/v3/order`); paths that
+ * already carry a version prefix pass through unchanged.
+ */
+declare function canonicalPath(baseURL: string, path: string): string;
+/** Contract for a canonical path + method, or undefined when unknown. */
+declare function findContract(canonical: string, method?: EndpointMethod): EndpointContract | undefined;
+/** Contract lookup by product + operation, e.g. ('spot', 'trading.createOrder'). */
+declare function getContract(product: EndpointEntry['product'], operation: string): EndpointContract | undefined;
+/** Contract metadata attached to `http.request.*` observability events. */
+interface HttpContractMeta {
+    product: EndpointEntry['product'];
+    operation: string;
+    authentication: EndpointAuth;
+    security: EndpointSecurityScheme;
+    declaredWeight: number | undefined;
+}
+/**
+ * Resolve the contract for a request as the HttpClient sees it: base URL +
+ * method + resource path. Returns undefined for unregistered paths (e.g.
+ * host-level time endpoints reused across products).
+ */
+declare function contractFor(baseURL: string, method: string, path: string): HttpContractMeta | undefined;
+/** One-line human description, for logs and agent-facing docs. */
+declare function describeContract(contract: EndpointContract): string;
+
+/** The pooled connection classes the platform already ships per family. */
+type PooledConnection = FuturesMarketWS | SpotMarketWS | CoinMMarketWS;
+interface FamilyConnectionPoolOptions {
+    family: WsFamily;
+    /** Combined-stream base URL for the family (from core.endpoints). */
+    baseStreamUrl: string;
+    /** Cap on pooled connections; default is the family's documented default. */
+    maxConnections?: number;
+    /** Reconnect backoff; default jittered exponential. */
+    reconnectPolicy?: ReconnectPolicy;
+    /** Observability bus. */
+    events?: EventBus;
+    /** Injectable WebSocket factory for tests. */
+    socketFactory?: (url: string) => WebSocket;
+    /** Control-request ack timeout. Default 10s. */
+    requestTimeoutMs?: number;
+    /**
+     * Called exactly once per created connection so the platform can wire
+     * heartbeat liveness and centralized renewal (the pool itself never
+     * schedules timers beyond the connection's own reconnect backoff).
+     */
+    onConnection?: (name: string, conn: PooledConnection) => void;
+}
+/**
+ * Capacity-aware connection pool for one market-stream family.
+ *
+ * Binance documents a per-connection stream ceiling (200 for futures, 1024
+ * for spot); the pool packs streams onto the least-loaded connection with
+ * capacity and opens another connection (up to `maxConnections`) when every
+ * existing one is full — so a 500-stream workload spreads across 3 USDⓈ-M
+ * connections automatically instead of failing server-side.
+ *
+ * Pool-managed connections:
+ *  - disable the built-in 23h rotation timer (renewal is centralized in
+ *    {@link RenewalController} for stagger and observability);
+ *  - disable the built-in liveness watchdog (pool-level {@link WsHeartbeat}
+ *    uses one timer for all connections);
+ *  - use the platform reconnect policy (jittered backoff, so a pool-wide
+ *    outage does not retry in lockstep).
+ */
+declare class FamilyConnectionPool {
+    readonly family: WsFamily;
+    private readonly baseStreamUrl;
+    private readonly maxConnections;
+    private readonly maxStreamsPerConnection;
+    private readonly events?;
+    private readonly socketFactory?;
+    private readonly requestTimeoutMs;
+    private readonly onConnection?;
+    private readonly createConnection;
+    private readonly pool;
+    constructor(options: FamilyConnectionPoolOptions);
+    /**
+     * Pick the connection that should carry `newStreams` — the least-loaded one
+     * with capacity, or a newly created one. Creates never perform I/O: the
+     * returned connection connects lazily on first `subscribe()`.
+     *
+     * Throws when every connection is at the documented stream ceiling and the
+     * `maxConnections` cap is reached — the caller is over the family's
+     * capacity and must raise the cap.
+     */
+    selectOrCreate(newStreams: readonly string[]): PooledConnection;
+    /** Live pooled connections (copy). */
+    connections(): PooledConnection[];
+    /** Number of pooled connections. */
+    size(): number;
+    /** Structural snapshot (cheap, no I/O). */
+    stats(): WsConnectionStats[];
+    /** Close every pooled connection. Safe repeatedly. */
+    closeAll(): void;
+    /** Next pool-assigned connection name, e.g. `usdmMarket[3]`. */
+    private nextName;
+}
+
+/**
+ * Stream-level routing over one family's connection pool.
+ *
+ * Responsibilities:
+ *
+ *  - **Refcounting** — N `Subscription` objects for one stream name share a
+ *    single server-level subscription; the last `close()` issues the protocol
+ *    UNSUBSCRIBE.
+ *  - **Fan-out** — one `message` listener per pooled connection dispatches
+ *    frames to every live subscription for that stream (parsed payload plus
+ *    lossless raw view).
+ *  - **Reconnect transparency** — when a pooled connection drops, its
+ *    subscriptions flip to `pending`; after the connection's own repair
+ *    (reconnect or rotation, followed by its resynchronize pass) the registry
+ *    re-marks every server-confirmed stream `live`.
+ *
+ * The registry never subscribes the same stream on two connections of the
+ * same family — a stream maps to exactly one connection while it has
+ * subscribers.
+ */
+declare class FamilySubscriptionRegistry {
+    private readonly pool;
+    private readonly events?;
+    private readonly confirmTimeoutMs;
+    private readonly mappings;
+    /** Connections whose dispatch listeners are attached (bounded by pool cap). */
+    private readonly attached;
+    constructor(options: {
+        pool: FamilyConnectionPool;
+        events?: EventBus;
+        requestTimeoutMs?: number;
+    });
+    /**
+     * Acquire a subscription for one stream, confirming it server-side. When
+     * the stream already has subscribers this is a pure fan-out join (no I/O).
+     *
+     * Rejects when confirmation does not arrive within `confirmTimeoutMs`;
+     * the subscription stays registered in that case — it flips to `live` via
+     * the reconnect/repair path and remains reachable through
+     * {@link FamilySubscriptionRegistry.getSubscription}.
+     */
+    acquire(stream: string, options?: SubscribeOptions): Promise<Subscription>;
+    private doAcquire;
+    /**
+     * Release a subscription (refcount down). The last release for a stream
+     * removes the mapping and issues the protocol UNSSUBSCRIBE (best-effort —
+     * desired state is already dropped, so reconnects will not resurrect it).
+     * Invoked automatically by {@link Subscription.close}.
+     */
+    release(subscription: Subscription): void;
+    /** Active subscription object for a stream, if one is registered. */
+    getSubscription(stream: string): Subscription | undefined;
+    /** Streams with at least one live subscription. */
+    activeStreams(): string[];
+    /** Registry snapshot: streams per connection. */
+    stats(): {
+        streams: number;
+        connections: number;
+    };
+    /** Close every subscription (platform teardown). */
+    closeAll(): void;
+    private attach;
+    private markConnectionPending;
+    private refreshConfirmed;
+}
+
+/**
+ * Minimal connection surface the heartbeat needs — implemented by
+ * {@link WsConnection} and satisfiable by test stubs.
+ */
+interface HeartbeatWatch {
+    /** Connection label for events. */
+    name?: string;
+    getState(): string;
+    /** ms since the last inbound frame; Infinity when never opened. */
+    msSinceLastActivity(): number;
+    /** Tear down into the reconnect path. */
+    reconnect(): void;
+}
+interface WsHeartbeatOptions {
+    /** Silence threshold that declares a connection dead. Default 10 min. */
+    staleMs?: number;
+    /** Sampling interval. Default 30s. */
+    intervalMs?: number;
+    /** Observability bus. */
+    events?: EventBus;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Injectable timer for tests (returns an unref-able handle). */
+    setInterval?: (fn: () => void, ms: number) => {
+        unref?: () => void;
+    };
+}
+/**
+ * Pool-level liveness watchdog with a *single* timer.
+ *
+ * `WsConnection` already supports per-connection `staleMs`, but v3 platforms
+ * watch dozens of sockets; one tick beats N setInterval handles, and the
+ * judgment (server pings every 3 minutes → 10 minutes of total silence means
+ * the path is dead) lives in exactly one place. Protocol-level activity
+ * (pings/pongs) counts as liveness via `msSinceLastActivity`.
+ *
+ * When a connection goes stale the heartbeat does not wait for TCP to notice:
+ * it calls `reconnect()` (terminate + fresh socket), which is the correct
+ * response to a half-open path.
+ */
+declare class WsHeartbeat {
+    private readonly staleMs;
+    private readonly intervalMs;
+    private readonly events?;
+    private readonly now;
+    private readonly timerFn;
+    private readonly watched;
+    private timer;
+    constructor(options?: WsHeartbeatOptions);
+    /** Start watching a connection under a stable key. */
+    watch(key: string, conn: HeartbeatWatch): void;
+    /** Stop watching (connection closed or pooled away). */
+    unwatch(key: string): void;
+    /** True when currently watched. */
+    isWatching(key: string): boolean;
+    /** Number of watched connections. */
+    size(): number;
+    /** Run one check immediately (also the interval body). */
+    check(): {
+        stale: string[];
+    };
+    start(): void;
+    stop(): void;
+    private ensureTicking;
+}
+
+/**
+ * Minimal connection surface the renewal controller needs — implemented by
+ * {@link WsConnection} (an EventEmitter) and satisfiable by test stubs.
+ *
+ * Zero-gap rotation is transparent in the state machine: the connection stays
+ * OPEN while the replacement connects, so completion is signalled by the
+ * `rotated` / `rotationFailed` emitter events, not by state transitions.
+ */
+interface RenewableConnection {
+    on(event: 'state', listener: (to: string, from: string) => void): unknown;
+    on(event: 'rotated', listener: () => void): unknown;
+    on(event: 'rotationFailed', listener: (info: {
+        code: number;
+        reason: string;
+    }) => void): unknown;
+    off(event: 'state', listener: (to: string, from: string) => void): unknown;
+    off(event: 'rotated', listener: () => void): unknown;
+    off(event: 'rotationFailed', listener: (info: {
+        code: number;
+        reason: string;
+    }) => void): unknown;
+    getState(): string;
+    /** Attempt a zero-gap rotation; false when not applicable. */
+    rotateNow(): boolean;
+}
+interface RenewalControllerOptions {
+    /**
+     * Renewal window. Binance kills stream connections at 24h; the platform
+     * rotates at 23h so the replacement carries traffic *before* the drop.
+     * Default 23h.
+     */
+    rotationMs?: number;
+    /**
+     * Per-connection jitter (uniform [0, jitterMs)). Two connections opened in
+     * the same millisecond would otherwise renew in the same millisecond — a
+     * synchronized herd. Default 10 min.
+     */
+    jitterMs?: number;
+    /**
+     * Platform-wide cap on simultaneous renewals; the default 1 serializes
+     * rotations so a pool of N connections renews one at a time.
+     */
+    maxConcurrent?: number;
+    /** Observability bus. */
+    events?: EventBus;
+    /** Injectable randomness for tests; must return [0, 1). */
+    random?: () => number;
+    /** Injectable timer for tests. */
+    setTimeout?: (fn: () => void, ms: number) => {
+        unref?: () => void;
+    };
+    /** Postponement/retry interval. Default 30s. */
+    retryMs?: number;
+}
+/**
+ * Centralized, staggered 24h-safe renewal sequencing.
+ *
+ * `WsConnection` has a built-in 23h rotation timer; pool-managed connections
+ * disable it (`rotationMs: 0`) and defer to this controller because:
+ *
+ *  - **Decorrelation** — every connection gets a uniform jitter on top of the
+ *    23h window, so a pool created at boot rotates across a spread, not a
+ *    synchronized herd.
+ *  - **Concurrency cap** — at most `maxConcurrent` rotations platform-wide;
+ *    a herd forced to serialize is a blip, not an event.
+ *  - **Observability** — `nextRenewalAt(name)` and `ws.renewal.*` events make
+ *    the rotation schedule inspectable instead of a hidden timer per socket.
+ *
+ * Renewals are zero-gap: the connection swaps sockets internally (traffic
+ * keeps flowing on the old one until the replacement is open).
+ */
+declare class RenewalController {
+    private readonly rotationMs;
+    private readonly jitterMs;
+    private readonly maxConcurrent;
+    private readonly events?;
+    private readonly random;
+    private readonly setTimeoutFn;
+    private readonly retryMs;
+    private readonly tracked;
+    constructor(options?: RenewalControllerOptions);
+    /**
+     * Start centrally managing renewal for a connection. Scheduling anchors on
+     * the connection reaching OPEN (or immediately, if already open), so a
+     * tracked-but-not-yet-connected socket does not burn its rotation window.
+     */
+    track(name: string, conn: RenewableConnection): void;
+    /** Stop managing a connection; safe to call for unknown names. */
+    untrack(name: string): void;
+    /** Epoch-ms of the next scheduled renewal, or null when idle/closed. */
+    nextRenewalAt(name: string): number | null;
+    /** True while a renewal is in flight for this connection. */
+    isRenewing(name: string): boolean;
+    /** Number of centrally managed connections. */
+    size(): number;
+    /** Stop managing everything. */
+    close(): void;
+    private scheduleRenewal;
+    private fireRenewal;
+    private countInFlight;
+}
+
+/**
+ * Reconnect backoff strategies.
+ *
+ * v2's {@link WsConnection} hard-coded `min(base * 2^attempt, max)`. The
+ * platform keeps that as the default shape but makes it pluggable and adds
+ * jitter: a reconnect storm (e.g. Binance restarting an edge) hits every
+ * connection at once, and deterministic identical delays make the herd
+ * collide on every subsequent attempt too. *Equal jitter* — half fixed, half
+ * random — keeps the first retry responsive while decorrelating the herd.
+ */
+interface ExponentialBackoffOptions {
+    /** First-attempt delay. Default 1000ms. */
+    baseMs?: number;
+    /** Ceiling. Default 30000ms. */
+    maxMs?: number;
+    /** Random decorrelation; defaults on. Disable for deterministic tests. */
+    jitter?: boolean;
+    /** Injectable randomness for tests; must return [0, 1). */
+    random?: () => number;
+}
+/**
+ * Exponential backoff with equal jitter (default policy):
+ * `raw = min(base * 2^attempt, max)`; returned delay is
+ * `raw/2 + random() * raw/2` — always ≥ raw/2, ≤ raw.
+ */
+declare function exponentialBackoff(options?: ExponentialBackoffOptions): ReconnectPolicy;
+/** Constant delay — reconnects at a fixed cadence regardless of attempt. */
+declare function fixedBackoff(delayMs: number): ReconnectPolicy;
+/** Linear backoff: `base * (attempt + 1)`, capped at `maxMs`. */
+declare function linearBackoff(options?: {
+    baseMs?: number;
+    maxMs?: number;
+}): ReconnectPolicy;
+
+/**
+ * Semantic retry classification for order operations.
+ *
+ * "Can I retry this?" is the first question every caller of a trading SDK
+ * asks after an error, and the honest answer depends on *which* failure
+ * occurred, not on generic error taxonomy:
+ *
+ *  - a timeout on order placement leaves the outcome unknown — the order may
+ *    be live; retrying blind can double the position (`reconciliation-required`);
+ *  - a `-2013` after an ambiguous submission *proves* the order never reached
+ *    the engine — resubmission is free of risk (`safe`);
+ *  - `-1013` filter rejections are deterministic — the identical request
+ *    fails forever (`never-retry`).
+ *
+ * This module makes the SDK's answer explicit and testable. The execution
+ * manager already *embodies* this matrix (its resubmit-after-`-2013` path is
+ * the 'safe' branch; its `ExecutionUnknownError` is 'reconciliation-required'
+ * made fatal); the classifier exposes the same reasoning to callers holding
+ * raw errors, so agents and tools can decide without reimplementing it.
+ *
+ * Note on `'idempotent'`: the live exchange never earns it — Binance does not
+ * enforce `newClientOrderId` uniqueness, so a "retry with the same key" is not
+ * distinguishable from a second order. The category exists for backends whose
+ * create operation is genuinely keyed (paper engines, future brokers).
+ */
+/** Classify one error for retry semantics against the live exchange. */
+declare function classifyRetrySafety(error: unknown): RetryClassification;
+/** Narrow helper for switch-style consumers. */
+declare function isRetrySafety(value: unknown): value is RetrySafety;
+
+/**
+ * v3 paper execution platform — the assembled paper runtime.
+ *
+ * See `PaperSession.ts` for the session that replays simulator fills as
+ * user-data frames; this module is the one-call wiring of the whole stack:
+ * simulator + adapter + execution manager + execution platform, over one
+ * shared {@link CoreContext}. Use {@link createPaperExecutionPlatform}.
+ */
+/** Options for {@link createPaperExecutionPlatform}. */
+interface PaperExecutionPlatformOptions extends PaperTradingOptions {
+    /**
+     * Report source wiring: pass an adapter when one already routes this engine
+     * (e.g. an existing gateway); a fresh one is built otherwise. The platform
+     * registers its own listener — since M4, paper reports fan out to every
+     * listener, so an execution manager over the same adapter keeps working.
+     */
+    adapter?: PaperExecutionAdapter;
+}
+/** The assembled paper execution platform. */
+interface PaperExecutionPlatform {
+    /** Execution platform in paper mode — session, trackers, classify, reconcile. */
+    platform: ExecutionPlatform;
+    /** Paper-backed execution manager: idempotent place/cancel/reconcile. */
+    execution: ExecutionManager;
+    /** The simulator engine (account, positions, order history). */
+    engine: PaperTradingEngine;
+    /** The adapter orders flow through. */
+    adapter: PaperExecutionAdapter;
+}
+/**
+ * Build a complete paper trading runtime over a shared {@link CoreContext}:
+ * simulator + adapter + execution manager + execution platform, all wired.
+ *
+ * This is "paper as a first-class execution backend": the same
+ * {@link ExecutionPlatform} boundary live trading uses, with the simulator in
+ * the server seat. Market prices come through the shared core transports
+ * (testnet/demo envs and request mocks apply), so a paper run is the live
+ * run with the matching engine swapped out.
+ *
+ * ```ts
+ * const core = new CoreContext({ apiKey, apiSecret });
+ * const paper = createPaperExecutionPlatform(core, { initialBalance: 25_000 });
+ *
+ * await paper.platform.startUserSession();      // no network — local session
+ * const fill = await paper.execution.placeOrder({
+ *   symbol: 'BTCUSDT', side: 'BUY', type: 'MARKET', quantity: '0.01',
+ * });
+ * // the fill is already folded — same API as live:
+ * paper.platform.orders.get(fill.clientOrderId);   // OrderRecord (status: FILLED)
+ * paper.platform.positions.get('BTCUSDT');         // PositionRecord (signed amount)
+ * ```
+ */
+declare function createPaperExecutionPlatform(core: CoreContext, options?: PaperExecutionPlatformOptions): PaperExecutionPlatform;
 
 declare class BinanceError extends Error {
     constructor(message: string);
 }
 
 declare class BinanceAuthError extends BinanceError {
-    readonly missing: 'apiKey' | 'apiSecret';
-    constructor(missing: 'apiKey' | 'apiSecret');
+    readonly missing: 'apiKey' | 'apiSecret' | 'privateKey';
+    constructor(missing: 'apiKey' | 'apiSecret' | 'privateKey');
 }
 
+interface BinanceApiErrorContext {
+    endpoint?: string;
+    method?: string;
+    headers?: Record<string, string>;
+}
 declare class BinanceApiError extends BinanceError {
     readonly code: number;
     readonly status: number;
-    constructor(message: string, code: number, status: number);
+    readonly endpoint?: string;
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    constructor(message: string, code: number, status: number, context?: BinanceApiErrorContext);
+    /** -1003 (way too many requests) or HTTP 429/418. */
+    isRateLimitError(): boolean;
+    /** -1021: request timestamp outside recvWindow, usually caused by local clock drift. */
+    isTimestampError(): boolean;
+    /** -2010: account has insufficient balance for the requested action. */
+    isInsufficientBalance(): boolean;
 }
 
 declare class RateLimitError extends BinanceApiError {
     readonly retryAfterMs?: number;
-    constructor(message: string, code: number, status: number, retryAfterMs?: number);
+    constructor(message: string, code: number, status: number, retryAfterMs?: number, context?: BinanceApiErrorContext);
 }
 
 declare class NetworkError extends BinanceError {
@@ -320,8 +1947,41 @@ declare class NetworkError extends BinanceError {
     constructor(message: string, cause?: unknown);
 }
 
-declare function createBinanceMcpServer(client: BinanceClient): McpServer;
+type PolicyRule = 'readOnly' | 'symbolNotAllowed' | 'maxNotionalPerOrder' | 'notionalUndeterminable' | 'withdrawalsBlocked' | 'transfersBlocked' | 'blockedPath' | 'circuitBreaker' | 'maxLeverage' | 'maxOpenNotional' | 'maxDailyLoss';
+/**
+ * Thrown when a request is refused by the client's own {@link TradingPolicy} — before it
+ * ever reaches Binance. Distinct from BinanceApiError, which reports an exchange rejection.
+ */
+declare class PolicyViolationError extends BinanceError {
+    readonly rule: PolicyRule;
+    readonly method: string;
+    readonly endpoint: string;
+    readonly details?: Record<string, unknown>;
+    constructor(rule: PolicyRule, message: string, method: string, endpoint: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown instead of sending a mutating request when the client is in dry-run mode.
+ *
+ * Dry run deliberately throws rather than returning a synthetic success payload: a fabricated
+ * orderId would lead an agent to believe an order exists and then try to manage or cancel it.
+ * Failing loudly — while carrying the exact request that *would* have been sent — is the only
+ * safe signal. Tool layers should catch this and surface `describe()` back to the model.
+ */
+declare class DryRunError extends BinanceError {
+    readonly method: string;
+    readonly endpoint: string;
+    readonly params: Record<string, unknown>;
+    constructor(method: string, endpoint: string, params?: Record<string, unknown>);
+    /** Human/LLM-readable description of the suppressed request. */
+    describe(): string;
+}
 
-declare const VERSION = "2.1.0";
+/**
+ * MCP server over the toolkit. Pass `toolkit: { executionBackend: 'paper' }`
+ * to route every order tool through the simulator — safe to expose to any
+ * host without API-key trading risk.
+ */
+declare function createBinanceMcpServer(client: BinanceClient, options?: FuturesToolkitOptions): McpServer;
 
-export { BinanceApiError, BinanceAuthError, BinanceClient, BinanceError, type Endpoints, type Environment, FuturesMarket, NetworkError, type PaperAccount, type PaperOrder, type PaperPosition, type PaperPositionSide, PaperTradingEngine, type PaperTradingOptions, RateLimitError, VERSION, type WsAggTradePayload, WsAggTradePayloadSchema, type WsAssetIndexPayload, WsAssetIndexPayloadSchema, type WsBookTickerPayload, WsBookTickerPayloadSchema, type WsCompositeIndexPayload, WsCompositeIndexPayloadSchema, type WsDepthUpdatePayload, WsDepthUpdatePayloadSchema, type WsForceOrderPayload, WsForceOrderPayloadSchema, type WsKlinePayload, WsKlinePayloadSchema, type WsMarkPricePayload, WsMarkPricePayloadSchema, type WsMiniTickerPayload, WsMiniTickerPayloadSchema, type WsRollingWindowTickerPayload, WsRollingWindowTickerPayloadSchema, type WsSpotAvgPricePayload, WsSpotAvgPricePayloadSchema, type WsStreamPayload, type WsTicker24hrPayload, WsTicker24hrPayloadSchema, type WsTradePayload, WsTradePayloadSchema, createBinanceMcpServer, parseWsPayload, resolveEnvironment };
+export { BinanceApiError, type BinanceApiErrorContext, BinanceAuthError, BinanceClient, BinanceClientOptions, BinanceError, BookEngine, type BookEngineOptions, BookLevel, BookSnapshotInput, type BookSyncEvent, type BookUpdateEvent, CoinMClient, CoinMMarketWS, CoinMSurface, CoreContext, CreateOrderParams, DiffInput, DryRunError, ENDPOINT_REGISTRY, EXECUTION_PLATFORM_DEFAULTS, type EndpointAuth, type EndpointContract, type EndpointEntry, type EndpointMethod, type EndpointQuery, type EndpointSecurityScheme, EventBus, ExecutionAdapter, ExecutionFill, ExecutionManager, ExecutionPlatform, type ExecutionPlatformOptions, ExecutionReportShape, type ExponentialBackoffOptions, FamilyConnectionPool, type FamilyConnectionPoolOptions, FamilySubscriptionRegistry, FuturesMarketWS, FuturesToolkitOptions, type HttpContractMeta, type ListenKeyApi, ManagedBook, type ManagedBookOptions, type ManagedBookState, NetworkError, OrderBookMetrics, OrderKey, type OrderRecord, OrderShape, type OrderStatus, OrderTracker, type OrderTrackerOptions, type OrderUpdate, type PaperBackendOptions, PaperExecutionAdapter, type PaperExecutionPlatform, type PaperExecutionPlatformOptions, PaperSession, type PaperSessionOptions, PaperTradingEngine, PaperTradingOptions, type PlatformUserSession, type PolicyRule, PolicyViolationError, type PooledConnection, type PositionRecord, PositionTracker, type PositionTrackerOptions, type PositionUpdate, type ProductClient, type ProductFactory, type ProductId, RateLimitError, type ReconcileOptions, type ReconcileTarget, type ReconciliationSummary, ReconnectPolicy, type RenewableConnection, RenewalController, type RenewalControllerOptions, type RetryClassification, type RetrySafety, SpotClient, SpotMarketWS, SpotSurface, type CoinMClient$1 as StandaloneCoinMClient, type SpotClient$1 as StandaloneSpotClient, type USDMClient$1 as StandaloneUSDMClient, SubscribeOptions, Subscription, USDMClient, UsdmSurface, type UserEventParser, type UserSessionState, type UserSessionTuning, UserStreamLike, UserStreamSession, type UserStreamSessionOptions, VERSION, WsConnection, WsConnectionOptions, WsConnectionStats, WsFamily, WsHeartbeat, type WsHeartbeatOptions, canonicalPath, classifyRetrySafety, contractFor, createBinanceMcpServer, createCoinMClient, createPaperExecutionPlatform, createSpotClient, createUSDMClient, createUserEventParser, decimalString, describeContract, endpointCounts, exponentialBackoff, findContract, findEndpoint, fixedBackoff, getContract, isProductClient, isRetrySafety, isTerminalOrderStatus, linearBackoff, listEndpoints, normalizeIntStrings, orderShapeFromSpotOpenOrder, orderShapeFromUsdmOpenOrder, paperAccountUpdateFrame, paperOrderTradeUpdateFrame, parseJsonLossless, parseJsonLosslessAs, positionUpdatesFromPositionRisk, reconcileExecutionPlatform };