binance/lib/util/websockets/websocket-util.d.ts

Professional Node.js & JavaScript SDK for Binance REST APIs & WebSockets, with TypeScript & end-to-end tests.

import WebSocket from 'isomorphic-ws';
import { WsRequestOperationBinance } from '../../types/websockets/ws-api';
import { WebsocketClientOptions, WSClientConfigurableOptions, WsMarket, WsTopic } from '../../types/websockets/ws-general';
import { DefaultLogger } from '../logger';
export declare const WS_LOGGER_CATEGORY: {
    category: string;
};
export declare const EVENT_TYPES_USER_DATA: string[];
export declare const WS_KEY_MAP: {
    readonly main: "main";
    readonly main2: "main2";
    readonly main3: "main3";
    readonly mainTestnetPublic: "mainTestnetPublic";
    readonly mainTestnetUserData: "mainTestnetUserData";
    readonly mainWSAPI: "mainWSAPI";
    readonly mainWSAPI2: "mainWSAPI2";
    readonly mainWSAPITestnet: "mainWSAPITestnet";
    readonly marginRiskUserData: "marginRiskUserData";
    readonly marginUserData: "marginUserData";
    /**
     * USD-M Futures product-group alias.
     *
     * For raw subscribe/unsubscribe calls, this is auto-routed to the required
     * split USD-M market data key (`usdmPublic` or `usdmMarket`) per topic.
     *
     * For direct endpoint control, use `usdmPublic`, `usdmMarket`, or
     * `usdmPrivate`.
     */
    readonly usdm: "usdm";
    readonly usdmPrivate: "usdmPrivate";
    readonly usdmPublic: "usdmPublic";
    readonly usdmMarket: "usdmMarket";
    readonly usdmTestnet: "usdmTestnet";
    readonly usdmTestnetPrivate: "usdmTestnetPrivate";
    readonly usdmTestnetPublic: "usdmTestnetPublic";
    readonly usdmTestnetMarket: "usdmTestnetMarket";
    readonly usdmWSAPI: "usdmWSAPI";
    readonly usdmWSAPITestnet: "usdmWSAPITestnet";
    readonly coinm: "coinm";
    readonly coinm2: "coinm2";
    readonly coinmTestnet: "coinmTestnet";
    readonly coinmWSAPI: "coinmWSAPI";
    readonly coinmWSAPITestnet: "coinmWSAPITestnet";
    readonly eoptions: "eoptions";
    readonly portfolioMarginUserData: "portfolioMarginUserData";
    readonly portfolioMarginProUserData: "portfolioMarginProUserData";
    readonly alpha: "alpha";
};
export declare const WS_KEYS_SPOT: string[];
export declare const WS_KEYS_FUTURES: string[];
export type WsKey = (typeof WS_KEY_MAP)[keyof typeof WS_KEY_MAP];
/**
 * These WS Key values correspond to a WS API connection
 */
export type WSAPIWsKeyMain = typeof WS_KEY_MAP.mainWSAPI | typeof WS_KEY_MAP.mainWSAPI2 | typeof WS_KEY_MAP.mainWSAPITestnet | typeof WS_KEY_MAP.marginUserData;
export type WSAPIWsKeyFutures = typeof WS_KEY_MAP.usdmWSAPI | typeof WS_KEY_MAP.usdmWSAPITestnet | typeof WS_KEY_MAP.coinmWSAPI | typeof WS_KEY_MAP.coinmWSAPITestnet;
export type WSAPIWsKey = WSAPIWsKeyMain | WSAPIWsKeyFutures;
export declare const WS_KEY_URL_MAP: Record<WsKey, string>;
export declare const WS_KEY_MM_URL_MAP: Record<WsKey, string | undefined>;
export declare const WS_KEY_DEMO_URL_MAP: Record<WsKey, string | undefined>;
/**
 * For some products, topics are broken down into 3 endpoint/connection categories:
 *  https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams/Important-WebSocket-Change-Notice#public--market-combined-subscriptions
 *
 * - Public (high frequency market data, e.g. book updates)
 * - Market (general market data)
 * - Private (account data, user data stream)
 */
export type WSConnectionCategory = 'public' | 'market' | 'private';
export declare function getWsURLSuffix(wsKey: WsKey, connectionType: WSConnectionCategory): string;
/**
 * Follows API spec to route topics to specific WS Endpoints:
 * https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams/Important-WebSocket-Change-Notice#public--market-combined-subscriptions
 */
export declare function getWSConnectionCategoryForTopic(wsTopic: WsTopic): WSConnectionCategory;
export declare const WS_AUTH_ON_CONNECT_KEYS: WsKey[];
/**
 * Normalised internal format for a request (subscribe/unsubscribe/etc) on a topic, with optional parameters.
 *
 * - Topic: the topic this event is for
 * - Payload: the parameters to include, optional. E.g. auth requires key + sign. Some topics allow configurable parameters.
 * - Category: required for bybit, since different categories have different public endpoints
 */
export interface WsTopicRequest<TWSTopic extends string = string, TWSPayload = unknown> {
    topic: TWSTopic;
    payload?: TWSPayload;
}
/**
 * Conveniently allow users to request a topic either as string topics or objects (containing string topic + params)
 */
