From 7d49420c79910f8667d98c97e3c316a22bb89e25 Mon Sep 17 00:00:00 2001 From: Pablo Date: Mon, 6 Apr 2026 02:32:21 +0200 Subject: [PATCH 1/5] =?UTF-8?q?feat:=20migrate=20USD=E2=93=88-M=20futures?= =?UTF-8?q?=20WS=20to=20/public=20/market=20/private=20endpoints?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Route futures WebSocket streams to Binance's new category-based URLs per the 2026-03-06 upgrade notice. Legacy URLs retire 2026-04-23. --- src/node-binance-api.ts | 40 ++++-- tests/ws-endpoints-migration.test.ts | 192 +++++++++++++++++++++++++++ 2 files changed, 224 insertions(+), 8 deletions(-) create mode 100644 tests/ws-endpoints-migration.test.ts diff --git a/src/node-binance-api.ts b/src/node-binance-api.ts index 16508f10..70b1f45b 100644 --- a/src/node-binance-api.ts +++ b/src/node-binance-api.ts @@ -294,15 +294,35 @@ export default class Binance { return this.dstreamSingle; } - getFStreamSingleUrl() { + /** + * Classify a futures stream endpoint into public, market, or private category + * per Binance USDⓈ-M Futures WebSocket URL split (2026-03-06) + */ + classifyFuturesStream(endpoint: string): 'public' | 'market' | 'private' { + // Public: bookTicker and depth streams (high-frequency) + if (endpoint.includes('@bookTicker') || endpoint === '!bookTicker' + || endpoint.includes('@depth')) { + return 'public'; + } + // Private: listenKey strings (no @ or ! prefix) + if (!endpoint.includes('@') && !endpoint.startsWith('!')) { + return 'private'; + } + // Market: everything else (aggTrade, markPrice, kline, ticker, miniTicker, forceOrder, etc.) + return 'market'; + } + + getFStreamSingleUrl(category?: 'public' | 'market' | 'private') { if (this.Options.demo) return this.fstreamSingleDemo; if (this.Options.test) return this.fstreamSingleTest; + if (category) return `wss://fstream.binance.${this.domain}/${category}/ws/`; return this.fstreamSingle; } - getFStreamUrl() { + getFStreamUrl(category?: 'public' | 'market' | 'private') { if (this.Options.demo) return this.fstreamDemo; if (this.Options.test) return this.fstreamTest; + if (category) return `wss://fstream.binance.${this.domain}/${category}/stream?streams=`; return this.fstream; } @@ -1772,6 +1792,8 @@ export default class Binance { const httpsproxy = this.getHttpsProxy(); let socksproxy = this.getSocksProxy(); let ws: any = undefined; + const category = this.classifyFuturesStream(endpoint); + const baseUrl = this.getFStreamSingleUrl(category); if (socksproxy) { socksproxy = this.proxyReplacewithIp(socksproxy); @@ -1781,14 +1803,14 @@ export default class Binance { host: this.parseProxy(socksproxy)[1], port: this.parseProxy(socksproxy)[2] }); - ws = new WebSocket((this.getFStreamSingleUrl()) + endpoint, { agent }); + ws = new WebSocket(baseUrl + endpoint, { agent }); } else if (httpsproxy) { const config = url.parse(httpsproxy); const agent = new HttpsProxyAgent(config); if (this.Options.verbose) this.Options.log(`futuresSubscribeSingle: using proxy server: ${agent}`); - ws = new WebSocket((this.getFStreamSingleUrl()) + endpoint, { agent }); + ws = new WebSocket(baseUrl + endpoint, { agent }); } else { - ws = new WebSocket((this.getFStreamSingleUrl()) + endpoint); + ws = new WebSocket(baseUrl + endpoint); } if (this.Options.verbose) this.Options.log('futuresSubscribeSingle: Subscribed to ' + endpoint); @@ -1827,6 +1849,8 @@ export default class Binance { const httpsproxy = this.getHttpsProxy(); let socksproxy = this.getSocksProxy(); const queryParams = streams.join('/'); + const category = this.classifyFuturesStream(streams[0]); + const baseUrl = this.getFStreamUrl(category); let ws: any = undefined; if (socksproxy) { socksproxy = this.proxyReplacewithIp(socksproxy); @@ -1836,14 +1860,14 @@ export default class Binance { host: this.parseProxy(socksproxy)[1], port: this.parseProxy(socksproxy)[2] }); - ws = new WebSocket(this.getFStreamUrl() + queryParams, { agent }); + ws = new WebSocket(baseUrl + queryParams, { agent }); } else if (httpsproxy) { if (this.Options.verbose) this.Options.log(`futuresSubscribe: using proxy server ${httpsproxy}`); const config = url.parse(httpsproxy); const agent = new HttpsProxyAgent(config); - ws = new WebSocket(this.getFStreamUrl() + queryParams, { agent }); + ws = new WebSocket(baseUrl + queryParams, { agent }); } else { - ws = new WebSocket(this.getFStreamUrl() + queryParams); + ws = new WebSocket(baseUrl + queryParams); } ws.reconnect = this.Options.reconnect; diff --git a/tests/ws-endpoints-migration.test.ts b/tests/ws-endpoints-migration.test.ts new file mode 100644 index 00000000..3dad1919 --- /dev/null +++ b/tests/ws-endpoints-migration.test.ts @@ -0,0 +1,192 @@ +import Binance from '../src/node-binance-api'; +import { assert } from 'chai'; + +const TIMEOUT = 30000; + +// Production instance (no auth needed for public/market streams) +const binance = new Binance(); + +// Demo instance for private stream test +const demoBinance = new Binance().options({ + APIKEY: process.env.BINANCE_APIKEY || '', + APISECRET: process.env.BINANCE_SECRET || '', + demo: true, +}); + +const stopSockets = function (instance) { + const endpoints = instance.websockets.subscriptions(); + for (const endpoint in endpoints) { + instance.websockets.terminate(endpoint); + } +}; + +describe('classifyFuturesStream', function () { + it('classifies bookTicker as public', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@bookTicker'), 'public'); + assert.equal(binance.classifyFuturesStream('!bookTicker'), 'public'); + }); + + it('classifies depth streams as public', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@depth'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth@100ms'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth@500ms'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth5'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth10'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth20'), 'public'); + assert.equal(binance.classifyFuturesStream('btcusdt@depth5@100ms'), 'public'); + }); + + it('classifies aggTrade as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@aggTrade'), 'market'); + }); + + it('classifies markPrice as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@markPrice'), 'market'); + assert.equal(binance.classifyFuturesStream('btcusdt@markPrice@1s'), 'market'); + assert.equal(binance.classifyFuturesStream('!markPrice@arr'), 'market'); + assert.equal(binance.classifyFuturesStream('!markPrice@arr@1s'), 'market'); + }); + + it('classifies kline as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@kline_1m'), 'market'); + }); + + it('classifies ticker as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@ticker'), 'market'); + assert.equal(binance.classifyFuturesStream('!ticker@arr'), 'market'); + }); + + it('classifies miniTicker as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@miniTicker'), 'market'); + assert.equal(binance.classifyFuturesStream('!miniTicker@arr'), 'market'); + }); + + it('classifies forceOrder as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@forceOrder'), 'market'); + assert.equal(binance.classifyFuturesStream('!forceOrder@arr'), 'market'); + }); + + it('classifies compositeIndex as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@compositeIndex'), 'market'); + }); + + it('classifies contractInfo as market', function () { + assert.equal(binance.classifyFuturesStream('!contractInfo'), 'market'); + }); + + it('classifies assetIndex as market', function () { + assert.equal(binance.classifyFuturesStream('btcusdt@assetIndex'), 'market'); + assert.equal(binance.classifyFuturesStream('!assetIndex@arr'), 'market'); + }); + + it('classifies listenKey as private', function () { + assert.equal(binance.classifyFuturesStream('pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a1a65a1a5s61cv6a81va65sd'), 'private'); + }); +}); + +describe('getFStreamSingleUrl with category', function () { + it('returns public ws URL', function () { + assert.equal(binance.getFStreamSingleUrl('public'), 'wss://fstream.binance.com/public/ws/'); + }); + it('returns market ws URL', function () { + assert.equal(binance.getFStreamSingleUrl('market'), 'wss://fstream.binance.com/market/ws/'); + }); + it('returns private ws URL', function () { + assert.equal(binance.getFStreamSingleUrl('private'), 'wss://fstream.binance.com/private/ws/'); + }); + it('returns legacy URL without category', function () { + assert.equal(binance.getFStreamSingleUrl(), 'wss://fstream.binance.com/ws/'); + }); +}); + +describe('getFStreamUrl with category', function () { + it('returns public stream URL', function () { + assert.equal(binance.getFStreamUrl('public'), 'wss://fstream.binance.com/public/stream?streams='); + }); + it('returns market stream URL', function () { + assert.equal(binance.getFStreamUrl('market'), 'wss://fstream.binance.com/market/stream?streams='); + }); + it('returns private stream URL', function () { + assert.equal(binance.getFStreamUrl('private'), 'wss://fstream.binance.com/private/stream?streams='); + }); + it('returns legacy URL without category', function () { + assert.equal(binance.getFStreamUrl(), 'wss://fstream.binance.com/stream?streams='); + }); +}); + +describe('Demo mode ignores category (uses legacy URLs)', function () { + it('getFStreamSingleUrl returns demo URL regardless of category', function () { + assert.equal(demoBinance.getFStreamSingleUrl('market'), 'wss://fstream.binancefuture.com/ws/'); + }); + it('getFStreamUrl returns demo URL regardless of category', function () { + assert.equal(demoBinance.getFStreamUrl('market'), 'wss://fstream.binancefuture.com/stream?streams='); + }); +}); + +describe('Live: production market stream (aggTrade via /market/)', function () { + let trade; + let cnt = 0; + + beforeEach(function (done) { + this.timeout(TIMEOUT); + binance.futuresAggTradeStream('BTCUSDT', a_trade => { + cnt++; + if (cnt > 1) return; + trade = a_trade; + stopSockets(binance); + done(); + }); + }); + + it('receives aggTrade data from /market/ endpoint', function () { + assert(typeof trade === 'object', 'should be an object'); + assert(trade !== null, 'should not be null'); + assert(Object.prototype.hasOwnProperty.call(trade, 'symbol'), 'should have symbol'); + assert(Object.prototype.hasOwnProperty.call(trade, 'price'), 'should have price'); + }); +}); + +describe('Live: production public stream (bookTicker via /public/)', function () { + let ticker; + let cnt = 0; + + beforeEach(function (done) { + this.timeout(TIMEOUT); + binance.futuresBookTickerStream('BTCUSDT', a_ticker => { + cnt++; + if (cnt > 1) return; + ticker = a_ticker; + stopSockets(binance); + done(); + }); + }); + + it('receives bookTicker data from /public/ endpoint', function () { + assert(typeof ticker === 'object', 'should be an object'); + assert(ticker !== null, 'should not be null'); + assert(Object.prototype.hasOwnProperty.call(ticker, 'bestBid'), 'should have bestBid'); + assert(Object.prototype.hasOwnProperty.call(ticker, 'bestAsk'), 'should have bestAsk'); + }); +}); + +describe('Live: production combined market stream (kline via /market/)', function () { + let candle; + let cnt = 0; + + beforeEach(function (done) { + this.timeout(TIMEOUT); + binance.futuresCandlesticksStream(['BTCUSDT'], '1m', a_candle => { + cnt++; + if (cnt > 1) return; + candle = a_candle; + stopSockets(binance); + done(); + }); + }); + + it('receives kline data from /market/ combined stream', function () { + assert(typeof candle === 'object', 'should be an object'); + assert(candle !== null, 'should not be null'); + assert(Object.prototype.hasOwnProperty.call(candle, 'k'), 'should have kline data'); + }); +}); From 7e1a7f4af5222bcd321b7f2824228cd6c635f2d9 Mon Sep 17 00:00:00 2001 From: Pablo Date: Mon, 6 Apr 2026 02:45:33 +0200 Subject: [PATCH 2/5] fix: apply category-based WS URLs to demo and test environments too --- src/node-binance-api.ts | 12 ++++++++++-- tests/ws-endpoints-migration.test.ts | 22 ++++++++++++++++------ 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/src/node-binance-api.ts b/src/node-binance-api.ts index 70b1f45b..6c048b65 100644 --- a/src/node-binance-api.ts +++ b/src/node-binance-api.ts @@ -313,16 +313,24 @@ export default class Binance { } getFStreamSingleUrl(category?: 'public' | 'market' | 'private') { + if (category) { + if (this.Options.demo) return `wss://fstream.binancefuture.com/${category}/ws/`; + if (this.Options.test) return `wss://stream.binancefuture.${this.domain}/${category}/ws/`; + return `wss://fstream.binance.${this.domain}/${category}/ws/`; + } if (this.Options.demo) return this.fstreamSingleDemo; if (this.Options.test) return this.fstreamSingleTest; - if (category) return `wss://fstream.binance.${this.domain}/${category}/ws/`; return this.fstreamSingle; } getFStreamUrl(category?: 'public' | 'market' | 'private') { + if (category) { + if (this.Options.demo) return `wss://fstream.binancefuture.com/${category}/stream?streams=`; + if (this.Options.test) return `wss://stream.binancefuture.${this.domain}/${category}/stream?streams=`; + return `wss://fstream.binance.${this.domain}/${category}/stream?streams=`; + } if (this.Options.demo) return this.fstreamDemo; if (this.Options.test) return this.fstreamTest; - if (category) return `wss://fstream.binance.${this.domain}/${category}/stream?streams=`; return this.fstream; } diff --git a/tests/ws-endpoints-migration.test.ts b/tests/ws-endpoints-migration.test.ts index 3dad1919..cf18b20b 100644 --- a/tests/ws-endpoints-migration.test.ts +++ b/tests/ws-endpoints-migration.test.ts @@ -114,12 +114,22 @@ describe('getFStreamUrl with category', function () { }); }); -describe('Demo mode ignores category (uses legacy URLs)', function () { - it('getFStreamSingleUrl returns demo URL regardless of category', function () { - assert.equal(demoBinance.getFStreamSingleUrl('market'), 'wss://fstream.binancefuture.com/ws/'); - }); - it('getFStreamUrl returns demo URL regardless of category', function () { - assert.equal(demoBinance.getFStreamUrl('market'), 'wss://fstream.binancefuture.com/stream?streams='); +describe('Demo mode uses category-based URLs', function () { + it('getFStreamSingleUrl returns demo URL with category', function () { + assert.equal(demoBinance.getFStreamSingleUrl('public'), 'wss://fstream.binancefuture.com/public/ws/'); + assert.equal(demoBinance.getFStreamSingleUrl('market'), 'wss://fstream.binancefuture.com/market/ws/'); + assert.equal(demoBinance.getFStreamSingleUrl('private'), 'wss://fstream.binancefuture.com/private/ws/'); + }); + it('getFStreamUrl returns demo URL with category', function () { + assert.equal(demoBinance.getFStreamUrl('public'), 'wss://fstream.binancefuture.com/public/stream?streams='); + assert.equal(demoBinance.getFStreamUrl('market'), 'wss://fstream.binancefuture.com/market/stream?streams='); + assert.equal(demoBinance.getFStreamUrl('private'), 'wss://fstream.binancefuture.com/private/stream?streams='); + }); + it('getFStreamSingleUrl returns legacy demo URL without category', function () { + assert.equal(demoBinance.getFStreamSingleUrl(), 'wss://fstream.binancefuture.com/ws/'); + }); + it('getFStreamUrl returns legacy demo URL without category', function () { + assert.equal(demoBinance.getFStreamUrl(), 'wss://fstream.binancefuture.com/stream?streams='); }); }); From 570d88651460eebd2eb199080566cee905959f2c Mon Sep 17 00:00:00 2001 From: Pablo Date: Mon, 6 Apr 2026 02:50:40 +0200 Subject: [PATCH 3/5] refactor: use positive regex match for listenKey classification --- src/node-binance-api.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/node-binance-api.ts b/src/node-binance-api.ts index 6c048b65..f6f6150d 100644 --- a/src/node-binance-api.ts +++ b/src/node-binance-api.ts @@ -304,11 +304,11 @@ export default class Binance { || endpoint.includes('@depth')) { return 'public'; } - // Private: listenKey strings (no @ or ! prefix) - if (!endpoint.includes('@') && !endpoint.startsWith('!')) { + // Private: listenKey is a long alphanumeric string (60+ chars, no @ or !) + if (/^[A-Za-z0-9]{20,}$/.test(endpoint)) { return 'private'; } - // Market: everything else (aggTrade, markPrice, kline, ticker, miniTicker, forceOrder, etc.) + // Market: aggTrade, markPrice, kline, ticker, miniTicker, forceOrder, etc. return 'market'; } From 01e692180baf77f0fc7fe1030dbf325eca7278cd Mon Sep 17 00:00:00 2001 From: Pablo Date: Mon, 6 Apr 2026 02:55:17 +0200 Subject: [PATCH 4/5] fix: use query params for private listenKey URL per new Binance spec The new /private/ endpoint requires ?listenKey= format instead of the legacy path-based / format. --- src/node-binance-api.ts | 10 +++++++--- tests/ws-endpoints-migration.test.ts | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/src/node-binance-api.ts b/src/node-binance-api.ts index f6f6150d..4ff0947c 100644 --- a/src/node-binance-api.ts +++ b/src/node-binance-api.ts @@ -1802,6 +1802,10 @@ export default class Binance { let ws: any = undefined; const category = this.classifyFuturesStream(endpoint); const baseUrl = this.getFStreamSingleUrl(category); + // Private streams use query params: ?listenKey= instead of path: / + const wsUrl = category === 'private' + ? baseUrl.replace(/\/$/, '') + '?listenKey=' + endpoint + : baseUrl + endpoint; if (socksproxy) { socksproxy = this.proxyReplacewithIp(socksproxy); @@ -1811,14 +1815,14 @@ export default class Binance { host: this.parseProxy(socksproxy)[1], port: this.parseProxy(socksproxy)[2] }); - ws = new WebSocket(baseUrl + endpoint, { agent }); + ws = new WebSocket(wsUrl, { agent }); } else if (httpsproxy) { const config = url.parse(httpsproxy); const agent = new HttpsProxyAgent(config); if (this.Options.verbose) this.Options.log(`futuresSubscribeSingle: using proxy server: ${agent}`); - ws = new WebSocket(baseUrl + endpoint, { agent }); + ws = new WebSocket(wsUrl, { agent }); } else { - ws = new WebSocket(baseUrl + endpoint); + ws = new WebSocket(wsUrl); } if (this.Options.verbose) this.Options.log('futuresSubscribeSingle: Subscribed to ' + endpoint); diff --git a/tests/ws-endpoints-migration.test.ts b/tests/ws-endpoints-migration.test.ts index cf18b20b..97173da4 100644 --- a/tests/ws-endpoints-migration.test.ts +++ b/tests/ws-endpoints-migration.test.ts @@ -133,6 +133,25 @@ describe('Demo mode uses category-based URLs', function () { }); }); +describe('Private stream URL uses query params for listenKey', function () { + it('constructs ?listenKey= URL instead of path-based', function () { + const listenKey = 'pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a1a65a1a5s61cv6a81va65sd'; + const category = binance.classifyFuturesStream(listenKey); + const baseUrl = binance.getFStreamSingleUrl(category); + const wsUrl = baseUrl.replace(/\/$/, '') + '?listenKey=' + listenKey; + assert.equal(category, 'private'); + assert.equal(wsUrl, `wss://fstream.binance.com/private/ws?listenKey=${listenKey}`); + }); + + it('constructs query-param URL for demo too', function () { + const listenKey = 'pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a1a65a1a5s61cv6a81va65sd'; + const category = demoBinance.classifyFuturesStream(listenKey); + const baseUrl = demoBinance.getFStreamSingleUrl(category); + const wsUrl = baseUrl.replace(/\/$/, '') + '?listenKey=' + listenKey; + assert.equal(wsUrl, `wss://fstream.binancefuture.com/private/ws?listenKey=${listenKey}`); + }); +}); + describe('Live: production market stream (aggTrade via /market/)', function () { let trade; let cnt = 0; From 13a6fd84a8654b84919e31db648c320e7e461e74 Mon Sep 17 00:00:00 2001 From: Pablo Date: Mon, 6 Apr 2026 02:59:17 +0200 Subject: [PATCH 5/5] test: add live test for private/userFutureData stream --- tests/ws-endpoints-migration.test.ts | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/tests/ws-endpoints-migration.test.ts b/tests/ws-endpoints-migration.test.ts index 97173da4..cd8b3dda 100644 --- a/tests/ws-endpoints-migration.test.ts +++ b/tests/ws-endpoints-migration.test.ts @@ -198,6 +198,30 @@ describe('Live: production public stream (bookTicker via /public/)', function () }); }); +describe('Live: demo private stream (userFutureData via /private/)', function () { + let endpoint; + + beforeEach(function (done) { + this.timeout(TIMEOUT); + demoBinance.userFutureData( + undefined, // all_updates_callback + undefined, // margin_call_callback + undefined, // account_update_callback + undefined, // order_update_callback + (a_endpoint) => { // subscribed_callback + endpoint = a_endpoint; + stopSockets(demoBinance); + done(); + } + ); + }); + + it('connects to private user data stream successfully', function () { + assert(endpoint !== undefined, 'should have received subscription endpoint'); + assert(typeof endpoint === 'string', 'endpoint should be a string'); + }); +}); + describe('Live: production combined market stream (kline via /market/)', function () { let candle; let cnt = 0;