binance 3.0.0-beta.7 → 3.0.0

package/lib/websocket-client.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -44,9 +55,12 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
         super(options, logger);
         this.restClientCache = new rest_client_cache_1.RestClientCache();
         this.beautifier = new beautifier_1.default({
-            warnKeyMissingInMap: true,
+            warnKeyMissingInMap: false,
         });
         this.respawnTimeoutCache = {};
+        if (options === null || options === void 0 ? void 0 : options.beautifyWarnIfMissing) {
+            this.beautifier.setWarnIfMissing(options.beautifyWarnIfMissing);
+        }
         /**
          * Binance uses native WebSocket ping/pong frames, which cannot be directly used in
          * some environents (e.g. most browsers do not support sending raw ping/pong frames).
@@ -57,7 +71,7 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
          * be found here: https://stackoverflow.com/questions/10585355/sending-websocket-ping-pong-frame-from-browser
          */
         if (!(0, websocket_util_1.isWSPingFrameAvailable)()) {
-            this.logger.trace('Disabled WS heartbeats. WS.ping() is not available in your environment.');
+            this.logger.info('Disabled WS heartbeats. WS.ping() is not available in your environment.');
             this.options.disableHeartbeat = true;
         }
         this.userDataStreamManager = new user_data_stream_manager_1.UserDataStreamManager({
@@ -65,8 +79,12 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             wsStore: this.getWsStore(),
             restClientCache: this.restClientCache,
             // fn pointers:
-            respawnUserDataFn: (wsKey, market, context = {}) => this.respawnUserDataStream(wsKey, market, context),
-            getWsUrlFn: (wsKey, connectionType) => this.getWsUrl(wsKey, connectionType),
+            respawnUserDataFn: (wsKey, market, context = {}) => {
+                return this.respawnUserDataStream(wsKey, market, context);
+            },
+            getWsUrlFn: (wsKey, connectionType) => {
+                return this.getWsUrl(wsKey, connectionType);
+            },
             getRestClientOptionsFn: () => this.getRestClientOptions(),
             getWsClientOptionsfn: () => this.options,
             closeWsFn: (wsKey, force) => this.close(wsKey, force),
@@ -114,7 +132,10 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
      * 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) {
+    connectWSAPI(wsKey, skipAuth) {
+        if (skipAuth) {
+            return this.assertIsConnected(wsKey);
+        }
         /** This call automatically ensures the connection is active AND authenticated before resolving */
         return this.assertIsAuthenticated(wsKey);
     }
@@ -146,27 +167,48 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
         const normalisedTopicRequests = (0, websocket_util_1.getNormalisedTopicRequests)(topicRequests);
         return this.unsubscribeTopicsForWsKey(normalisedTopicRequests, wsKey);
     }
-    sendWSAPIRequest(wsKey, operation, params) {
+    sendWSAPIRequest(wsKey, operation, params, requestFlags) {
         return __awaiter(this, void 0, void 0, function* () {
             /**
-             * Spot: https://developers.binance.com/docs/binance-spot-api-docs/websocket-api/general-api-information
+             * Spot:
+             * -> https://developers.binance.com/docs/binance-spot-api-docs/websocket-api/general-api-information
+             * -> https://github.com/binance/binance-spot-api-docs/blob/master/web-socket-api.md#public-api-requests
              * 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
              */
-            var _a;
+            var _a, _b;
             // If testnet, enforce testnet wskey for WS API calls
             const resolvedWsKey = this.options.testnet ? (0, websocket_util_1.getTestnetWsKey)(wsKey) : wsKey;
             // this.logger.trace(`sendWSAPIRequest(): assertIsConnected("${wsKey}")...`);
+            const timestampBeforeAuth = Date.now();
             yield this.assertIsConnected(resolvedWsKey);
             // this.logger.trace('sendWSAPIRequest(): assertIsConnected(${wsKey}) ok');
-            // this.logger.trace('sendWSAPIRequest(): assertIsAuthenticated(${wsKey})...');
-            yield this.assertIsAuthenticated(resolvedWsKey);
-            // this.logger.trace('sendWSAPIRequest(): assertIsAuthenticated(${wsKey}) ok');
+            // Some commands don't require authentication.
+            if ((requestFlags === null || requestFlags === void 0 ? void 0 : requestFlags.authIsOptional) !== true) {
+                // this.logger.trace('sendWSAPIRequest(): assertIsAuthenticated(${wsKey})...');
+                yield this.assertIsAuthenticated(resolvedWsKey);
+                // this.logger.trace('sendWSAPIRequest(): assertIsAuthenticated(${wsKey}) ok');
+            }
+            const timestampAfterAuth = Date.now();
             const request = {
                 id: this.getNewRequestId(),
                 method: operation,
                 params: Object.assign({}, params),
             };
+            /**
+             * Some WS API requests require a timestamp to be included. assertIsConnected and assertIsAuthenticated
+             * can introduce a small delay before the actual request is sent, if not connected before that request is
+             * made. This can lead to a curious race condition, where the request timestamp is before
+             * the "authorizedSince" timestamp - as such, binance does not recognise the session as already authenticated.
+             *
+             * The below mechanism measures any delay introduced from the assert calls, and if the request includes a timestamp,
+             * it offsets that timestamp by the delay.
+             */
+            const delayFromAuthAssert = timestampAfterAuth - timestampBeforeAuth;
+            if (delayFromAuthAssert && ((_a = request.params) === null || _a === void 0 ? void 0 : _a.timestamp)) {
+                request.params.timestamp += delayFromAuthAssert;
+                this.logger.trace(`sendWSAPIRequest(): adjust timestamp - delay seen by connect/auth assert and delayed request includes timestamp, adjusting timestamp by ${delayFromAuthAssert}ms`);
+            }
             if ((0, requestUtils_1.requiresWSAPINewClientOID)(request, resolvedWsKey)) {
                 (0, requestUtils_1.validateWSAPINewClientOID)(request, resolvedWsKey);
             }
@@ -175,17 +217,24 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             // Store deferred promise, resolved within the "resolveEmittableEvents" method while parsing incoming events
             const promiseRef = (0, websocket_util_1.getPromiseRefForWSAPIRequest)(resolvedWsKey, signedEvent);
             const deferredPromise = this.getWsStore().createDeferredPromise(resolvedWsKey, promiseRef, false);
-            (_a = deferredPromise.promise) === null || _a === void 0 ? void 0 : _a.catch((e) => {
+            // Enrich returned promise with request context for easier debugging
+            (_b = deferredPromise.promise) === null || _b === void 0 ? void 0 : _b.then((res) => {
+                if (!Array.isArray(res)) {
+                    res.request = Object.assign({ wsKey: resolvedWsKey }, signedEvent);
+                }
+                return res;
+            }).catch((e) => {
                 if (typeof e === 'string') {
                     this.logger.error('unexpcted string', { e });
-                    throw e;
+                    return e;
                 }
                 e.request = {
                     wsKey: resolvedWsKey,
                     operation,
-                    params,
+                    params: signedEvent.params,
                 };
-                throw e;
+                // throw e;
+                return e;
             });
             // this.logger.trace(
             //   `sendWSAPIRequest(): sending raw request: ${JSON.stringify(signedEvent)} with promiseRef(${promiseRef})`,
@@ -226,8 +275,26 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
     }
     signWSAPIRequest(requestEvent) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Not needed for Binance. Auth happens only on connection open, automatically.
-            // Faster than performing auth for every request
+            if (!requestEvent.params) {
+                return requestEvent;
+            }
+            /**
+             * Not really needed for most commands on Binance. Their WS API supports
+             * sending signed WS API commands, but that adds latency to every request.
+             *
+             * Instead, this SDK will authenticate once after connecting. All requests
+             * after authentication can then be sent without sign for maximum speed.
+             */
+            const _a = requestEvent.params, { signRequest } = _a, otherParams = __rest(_a, ["signRequest"]);
+            if (signRequest) {
+                const strictParamValidation = true;
+                const encodeValues = true;
+                const filterUndefinedParams = true;
+                const semiFinalRequestParams = Object.assign({ apiKey: this.options.api_key }, otherParams);
+                const serialisedParams = (0, requestUtils_1.serialiseParams)(semiFinalRequestParams, strictParamValidation, encodeValues, filterUndefinedParams);
+                const signature = yield this.signMessage(serialisedParams, this.options.api_secret, 'base64', 'SHA-256');
+                return Object.assign(Object.assign({}, requestEvent), { params: Object.assign(Object.assign({}, semiFinalRequestParams), { signature }) });
+            }
             return requestEvent;
         });
     }
@@ -238,21 +305,23 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                 // If you do not want to specify apiKey and signature in each individual request, you can authenticate your API key for the active WebSocket session.
                 // Once authenticated, you no longer have to specify apiKey and signature for those requests that need them. Requests will be performed on behalf of the account owning the authenticated API key.
                 // Note: You still have to specify the timestamp parameter for SIGNED requests.
-                const recvWindow = this.options.recvWindow || 0;
-                const timestamp = Date.now() + (this.getTimeOffsetMs() || 0) + recvWindow;
+                const timestamp = Date.now() + (this.getTimeOffsetMs() || 0);
                 const strictParamValidation = true;
                 const encodeValues = true;
                 const filterUndefinedParams = true;
-                const authParams = {
+                if (!this.options.api_key || !this.options.api_secret) {
+                    throw new Error('API key and/or secret missing, unable to prepare WS auth event without valid API keys.');
+                }
+                const params = {
                     apiKey: this.options.api_key,
                     timestamp,
                 };
-                const serialisedParams = (0, requestUtils_1.serialiseParams)(authParams, strictParamValidation, encodeValues, filterUndefinedParams);
+                const serialisedParams = (0, requestUtils_1.serialiseParams)(params, strictParamValidation, encodeValues, filterUndefinedParams);
                 const signature = yield this.signMessage(serialisedParams, this.options.api_secret, 'base64', 'SHA-256');
                 const request = {
                     id: this.getNewRequestId(),
                     method: 'session.logon',
-                    params: Object.assign(Object.assign({}, authParams), { signature }),
+                    params: Object.assign(Object.assign({}, params), { signature }),
                 };
                 return request;
             }
@@ -390,26 +459,71 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
      * Abstraction called to sort ws events into emittable event types (response to a request, data update, etc)
      */
     resolveEmittableEvents(wsKey, event) {
-        var _a, _b, _c;
+        var _a, _b;
+        // this.logger.trace(`resolveEmittableEvents(${wsKey}): `, event?.data);
         const results = [];
         try {
-            // const parsed = JSON.parse(event.data);
-            const parsed = (0, websocket_util_1.parseRawWsMessage)(event);
-            const eventType = (0, websocket_util_1.parseEventTypeFromMessage)(wsKey, parsed);
+            /**
+             *
+             * Extract event from JSON
+             *
+             */
+            const parsedEvent = (0, websocket_util_1.parseRawWsMessage)(event);
+            /**
+             *
+             * Minor data normalisation & preparation
+             *
+             */
+            // ws consumers: { data: ... }
+            // ws api consumers (user data): { event: ... }
+            // other responses: { ... }
+            const eventData = (parsedEvent === null || parsedEvent === void 0 ? void 0 : parsedEvent.data) || (parsedEvent === null || parsedEvent === void 0 ? void 0 : parsedEvent.event) || parsedEvent;
+            const parsedEventId = parsedEvent === null || parsedEvent === void 0 ? void 0 : parsedEvent.id;
+            const parsedEventErrorCode = (_a = parsedEvent === null || parsedEvent === void 0 ? void 0 : parsedEvent.error) === null || _a === void 0 ? void 0 : _a.code;
+            const streamName = parsedEvent === null || parsedEvent === void 0 ? void 0 : parsedEvent.stream;
+            const eventType = 
+            // First try, the child node
+            (0, websocket_util_1.parseEventTypeFromMessage)(wsKey, eventData) ||
+                // Second try, the parent
+                (0, websocket_util_1.parseEventTypeFromMessage)(wsKey, parsedEvent);
             // Some events don't include the topic (event name)
             // This tries to extract and append it, using available context
-            (0, requestUtils_1.appendEventIfMissing)(parsed, wsKey);
+            (0, requestUtils_1.appendEventIfMissing)(eventData, wsKey, eventType);
             const legacyContext = (0, websocket_util_1.getLegacyWsKeyContext)(wsKey);
-            if (legacyContext) {
-                parsed.wsMarket = legacyContext.market;
+            const wsMarket = legacyContext
+                ? legacyContext.market
+                : (0, websocket_util_1.resolveUserDataMarketForWsKey)(wsKey);
+            // This attaches `wsMarket` and `streamName` to incoming events
+            // If the event is an array, it's attached to each element in the array
+            if (Array.isArray(eventData)) {
+                for (const row of eventData) {
+                    row.wsMarket = wsMarket;
+                    if (streamName && !row.streamName) {
+                        row.streamName = streamName;
+                    }
+                }
+            }
+            else {
+                eventData.wsMarket = wsMarket;
+                if (streamName && !eventData.streamName) {
+                    eventData.streamName = streamName;
+                }
             }
+            /**
+             *
+             *
+             * Main parsing logic below:
+             *
+             *
+             */
             const traceEmittable = false;
             if (traceEmittable) {
-                this.logger.trace('resolveEmittableEvents', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { wsKey,
-                    eventType, parsed: JSON.stringify(parsed) }));
+                this.logger.trace('resolveEmittableEvents', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { wsKey, parsedEvent: JSON.stringify(parsedEvent), parsedEventData: JSON.stringify(eventData), eventType, properties: {
+                        parsedEventId,
+                        parsedEventErrorCode,
+                    } }));
             }
-            const reqId = parsed.id;
-            const isWSAPIResponse = typeof parsed.id === 'number';
+            const isWSAPIResponse = typeof parsedEventId === 'number';
             const EVENTS_AUTHENTICATED = ['auth'];
             const EVENTS_RESPONSES = [
                 'subscribe',
@@ -454,65 +568,66 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                       isWSAPIResponse: true
                     }
                  */
-                const isError = typeof ((_a = parsed.error) === null || _a === void 0 ? void 0 : _a.code) === 'number' && ((_b = parsed.error) === null || _b === void 0 ? void 0 : _b.code) !== 0;
+                const isError = typeof parsedEventErrorCode === 'number' &&
+                    parsedEventErrorCode !== 0;
                 // This is the counterpart to getPromiseRefForWSAPIRequest
-                const promiseRef = [wsKey, reqId].join('_');
-                if (!reqId) {
+                const promiseRef = [wsKey, parsedEventId].join('_');
+                if (!parsedEventId) {
                     this.logger.error('WS API response is missing reqId - promisified workflow could get stuck. If this happens, please get in touch with steps to reproduce. Trace:', {
                         wsKey,
                         promiseRef,
-                        parsedEvent: parsed,
+                        parsedEvent: eventData,
                     });
                 }
                 // WS API Exception
                 if (isError) {
                     try {
-                        this.getWsStore().rejectDeferredPromise(wsKey, promiseRef, Object.assign({ wsKey }, parsed), true);
+                        this.getWsStore().rejectDeferredPromise(wsKey, promiseRef, Object.assign({ wsKey }, eventData), true);
                     }
                     catch (e) {
                         this.logger.error('Exception trying to reject WSAPI promise', {
                             wsKey,
                             promiseRef,
-                            parsedEvent: parsed,
+                            parsedEvent: eventData,
                             e,
                         });
                     }
                     results.push({
                         eventType: 'exception',
-                        event: parsed,
+                        event: eventData,
                         isWSAPIResponse: isWSAPIResponse,
                     });
                     return results;
                 }
                 // authenticated
-                if ((_c = parsed.result) === null || _c === void 0 ? void 0 : _c.apiKey) {
+                if ((_b = eventData.result) === null || _b === void 0 ? void 0 : _b.apiKey) {
                     // Note: Without this check, this will also trigger "onWsAuthenticated()" for session.status requests
                     if (this.getWsStore().getAuthenticationInProgressPromise(wsKey)) {
                         results.push({
                             eventType: 'authenticated',
-                            event: parsed,
+                            event: eventData,
                             isWSAPIResponse: isWSAPIResponse,
                         });
                     }
                 }
                 // WS API Success
                 try {
-                    this.getWsStore().resolveDeferredPromise(wsKey, promiseRef, Object.assign({ wsKey }, parsed), true);
+                    this.getWsStore().resolveDeferredPromise(wsKey, promiseRef, Object.assign({ wsKey }, eventData), true);
                 }
                 catch (e) {
                     this.logger.error('Exception trying to resolve WSAPI promise', {
                         wsKey,
                         promiseRef,
-                        parsedEvent: parsed,
+                        parsedEvent: eventData,
                         e,
                     });
                 }
                 results.push({
                     eventType: 'response',
-                    event: Object.assign(Object.assign({}, parsed), { request: this.getCachedMidFlightRequest(wsKey, reqId) }),
+                    event: Object.assign(Object.assign({}, eventData), { request: this.getCachedMidFlightRequest(wsKey, `${parsedEventId}`) }),
                     isWSAPIResponse: isWSAPIResponse,
                 });
-                this.removeCachedMidFlightRequest(wsKey, reqId);
+                this.removeCachedMidFlightRequest(wsKey, `${parsedEventId}`);
                 return results;
             }
             // Handle incoming event that listen key expired
@@ -522,14 +637,14 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                     // handle this how?
                     throw new Error('No context found within wsKey - fatal error with expired listen key');
                 }
-                this.logger.info(`${legacyContext.market} listenKey EXPIRED - attempting to respawn user data stream: ${wsKey}`, parsed);
+                this.logger.info(`${legacyContext.market} listenKey EXPIRED - attempting to respawn user data stream: ${wsKey}`, eventData);
                 // Just closing the connection (with the last parameter as true) will handle cleanup and respawn
                 // Automatically leads to triggerCustomReconnectionWorkflow() to handle fresh user data respawn
                 this.getUserDataStreamManager().teardownUserDataListenKey(legacyContext.listenKey, this.getWsStore().getWs(wsKey));
                 this.executeReconnectableClose(wsKey, 'listenKeyExpired');
             }
             if (this.options.beautify) {
-                const beautifiedMessage = this.beautifier.beautifyWsMessage(parsed, eventType, false, 
+                const beautifiedMessage = this.beautifier.beautifyWsMessage(eventData, eventType, false, 
                 // Suffix all events for the beautifier, if market is options
                 // Options has some conflicting keys with different intentions, so will be suffixed
                 wsKey === 'eoptions' ? 'Options' : '');
@@ -540,19 +655,7 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                 });
                 // emit an additional event for user data messages
                 if (!Array.isArray(beautifiedMessage) && eventType) {
-                    if ([
-                        'balanceUpdate',
-                        'executionReport',
-                        'listStatus',
-                        'listenKeyExpired',
-                        'outboundAccountPosition',
-                        'ACCOUNT_CONFIG_UPDATE',
-                        'ACCOUNT_UPDATE',
-                        'MARGIN_CALL',
-                        'ORDER_TRADE_UPDATE',
-                        'TRADE_LITE',
-                        'CONDITIONAL_ORDER_TRIGGER_REJECT',
-                    ].includes(eventType)) {
+                    if (websocket_util_1.EVENT_TYPES_USER_DATA.includes(eventType)) {
                         results.push({
                             eventType: 'formattedUserDataMessage',
                             event: beautifiedMessage,
@@ -565,25 +668,25 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             if (typeof eventType === 'string') {
                 results.push({
                     eventType: 'message',
-                    event: (parsed === null || parsed === void 0 ? void 0 : parsed.data) ? parsed.data : parsed,
+                    event: (eventData === null || eventData === void 0 ? void 0 : eventData.data) ? eventData.data : eventData,
                 });
                 return results;
             }
             // Messages that are a "reply" to a request/command (e.g. subscribe to these topics) typically include the "op" property
             if (typeof eventType === 'string') {
                 // Failed request
-                if (parsed.success === false) {
+                if (eventData.success === false) {
                     results.push({
                         eventType: 'exception',
-                        event: parsed,
+                        event: eventData,
                     });
                     return results;
                 }
-                // These are r  equest/reply pattern events (e.g. after subscribing to topics or authenticating)
+                // These are request/reply pattern events (e.g. after subscribing to topics or authenticating)
                 if (EVENTS_RESPONSES.includes(eventType)) {
                     results.push({
                         eventType: 'response',
-                        event: parsed,
+                        event: eventData,
                     });
                     return results;
                 }
@@ -591,19 +694,19 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                 if (EVENTS_AUTHENTICATED.includes(eventType)) {
                     results.push({
                         eventType: 'authenticated',
-                        event: parsed,
+                        event: eventData,
                     });
                     return results;
                 }
-                this.logger.error(`!! Unhandled string operation type "${eventType}". Defaulting to "update" channel...`, parsed);
+                this.logger.error(`!! Unhandled string operation type "${eventType}". Defaulting to "update" channel... raw event:`, JSON.stringify(parsedEvent));
             }
             else {
-                this.logger.error(`!!!! Unhandled non-string event type "${eventType}". Defaulting to "update" channel...`, parsed);
+                this.logger.error(`!!!! Unhandled non-string event type "${eventType}". Defaulting to "update" channel... raw event:`, JSON.stringify(parsedEvent));
             }
             // In case of catastrophic failure, fallback to noisy emit update
             results.push({
                 eventType: 'message',
-                event: parsed,
+                event: eventData,
             });
         }
         catch (e) {
@@ -650,7 +753,9 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
         });
     }
     /**
-     * Subscribe to spot user data stream - listen key is automaticallyr generated. Calling multiple times only opens one connection.
+     * 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() {
         return __awaiter(this, arguments, void 0, function* (wsKey = 'main', forceNewConnection, miscState) {
@@ -672,8 +777,13 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             }
         });
     }
+    unsubscribeSpotUserDataStream(wsKey = 'main') {
+        return this.closeUserDataStream(wsKey, 'spot');
+    }
     /**
-     * Subscribe to margin user data stream - listen key is automatically generated.
+     * 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() {
         return __awaiter(this, arguments, void 0, function* (wsKey = 'main', forceNewConnection, miscState) {
@@ -691,8 +801,13 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             }
         });
     }
+    unsubscribeCrossMarginUserDataStream(wsKey = 'main') {
+        return this.closeUserDataStream(wsKey, 'crossMargin');
+    }
     /**
-     * Subscribe to isolated margin user data stream - listen key is automatically generated.
+     * 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_1) {
         return __awaiter(this, arguments, void 0, function* (symbol, wsKey = 'main', forceNewConnection, miscState) {
@@ -704,17 +819,27 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
                     symbol: lowerCaseSymbol,
                 });
                 const market = 'isolatedMargin';
-                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
+                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, Object.assign(Object.assign({}, miscState), { symbol }));
             }
             catch (e) {
                 this.logger.error('Failed to connect to isolated margin user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e, symbol }));
-                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribeIsolatedMarginUserDataStream()', wsKey,
-                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
+                this.emit('exception', {
+                    functionRef: 'subscribeIsolatedMarginUserDataStream()',
+                    wsKey,
+                    forceNewConnection,
+                    miscState: Object.assign(Object.assign({}, miscState), { symbol }),
+                    error: (e === null || e === void 0 ? void 0 : e.stack) || e,
+                });
             }
         });
     }
+    unsubscribeIsolatedMarginUserDataStream(symbol, wsKey = 'main') {
+        return this.closeUserDataStream(wsKey, 'isolatedMargin', symbol);
+    }
     /**
-     * Subscribe to margin risk user data stream - listen key is automatically generated.
+     * 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() {
         return __awaiter(this, arguments, void 0, function* (wsKey = 'main', forceNewConnection, miscState) {
@@ -732,6 +857,116 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             }
         });
     }
+    unsubscribeMarginRiskUserDataStream(wsKey = 'main') {
+        return this.closeUserDataStream(wsKey, 'riskDataMargin');
+    }
+    /**
+     * --------------------------
+     * 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() {
+        return __awaiter(this, arguments, void 0, function* (wsKey = 'usdm', // usdm | usdmTestnet
+        forceNewConnection, miscState) {
+            try {
+                const isTestnet = wsKey === websocket_util_1.WS_KEY_MAP.usdmTestnet;
+                const restClient = this.restClientCache.getUSDMRestClient(this.getRestClientOptions(), this.options.requestOptions);
+                const { listenKey } = yield restClient.getFuturesUserDataListenKey();
+                const market = isTestnet ? 'usdmTestnet' : 'usdm';
+                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
+            }
+            catch (e) {
+                this.logger.error('Failed to connect to USD Futures user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
+                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribeUsdFuturesUserDataStream()', wsKey,
+                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
+            }
+        });
+    }
+    unsubscribeUsdFuturesUserDataStream(wsKey = 'usdm') {
+        return this.closeUserDataStream(wsKey, 'usdm');
+    }
+    /**
+     * 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() {
+        return __awaiter(this, arguments, void 0, function* (wsKey = 'coinm', // coinm | coinmTestnet
+        forceNewConnection, miscState) {
+            try {
+                const isTestnet = wsKey === websocket_util_1.WS_KEY_MAP.coinmTestnet;
+                const { listenKey } = yield this.restClientCache
+                    .getCOINMRestClient(this.getRestClientOptions(), this.options.requestOptions)
+                    .getFuturesUserDataListenKey();
+                const market = isTestnet ? 'coinmTestnet' : 'coinm';
+                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
+            }
+            catch (e) {
+                this.logger.error('Failed to connect to COIN Futures user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
+                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribeCoinFuturesUserDataStream()', wsKey,
+                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
+            }
+        });
+    }
+    unsubscribeCoinFuturesUserDataStream(wsKey = 'coinm') {
+        return this.closeUserDataStream(wsKey, 'coinm');
+    }
+    /**
+     * 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() {
+        return __awaiter(this, arguments, void 0, function* (wsKey = 'portfolioMarginUserData', forceNewConnection, miscState) {
+            try {
+                const { listenKey } = yield this.restClientCache
+                    .getPortfolioClient(this.getRestClientOptions(), this.options.requestOptions)
+                    .getPMUserDataListenKey();
+                const market = 'portfoliom';
+                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
+            }
+            catch (e) {
+                this.logger.error('Failed to connect to Portfolio Margin user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
+                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribePortfolioMarginUserDataStream()', wsKey,
+                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
+            }
+        });
+    }
+    unsubscribePortfolioMarginUserDataStream(wsKey = 'portfolioMarginUserData') {
+        return this.closeUserDataStream(wsKey, 'portfoliom');
+    }
+    /**
+     * 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, wsMarket, symbol) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const wsKeys = this.getWsStore().getKeys();
+            const userDataWsKey = wsKeys.find((key) => {
+                if (key === wsKey) {
+                    return true;
+                }
+                // built around the assumption in how per-connection listen key wskeys are created
+                // isolatedMargin_userData_BTCUSDC_6RszN123x213x1233x213x1233x213xx123x1uzkTV_main
+                // coinm_userData__WRAVTxGaQa1Nhd1243312kjn13kj12n3m5wRFv6JoFQgwUR5AEFofZtlk_coinm
+                const symbolSuffix = symbol ? '_' + symbol : '';
+                const prefixMatch = wsMarket + '_userData' + symbolSuffix;
+                return key.startsWith(prefixMatch) && key.endsWith(wsKey);
+            });
+            if (!userDataWsKey) {
+                throw new Error(`No matching connection found with wsKey "${wsKey}". Active connections: ${JSON.stringify(wsKeys)}`);
+            }
+            // todo: close?
+            this.close(userDataWsKey);
+        });
+    }
     isCustomReconnectionNeeded(wsKey) {
         return wsKey.includes('userData');
     }
@@ -824,83 +1059,6 @@ class WebsocketClient extends BaseWSClient_1.BaseWebsocketClient {
             }
         });
     }
-    /**
-     * --------------------------
-     * End of SPOT market websocket streams
-     * --------------------------
-     **/
-    /**
-     * Subscribe to USD-M Futures user data stream - listen key is automatically generated.
-     */
-    subscribeUsdFuturesUserDataStream() {
-        return __awaiter(this, arguments, void 0, function* (wsKey = 'usdm', // usdm | usdmTestnet
-        forceNewConnection, miscState) {
-            try {
-                const isTestnet = wsKey === websocket_util_1.WS_KEY_MAP.usdmTestnet;
-                const restClient = this.restClientCache.getUSDMRestClient(this.getRestClientOptions(), this.options.requestOptions);
-                const { listenKey } = yield restClient.getFuturesUserDataListenKey();
-                const market = isTestnet ? 'usdmTestnet' : 'usdm';
-                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
-            }
-            catch (e) {
-                this.logger.error('Failed to connect to USD Futures user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
-                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribeUsdFuturesUserDataStream()', wsKey,
-                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
-            }
-        });
-    }
-    closeUserDataStream() {
-        return __awaiter(this, arguments, void 0, function* (wsKey = 'usdm') {
-            const wsKeys = this.getWsStore().getKeys();
-            const userDataWsKey = wsKeys.find((key) => {
-                return key === wsKey || key.startsWith(wsKey + '_userData');
-            });
-            if (!userDataWsKey) {
-                throw new Error(`No matching connection found with wsKey "${wsKey}". Active connections: [${JSON.stringify(wsKey)}]`);
-            }
-            this.close(userDataWsKey);
-        });
-    }
-    /**
-     * Subscribe to COIN-M Futures user data stream - listen key is automatically generated.
-     */
-    subscribeCoinFuturesUserDataStream() {
-        return __awaiter(this, arguments, void 0, function* (wsKey = 'coinm', // coinm | coinmTestnet
-        forceNewConnection, miscState) {
-            try {
-                const isTestnet = wsKey === websocket_util_1.WS_KEY_MAP.coinmTestnet;
-                const { listenKey } = yield this.restClientCache
-                    .getCOINMRestClient(this.getRestClientOptions(), this.options.requestOptions)
-                    .getFuturesUserDataListenKey();
-                const market = isTestnet ? 'coinmTestnet' : 'coinm';
-                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
-            }
-            catch (e) {
-                this.logger.error('Failed to connect to COIN Futures user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
-                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribeCoinFuturesUserDataStream()', wsKey,
-                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
-            }
-        });
-    }
-    /**
-     * Subscribe to Portfolio Margin user data stream - listen key is automatically generated.
-     */
-    subscribePortfolioMarginUserDataStream() {
-        return __awaiter(this, arguments, void 0, function* (wsKey = 'portfolioMarginUserData', forceNewConnection, miscState) {
-            try {
-                const { listenKey } = yield this.restClientCache
-                    .getPortfolioClient(this.getRestClientOptions(), this.options.requestOptions)
-                    .getPMUserDataListenKey();
-                const market = 'portfoliom';
-                return this.getUserDataStreamManager().subscribeGeneralUserDataStreamWithListenKey(wsKey, market, listenKey, forceNewConnection, miscState);
-            }
-            catch (e) {
-                this.logger.error('Failed to connect to Portfolio Margin user data', Object.assign(Object.assign({}, WS_LOGGER_CATEGORY), { error: e }));
-                this.emit('exception', Object.assign(Object.assign({ functionRef: 'subscribePortfolioMarginUserDataStream()', wsKey,
-                    forceNewConnection }, miscState), { error: (e === null || e === void 0 ? void 0 : e.stack) || e }));
-            }
-        });
-    }
     /**
      * Subscribe to the European Options user data stream - listen key is automatically generated.
      *