WIP: WSAPI & Multiplex WebSockets

[tiagosiebler]

Summary

This major release brings major upgrades to the Node.js, TypeScript & JavaScript SDK for Binance's REST APIs and WebSockets.

Key points, with further details below:

• BREAKING CHANGE: Previous WebsocketClient has been renamed to WebsocketClientV1.
• Potentially BREAKING CHANGE: Introduced NEW WebsocketClient:
  • Capable of live subscribing/unsubscribing (multiplex websockets)
  • Supports all userData streams available on Binance.
  • Supports all available WS APIs available on Binance.
• WIP: Added integration for the WebSocket API (send orders via WS, await responses). See Add support for WebSocket API (allows placing orders, canceling orders, etc. through a WebSocket connection) #283.
• WIP: Authentication now uses the Web Crypto API for request sign, both for REST & WS. See small mistake in the spelling of get24hrChangeStatististics #321.
• Upgraded build version to Node LTS.
• Misc dependency updates:
  • Axios to 1.7.9
  • @types/node to LTS
  • typescript to 5.7.3

Major Changes

Auth/Performance (REST & WS)

• TODO: Use the Web Crypto API for request sign/auth by default.
  • This is marginally slower than node's native crypto module, but provides better compatibility with browser environments.
  • See for context: Web Crypto API bybit-api#321
• TODO: Add customSignMessageFn() parameter to WebsocketClient and REST clients.
  • If you're latency sensitive, use this to inject a custom sign method to use something faster than the Web Crypto API.
  • See the examples/fasterHmacSign.ts example for a demonstration on using the faster node crypto createHmac function instead (same behaviour as before this upgrade).

Breaking Changes

WebsocketClientV1

• The existing WebsocketClient from the previous release has been renamed to WebsocketClientV1.
  • This should be considered the "legacy" WebsocketClient.
  • It still behaves as before, dedicating one WebSocket connection for every subscribed topic.
  • Note: this WebSocket client may be deprecated in future.
  • Detailed behaviour can be seen in the following example: https://github.com/tiagosiebler/binance/blob/wsapi/examples/ws-public-old.ts
• Consolidated the internal DefaultLogger methods, in line with my other SDKs
  • Into 3 key levels: trace | info | error.
  • Similar to the silly level before this release, the trace level is disabled/silent by default.

WebsocketClient

• Introduced a new WebsocketClient, designed around multiplex WebSocket subscriptions.
  • When subscribing to multiple topics within the same product group, it will automatically use one connection for all topics supported by that connection. This is significantly faster than the legacy WS Client, since you will no longer need thousands of connections for thousands of topics.
  • If a topic requires a different connection (e.g. a different subdomain), it will automatically handle all connectivity and event routing.
  • Detailed usage examples can be seen here: https://github.com/tiagosiebler/binance/blob/wsapi/examples/ws-public.ts#L71
• For backwards compatibility:
  • Existing "subscribe*" methods are available that exactly match the event behaviour seen in the legacy WS client.
  • Events behave and look the same, thanks to minimal internal processing in how events are received and handled.
• Key breaking changes:
  • The "wsKey" will no longer uniquely identify the topic an event is for, since it represents the connection the event came from (and one connection may have multiple subscribed topics).
  • Consolidated the internal DefaultLogger methods, in line with my other SDKs
    • Into 3 key levels: trace | info | error.
    • Similar to the silly level before this release, the trace level is disabled/silent by default.

High level checklist

• Public WS subscription on multiplex connection.
• Is everything consistent and intuitive across different products?
• Testnet
• Listenkey subscription on DEDICATED connection.
• spot
• other markets
• testnets
• workflows for closing user data stream
• workflows for closing all websockets, including user data streams
• reconnection workflows (quick)
• reconnection workflows (slow, with disconnect for hours)
• reconnection workflow ALWAYS emits reconnected event, even for user data with new listen key
• listenkey expiration (e.g. call delete listen key endpoint in parallel - ws client should handle refresh)
• Listenkey subscription on multiplex connection.
• Testnet listenkey
• Testnet market data
• Testnet REST APIs
• WS API commands
• update examples to use new WS client. Should be plug and play! Test!

[socket-security]

New and updated dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher
npm/axios@1.7.9 🔁 npm/axios@1.7.7	Transitive: environment, filesystem	+8	2.5 MB	jasonsaayman
npm/ts-jest@29.2.5 🔁 npm/ts-jest@29.1.1	Transitive: eval, network, shell	+156	15.5 MB	kul
npm/typescript@5.7.3 🔁 npm/typescript@4.9.5	None	0	22.7 MB	typescript-bot

View full report↗︎