fix(futures-ws): reject mixed-category combined streams

.github/workflows/js.yml

@@ -33,6 +33,8 @@ jobs:
       run: npm run ts-test-static
     - name: Static Tests (JS CJS)
       run: npm run static-test
+    - name: Futures WS endpoint migration tests
+      run: npm run ws-tests-migration
     - name: Live Tests (TS ESM)
       run: npm run ts-test-live
     - name: CJS test

package.json

@@ -32,6 +32,7 @@
     "ws-tests": "mocha ./tests/binance-class-ws.test.ts",
     "ws-tests-spot": "mocha ./tests/binance-ws-spot.test.ts --exit",
     "ws-tests-futures": "mocha ./tests/binance-ws-futures.test.ts --exit",
+    "ws-tests-migration": "mocha ./tests/ws-endpoints-migration.test.ts --fgrep \"Live:\" --invert --exit",
     "ws-api-userdata-tests": "mocha ./tests/binance-ws-api-userdata.test.ts --exit",
     "ws-live-tests": "mocha ./tests/binance-ws-spot.test.ts ./tests/binance-ws-futures.test.ts ./tests/binance-ws-api-userdata.test.ts ./tests/binance-ws-api-ticker.test.ts --exit",
     "test-debug": "mocha --inspect-brk",

src/node-binance-api.ts

@@ -1862,7 +1862,16 @@ export default class Binance {
         const httpsproxy = this.getHttpsProxy();
         let socksproxy = this.getSocksProxy();
         const queryParams = streams.join('/');
+        // Binance routes USDⓈ-M futures streams to separate endpoints by category
+        // (/public, /market, /private) and will not push cross-category streams on a
+        // single connection. Reject mixed-category combos so they fail loudly instead
+        // of silently dropping data — subscribe to each category on its own connection.
         const category = this.classifyFuturesStream(streams[0]);
+        const mismatch = streams.find(s => this.classifyFuturesStream(s) !== category);
+        if (mismatch !== undefined) {
+            const mismatchCategory = this.classifyFuturesStream(mismatch);
+            throw new Error(`futuresSubscribe: cannot combine '${category}' stream "${streams[0]}" with '${mismatchCategory}' stream "${mismatch}" on one connection. Binance routes futures streams to separate /public, /market and /private endpoints; subscribe to each category separately.`);
+        }
         const baseUrl = this.getFStreamUrl(category);
         let ws: any = undefined;
         if (socksproxy) {

tests/ws-endpoints-migration.test.ts

@@ -152,6 +152,34 @@ describe('Private stream URL uses query params for listenKey', function () {
     });
 });
 
+describe('futuresSubscribe rejects mixed-category combined streams', function () {
+    const listenKey = 'pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a1a65a1a5s61cv6a81va65sd';
+
+    it('throws when mixing market and public streams', function () {
+        assert.throws(
+            () => binance.futuresSubscribe(['btcusdt@aggTrade', 'btcusdt@depth'], () => { }),
+            /cannot combine/
+        );
+    });
+
+    it('throws when mixing public and private streams', function () {
+        assert.throws(
+            () => binance.futuresSubscribe(['btcusdt@bookTicker', listenKey], () => { }),
+            /cannot combine/
+        );
+    });
+
+    it('names both offending categories in the error message', function () {
+        try {
+            binance.futuresSubscribe(['btcusdt@markPrice', 'btcusdt@bookTicker'], () => { });
+            assert.fail('expected futuresSubscribe to throw');
+        } catch (e) {
+            assert.match(e.message, /market/);
+            assert.match(e.message, /public/);
+        }
+    });
+});
+
 describe('Live: production market stream (aggTrade via /market/)', function () {
     let trade;
     let cnt = 0;