import WebSocket from 'isomorphic-ws'; import { KlineInterval } from './types/shared'; import { Exact, WsAPIOperationResponseMap, WsAPITopicRequestParamMap, WsAPIWsKeyTopicMap, WsOperation, WsRequestOperationBinance } from './types/websockets/ws-api'; import { MessageEventLike, WSClientConfigurableOptions, WsMarket, WsTopic } from './types/websockets/ws-general'; import { BaseWebsocketClient, EmittableEvent, MidflightWsRequestEvent } from './util/BaseWSClient'; import { DefaultLogger } from './util/logger'; import { MiscUserDataConnectionState, WSAPIWsKey, WsKey, WsTopicRequest } from './util/websockets/websocket-util'; import { WSConnectedResult } from './util/websockets/WsStore.types'; export interface WSAPIRequestFlags { /** If true, will skip auth requirement for WS API connection */ authIsOptional?: boolean | undefined; } /** * Multiplex Node.js, JavaScript & TypeScript Websocket Client for all of Binance's available WebSockets. * * When possible, it will subscribe to all requested topics on a single websocket connection. A list of * all available streams can be seen in the WS_KEY_URL_MAP found in util/websockets/websocket-util.ts. * * Connectivity is automatically maintained. If disconnected, the WebsocketClient will automatically * clean out the old dead connection, respawn a fresh one and resubscribe to all the requested topics. * * If any connection is reconnected, the WS client will: * - Emit the "reconnecting" event when the process begins. * - Emit the "reconnected" event, when the process has completed. When this event arrives, it is often a * good time to execute any synchorisation workflow (e.g. via the REST API) if any information was missed * while disconnected. * * User data streams will use a dedicated connection per stream for increased resilience. */ export declare class WebsocketClient extends BaseWebsocketClient> { private restClientCache; private beautifier; private userDataStreamManager; private respawnTimeoutCache; constructor(options?: WSClientConfigurableOptions, logger?: DefaultLogger); private getUserDataStreamManager; private getRestClientOptions; /** * Request connection of all dependent (public & WS API) websockets in prod, instead of waiting * for automatic connection by SDK. * * For the Binance SDK, this will only open public connections (without auth), but is almost definitely overkill if you're only working with one product group. */ connectAll(): Promise[]; /** * Request connection to all public websockets in prod (spot, margin, futures, options). Overkill if * you're only working with one product group. */ connectPublic(): Promise[]; /** * This function serves no purpose in the Binance SDK */ connectPrivate(): Promise; /** * Ensures the WS API connection is active and ready. * * You do not need to call this, but if you call this before making any WS API requests, * it can accelerate the first request (by preparing the connection in advance). */ connectWSAPI(wsKey: WSAPIWsKey, skipAuth?: boolean): Promise; /** * Request subscription to one or more topics. Pass topics as either an array of strings, * or array of objects (if the topic has parameters). * * Objects should be formatted as {topic: string, params: object, category: CategoryV5}. * * - Subscriptions are automatically routed to the correct websocket connection. * - Authentication/connection is automatic. * - Resubscribe after network issues is automatic. * * Call `unsubscribe(topics)` to remove topics */ subscribe(requests: (WsTopicRequest | WsTopic) | (WsTopicRequest | WsTopic)[], wsKey: WsKey): Promise; /** * Unsubscribe from one or more topics. Similar to subscribe() but in reverse. * * - Requests are automatically routed to the correct websocket connection. * - These topics will be removed from the topic cache, so they won't be subscribed to again. */ unsubscribe(requests: (WsTopicRequest | WsTopic) | (WsTopicRequest | WsTopic)[], wsKey: WsKey): Promise; /** * * * * WS API Methods - similar to the REST API, but via WebSockets * https://developers.binance.com/docs/binance-spot-api-docs/websocket-api/general-api-information * * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/REST-API-vs-WebSockets-vs-WebSocket-API * * * */ /** * Send a Websocket API command/request on a connection. Returns a promise that resolves on reply. * * WS API Documentation for list of operations and parameters: * * - Spot: https://developers.binance.com/docs/binance-spot-api-docs/websocket-api/general-api-information * - USDM Futures: https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-api-general-info * - COINM Futures: https://developers.binance.com/docs/derivatives/coin-margined-futures/websocket-api-general-info * * * Returned promise is rejected if: * - an exception is detected in the reply, OR * - the connection disconnects for any reason (even if automatic reconnect will happen). * * Authentication is automatic. If you didn't request authentication yourself, there might * be a small delay after your first request, while the SDK automatically authenticates. * * Misc options: * - signRequest: boolean - if included, this request will automatically be signed with the available credentials. * * @param wsKey - The connection this event is for. Currently only "v5PrivateTrade" is supported * for Bybit, since that is the dedicated WS API connection. * @param operation - The command being sent, e.g. "order.create" to submit a new order. * @param params - Any request parameters for the command. E.g. `OrderParamsV5` to submit a new * order. Only send parameters for the request body. Everything else is automatically handled. * @returns Promise - tries to resolve with async WS API response. Rejects if disconnected or exception is seen in async WS API response */ sendWSAPIRequest[TWSOperation]>, TWSAPIResponse extends WsAPIOperationResponseMap[TWSOperation] = WsAPIOperationResponseMap[TWSOperation]>(wsKey: TWSKey, operation: TWSOperation, params?: TWSParams extends void | never ? undefined : TWSParams, requestFlags?: WSAPIRequestFlags): Promise; /** * * * Internal methods - not intended for public use * * */ /** * @returns The WS URL to connect to for this WS key */ getWsUrl(wsKey: WsKey, connectionType?: 'public' | 'market' | 'private'): Promise; private signMessage; /** * Handles request sign, if connection isn't authenticated yet. * If connection does not need to be authenticated or request doesn't require sign, * use the requestFlags.authIsOptional flag to skip sign and send the request immediately. */ private signWSAPIRequest; protected getWsAuthRequestEvent(wsKey: WsKey): Promise>; protected sendPingEvent(wsKey: WsKey): void; protected sendPongEvent(wsKey: WsKey): void; /** Force subscription requests to be sent in smaller batches, if a number is returned */ protected getMaxTopicsPerSubscribeEvent(wsKey: WsKey): number | null; /** * @returns one or more correctly structured request events for performing a operations over WS. This can vary per exchange spec. */ protected getWsRequestEvents(wsKey: WsKey, operation: WsOperation, requests: WsTopicRequest[]): Promise>[]>; protected getPrivateWSKeys(): WsKey[]; protected isAuthOnConnectWsKey(wsKey: WsKey): boolean; /** * Determines if a topic is for a private channel, using a hardcoded list of strings */ protected isPrivateTopicRequest(request: WsTopicRequest): boolean; protected isWsPing(msg: any): boolean; protected isWsPong(msg: any): boolean; /** * Abstraction called to sort ws events into emittable event types (response to a request, data update, etc) */ protected resolveEmittableEvents(wsKey: WsKey, event: MessageEventLike): EmittableEvent[]; /** * * * * * * User Data Streams * * * * * */ /** * -------------------------- * User data listen key tracking & persistence * -------------------------- **/ /** * Subscribe to a spot user data stream. Use REST client to generate and persist listen key. * Supports spot, margin & isolated margin listen keys. */ subscribeSpotUserDataStreamWithListenKey(wsKey: WsKey, listenKey: string, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; /** * Subscribe to spot user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group (e.g. port 9443 (main) vs 443 (main2)) */ subscribeSpotUserDataStream(wsKey?: WsKey, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeSpotUserDataStream(wsKey?: WsKey): Promise; fetchMarginListenToken(params?: { symbol?: string; isIsolated?: boolean; validity?: number; }): Promise<{ token: string; expirationTime: number; }>; /** * Subscribe to margin user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group (e.g. port 9443 (main) vs 443 (main2)) */ subscribeCrossMarginUserDataStream(wsKey?: WsKey, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeCrossMarginUserDataStream(wsKey?: WsKey): Promise; /** * Subscribe to isolated margin user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group (e.g. port 9443 (main) vs 443 (main2)) */ subscribeIsolatedMarginUserDataStream(symbol: string, wsKey?: WsKey, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeIsolatedMarginUserDataStream(symbol: string, wsKey?: WsKey): Promise; /** * Subscribe to margin risk user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group (e.g. port 9443 (main) vs 443 (main2)) */ subscribeMarginRiskUserDataStream(wsKey?: WsKey, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeMarginRiskUserDataStream(wsKey?: WsKey): Promise; /** * -------------------------- * End of SPOT market websocket streams * -------------------------- **/ /** * Subscribe to USD-M Futures user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group. */ subscribeUsdFuturesUserDataStream(wsKey?: WsKey, // usdm | usdmPrivate | usdmTestnet forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeUsdFuturesUserDataStream(wsKey?: WsKey): Promise; /** * Subscribe to COIN-M Futures user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group. */ subscribeCoinFuturesUserDataStream(wsKey?: WsKey, // coinm | coinmTestnet forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribeCoinFuturesUserDataStream(wsKey?: WsKey): Promise; /** * Subscribe to Portfolio Margin user data stream - listen key is automatically generated. Calling multiple times only opens one connection. * * Note: the wsKey parameter is optional, but can be used to connect to other environments for this product group. */ subscribePortfolioMarginUserDataStream(wsKey?: WsKey, forceNewConnection?: boolean, miscState?: MiscUserDataConnectionState): Promise; unsubscribePortfolioMarginUserDataStream(wsKey?: WsKey): Promise; /** * Close an active, dedicated, user data stream connection. * * @param wsKey - the connection key used to open the connection (excluding any automatic parameters such as the listen key). E.g. 'main' for spot/margin, 'usdm' for futures. * @param wsMarket - the product group, recommended if you're subscribed to both spot and margin (since they're on the same wsKey (main)). */ closeUserDataStream(wsKey: WsKey, wsMarket: WsMarket, symbol?: string): Promise; protected isCustomReconnectionNeeded(wsKey: string): boolean; protected triggerCustomReconnectionWorkflow(legacyWsKey: string): Promise; private respawnUserDataStream; /** * Subscribe to the European Options user data stream - listen key is automatically generated. * * Not supported at this time. Please get in touch if you need this. */ /** * * * * * Convenient subscribe methods, similar to the legacy WebsocketClient for Binance. * * * * */ /** * -------------------------- * Universal market websocket streams (may apply to one or more API markets) * -------------------------- **/ /** * Advanced: Subscribe to a universal market websocket stream * * This is NOT recommended unless you're very confident with what you're doing. */ subscribeEndpoint(endpoint: string, market: 'spot' | 'usdm' | 'coinm'): Promise; /** * Subscribe to aggregate trades for a symbol in a market category */ subscribeAggregateTrades(symbol: string, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to trades for a symbol in a market category * IMPORTANT: This topic for usdm and coinm is not listed in the api docs and might stop working without warning */ subscribeTrades(symbol: string, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to coin index for a symbol in COINM Futures markets */ subscribeCoinIndexPrice(symbol: string, updateSpeedMs?: 1000 | 3000, wsKeyOverride?: WsKey): Promise; /** * Subscribe to mark price for a symbol in a market category */ subscribeMarkPrice(symbol: string, market: 'usdm' | 'coinm', updateSpeedMs?: 1000 | 3000, wsKeyOverride?: WsKey): Promise; /** * Subscribe to mark price for all symbols in a market category */ subscribeAllMarketMarkPrice(market: 'usdm' | 'coinm', updateSpeedMs?: 1000 | 3000, wsKeyOverride?: WsKey): Promise; /** * Subscribe to klines(candles) for a symbol in a market category */ subscribeKlines(symbol: string, interval: KlineInterval, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to continuous contract klines(candles) for a symbol futures */ subscribeContinuousContractKlines(symbol: string, contractType: 'perpetual' | 'current_quarter' | 'next_quarter', interval: KlineInterval, market: 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to index klines(candles) for a symbol in a coinm futures */ subscribeIndexKlines(symbol: string, interval: KlineInterval, wsKeyOverride?: WsKey): Promise; /** * Subscribe to index klines(candles) for a symbol in a coinm futures */ subscribeMarkPriceKlines(symbol: string, interval: KlineInterval, wsKeyOverride?: WsKey): Promise; /** * Subscribe to mini 24hr ticker for a symbol in market category. */ subscribeSymbolMini24hrTicker(symbol: string, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to mini 24hr mini ticker in market category. */ subscribeAllMini24hrTickers(market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to 24hr ticker for a symbol in any market. */ subscribeSymbol24hrTicker(symbol: string, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to Alpha Trading WebSocket Market Data streams. * Base URL: wss://nbstream.binance.com/w3w/wsa/stream */ subscribeAlpha(topics: string | string[]): Promise; /** * Subscribe to Alpha all tokens 24h ticker (came@allTokens@ticker24) */ subscribeAlphaAllTokensTicker24(): Promise; /** * Subscribe to Alpha aggregate trades for a symbol * @param symbol e.g. ALPHA_474USDT */ subscribeAlphaAggTrade(symbol: string): Promise; /** * Subscribe to Alpha full depth for a symbol * @param symbol e.g. ALPHA_474USDT * @param intervalMs 0, 100, or 500 */ subscribeAlphaFulldepth(symbol: string, intervalMs?: 0 | 100 | 500): Promise; /** * Subscribe to Alpha klines for a contract * @param contractAddress Contract address * @param chainId Chain ID (e.g. CT_501, 56) * @param interval 1s, 1m, 5m, 15m, 1h, 4h, 1d */ subscribeAlphaKline(contractAddress: string, chainId: string, interval: '1s' | '1m' | '5m' | '15m' | '1h' | '4h' | '1d'): Promise; /** * Subscribe to 24hr ticker in any market. */ subscribeAll24hrTickers(market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to rolling window ticker statistics for all market symbols, * computed over multiple windows. Note that only tickers that have * changed will be present in the array. * * Notes: * - Supported window sizes: 1h,4h,1d. * - Supported markets: spot */ subscribeAllRollingWindowTickers(market: 'spot', windowSize: '1h' | '4h' | '1d', wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for symbol in spot markets. */ subscribeSymbolBookTicker(symbol: string, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for all symbols in spot markets. */ subscribeAllBookTickers(market: 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for symbol in spot markets. */ subscribeSymbolLiquidationOrders(symbol: string, market: 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for all symbols in spot markets. */ subscribeAllLiquidationOrders(market: 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to partial book depths (snapshots). * * Note: * - spot only supports 1000ms or 100ms for updateMs * - futures only support 100, 250 or 500ms for updateMs */ subscribePartialBookDepths(symbol: string, levels: 5 | 10 | 20, updateMs: 100 | 250 | 500 | 1000, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to orderbook depth updates to locally manage an order book. * * Note that the updatems parameter depends on which market you're trading * * - Spot: https://binance-docs.github.io/apidocs/spot/en/#diff-depth-stream * - USDM Futures: https://binance-docs.github.io/apidocs/futures/en/#diff-book-depth-streams */ subscribeDiffBookDepth(symbol: string, updateMs: 100 | 250 | 500 | 1000 | undefined, market: 'spot' | 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for all symbols in spot markets. */ subscribeContractInfoStream(market: 'usdm' | 'coinm', wsKeyOverride?: WsKey): Promise; /** * -------------------------- * SPOT market websocket streams * -------------------------- **/ /** * Subscribe to aggregate trades for a symbol in spot markets. */ subscribeSpotAggregateTrades(symbol: string, wsKeyOverride?: WsKey): Promise; /** * Subscribe to trades for a symbol in spot markets. */ subscribeSpotTrades(symbol: string, wsKeyOverride?: WsKey): Promise; /** * Subscribe to candles for a symbol in spot markets. */ subscribeSpotKline(symbol: string, interval: KlineInterval, wsKeyOverride?: WsKey): Promise; /** * Subscribe to mini 24hr ticker for a symbol in spot markets. */ subscribeSpotSymbolMini24hrTicker(symbol: string, wsKeyOverride?: WsKey): Promise; /** * Subscribe to mini 24hr mini ticker in spot markets. */ subscribeSpotAllMini24hrTickers(wsKeyOverride?: WsKey): Promise; /** * Subscribe to 24hr ticker for a symbol in spot markets. */ subscribeSpotSymbol24hrTicker(symbol: string, wsKeyOverride?: WsKey): Promise; /** * Subscribe to 24hr ticker in spot markets. */ subscribeSpotAll24hrTickers(wsKeyOverride?: WsKey): Promise; /** * Subscribe to best bid/ask for symbol in spot markets. */ subscribeSpotSymbolBookTicker(symbol: string, wsKeyOverride?: WsKey): Promise; /** * Subscribe to top bid/ask levels for symbol in spot markets. */ subscribeSpotPartialBookDepth(symbol: string, levels: 5 | 10 | 20, updateMs?: 1000 | 100, wsKeyOverride?: WsKey): Promise; /** * Subscribe to spot orderbook depth updates to locally manage an order book. */ subscribeSpotDiffBookDepth(symbol: string, updateMs?: 1000 | 100, wsKeyOverride?: WsKey): Promise; }