feat(v3.5.0, #653): add support for Binance USDM Futures base URL split & migration

[tiagosiebler]

Summary

• Bump dependencies after audit.
• Readme updates.
• Add more WebSocket documentation for more detailed guidance.
• No breaking changes expected, but USDM Futures WebSocket users may need to migrate in future when Binance deprecates the previous WS endpoint.
• Add complete support for new USDM Futures Base URL Split & Migration, with examples:
  • Action required: if you're using the wsClient.subscribe() methods, you must provide the correct WsKey. Refer to these examples for guidance:
    • USDM Public topics: https://github.com/tiagosiebler/binance/blob/master/examples/WebSockets/Public/ws-usdm-public.ts#L145-L152
    • USDM Market topics: https://github.com/tiagosiebler/binance/blob/master/examples/WebSockets/Public/ws-usdm-market.ts#L145-L151
    • USDM ListenKey User Data: https://github.com/tiagosiebler/binance/blob/master/examples/WebSockets/Private(userdata)/ws-userdata-listenkey.ts#L182-L186
    • USDM WS API User Data (recommended): https://github.com/tiagosiebler/binance/blob/master/examples/WebSockets/Private(userdata)/ws-userdata-wsapi.ts#L185

Base URL Split & Migration

On 06/03/2026, Binance announced a routing upgrade to their USDM Futures WebSocket System, titled: "Binance USDⓈ-M Futures WebSocket System Upgrade Notice (2026-03-06)".

Key Highlights:

• Introduction of three dedicated WebSocket base URLs:
  • Public (high-frequency public market data)
    • wss://fstream.binance.com/public
  • Market (regular market data)
    • wss://fstream.binance.com/market
  • Private (user data streams)
    • wss://fstream.binance.com/private
• New endpoints are supported immediately upon this announcement.
• Legacy WebSocket URLs will be permanently retired on 2026-04-23.
• Documentation including endpoint & stream mapping: https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams/Important-WebSocket-Change-Notice#public-high-frequency-public-data

Binance JavaScript SDK Support

All three dedicated WebSocket base URLs are supported. Each with their own unique WsKey, used to track each unique connection.

Continue to subscribe to market data as before with the dedicated subscribe method, but ensure to provide the connection key depending on the type of market data you are consuming.

Minimal examples:

// ...

// For public (high-frequency public data)
const wsKeyUsdmPublic = WS_KEY_MAP.usdmPublic;
wsClient.subscribe(['btcusdt@bookTicker', 'btcusdt@depth'], wsKeyUsdmPublic);

// For market (regular market data)
const wsKeyUsdmMarket = WS_KEY_MAP.usdmMarket;
wsClient.subscribe(['btcusdt@aggTrade', 'btcusdt@forceOrder'], wsKeyUsdmMarket);

// For user data, continue using the subscribe user data stream method as before.
// The SDK will automatically route to the "private" endpoint for USDM Futures:
wsClient.subscribeUsdFuturesUserDataStream();

Legacy wsClient.subscribe*() methods

If you're using any of the per-topic convenience methods, such as wsClient.subscribeAggregateTrades(...), no change is required. The SDK will automatically route the topic subscription request to the appropriate WS URL.

Further Reading

For detailed examples, refer to the examples in this folder, as well as the following documentation:

• Binance JavaScript SDK QuickStart Guide: https://siebly.io/sdk/binance/javascript
• Binance JavaScript SDK Tutorial: https://siebly.io/sdk/binance/javascript/tutorial
• Binance JavaScript SDK Readme: https://www.npmjs.com/package/binance

Additional Information

PR Checklist

As part of the PR, make sure you have:

• No breaking changes / documented all breaking changes clearly.
• Updated & checked that all tests pass.
• Increased the version number in the package.json
• Checked npm install runs without issue.
• Included the package-lock.json, if it changed after npm install
• Checked npm run build runs without issue.
• Updated the endpoint map (optional, if you know how).
• Run llms.txt generator (optional, if you know how).