export type WsTopicRequestOrStringTopic<TWSTopic extends string, TWSPayload = unknown> = WsTopicRequest<TWSTopic, TWSPayload> | string;
export declare function isPrivateWsTopic(topic: string): boolean;
export declare function getTestnetWsKey(wsKey: WSAPIWsKeyMain): WSAPIWsKeyMain;
export declare function getTestnetWsKey(wsKey: WSAPIWsKeyFutures): WSAPIWsKeyFutures;
export declare function getTestnetWsKey(wsKey: WSAPIWsKey): WSAPIWsKey;
export declare function getTestnetWsKey(wsKey: WsKey): WsKey;
export declare function getWsUrl(wsKey: WsKey, wsClientOptions: WebsocketClientOptions, logger: typeof DefaultLogger): string;
export declare function getMaxTopicsPerSubscribeEvent(wsKey: WsKey): number | null;
export declare const WS_ERROR_ENUM: {
    NOT_AUTHENTICATED_SPOT_V3: string;
    API_ERROR_GENERIC: string;
    API_SIGN_AUTH_FAILED: string;
    USDC_OPTION_AUTH_FAILED: string;
};
/**
 * #305: ws.terminate() is undefined in browsers.
 * This only works in node.js, not in browsers.
 * Does nothing if `ws` is undefined. Does nothing in browsers.
 */
export declare function safeTerminateWs(ws?: WebSocket | any, fallbackToClose?: boolean): boolean;
/**
 * WS API promises are stored using a primary key. This key is constructed using
 * properties found in every request & reply.
 *
 * The counterpart to this is in resolveEmittableEvents
 */
export declare function getPromiseRefForWSAPIRequest(wsKey: WsKey, requestEvent: WsRequestOperationBinance<string>): string;
/**
 * Users can conveniently pass topics as strings or objects (object has topic name + optional params).
 *
 * This method normalises topics into objects (object has topic name + optional params).
 */
export declare function getNormalisedTopicRequests(wsTopicRequests: WsTopicRequestOrStringTopic<string>[]): WsTopicRequest<string>[];
/**
 * USD-M Futures retired the legacy combined market data endpoint on 2026-04-23.
 * Keep the legacy `usdm` wsKey convenient by routing raw market data streams to
 * Binance's split public/market stream keys.
 */
export declare function getUsdmMarketDataWsKeyForTopic(wsKey: WsKey, topic: string): WsKey;
/**
 * Groups topics in request into per-wsKey groups
 * @param normalisedTopicRequests
 * @param wsKey
 * @param isPrivateTopic
 * @returns
 */
export declare function getTopicsPerWSKey(normalisedTopicRequests: WsTopicRequest[], wsKey: WsKey): {
    [key in WsKey]?: WsTopicRequest<WsTopic>[];
};
/**
 * Some of the newer multiplex websocket topics don't include an eventType ("e") property.
 *
 * This attempts to extract that from the streamName, which is included with these incoming events.
 */
export declare function parseEventTypeFromMessage(wsKey: WsKey, parsedMsg?: any): string | undefined;
export declare function resolveUserDataMarketForWsKey(wsKey: WsKey): WsMarket;
/**
 * Used by the legacy subscribe* utility methods to determine which wsKey to route the subscription to.
 */
export declare function getWsKeyForProductGroup(market: 'spot' | 'usdm' | 'coinm', topic: WsTopic): WsKey;
export declare function parseRawWsMessageLegacy(event: any, options: WSClientConfigurableOptions): any;
/**
 * One simple purpose - extract JSON event from raw WS Message.
 *
 * Any mapping or additonal handling should not be done here.
 */
export declare function parseRawWsMessage(event: any, options: WSClientConfigurableOptions): any;
export interface MiscUserDataConnectionState {
    isReconnecting?: boolean;
    respawnAttempt?: number;
    symbol?: string;
}
interface WsContext {
    symbol: string | undefined;
    legacyWsKey: string | undefined;
    wsKey: WsKey | undefined;
    market: WsMarket;
    isTestnet: boolean | undefined;
    isUserData: boolean;
    streamName: string;
    listenKey: string | undefined;
    otherParams: undefined | string[];
}
/**
 * @deprecated Only works for legacy WS client, where one connection exists per key
 */
export declare function getContextFromWsKey(legacyWsKey: any): WsContext;
/**
 * The legacy WS client creates a deterministic WS Key based on consistent input parameters
 */
export declare function getLegacyWsStoreKeyWithContext(market: WsMarket, streamName: string, symbol?: string | undefined, listenKey?: string | undefined, ...otherParams: (string | boolean)[]): any;
export declare function getLegacyWsKeyContext(wsKey: string): WsContext | undefined;
export declare function getRealWsKeyFromDerivedWsKey(wsKey: string | WsKey): WsKey;
export declare function appendEventMarket(wsMsg: any, wsKey: WsKey): void;
/**
 * WebSocket.ping() is not available in browsers. This is a simple check used to
 * disable heartbeats in browers, for exchanges that use native WebSocket ping/pong frames.
 */
export declare function isWSPingFrameAvailable(): boolean;
/**
 * WebSocket.pong() is not available in browsers. This is a simple check used to
 * disable heartbeats in browers, for exchanges that use native WebSocket ping/pong frames.
 */
export declare function isWSPongFrameAvailable(): boolean;
export {};