v4.0.0: WebSocket API, WebsocketClient upgrades, decommission deprecated v1-v3 API groups

[tiagosiebler]

Released

The release is now live, as of v4.0.0 on npm. Like/retweet/follow the announcement on X:
https://x.com/quantSDKs/status/1896897683526222318

Public Beta

The public beta release is now available on npm.

npm install bybit-api@beta

Summary

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

Key points, with further details below:

• Upgraded the WebsocketClient in line with the newer generation found in my newer SDKs.
• Added integration for the WebSocket API (send orders via WS, await responses). See Add support for the new Websocket API #344.
• Authentication now uses the Web Crypto API for request sign, both for REST & WS. See Web Crypto API #321.
• Upgraded build version to Node LTS.
• Misc dependency updates:
  • Axios to 1.7.9
  • @types/node to LTS
  • typescript to 5.7.3
• Removed decommissioned V1-V3 REST APIs and WebSockets. See Deprecation of V1-V3 REST APIs #375.
• Renamed "error" event to "exception". See WebsocketClient.on("error") event throws type error "Argument of type '(data: any) => void' is not assignable to parameter of type 'never'" #413.
• 4.0.0-beta.4: fixed demo trading wss url mapping, so it is not used for market data. Fixes Outdated documentation #411 (already in master).
• 4.0.0-beta.5: BREAKING CHANGE - deprecated "error" event in favour of new "exception" event. More info in top PR message.
• 4.0.0-beta.6: sync with master. BREAKING CHANGE - ws.subscribe() will NOT use a promise by default. You can opt in by using the promiseSubscribeRequests: true configuration in the WS client.
• 4.0.0-beta.7: feat(feat(): added/updated types with latest documentation changes #419) add/update REST types matching latest changes in API docs
• 4.0.0-beta.8 & 9: add support for bybit's new Websocket API batch order commands: https://bybit-exchange.github.io/docs/v5/websocket/trade/guideline#batch-createamendcancel-order

Major Changes

Auth/Performance (REST & WS)

• 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 Web Crypto API #321 for context.
• Add customSignMessageFn() parameter to WebsocketClient and RestClientV5.
  • 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).

WebsocketClient

• The market setting in the constructor is now optional.
  • Unless market is specified, it will use v5 by default.
• Introduced sendWSAPIRequest(WS_KEY_MAP.v5PrivateTrade, command, parameters) method to send WS API requests. See examples/ws-api-promises.ts for examples.

Breaking Changes

REST Clients

• Removed decommissioned V1-V3 REST clients.
  • Except for one endpoint, these have been decommissioned for a while (or are imminently going offline).
  • Anyone still using any should upgrade to V5, as they are at risk of going offline at any moment.

WebsocketClient

• Renamed "error" emitted event to "exception".
  • Emitting an "error" event had the unintended consequence of throwing an handled exception.
  • See: Outdated documentation #411
  • See: EventEmitter throws when emitting 'error' nodejs/node#3103
  • See: https://nodejs.org/api/events.html#error-events
  • Since the internal use of the "error" event doesn't emit an Error instance, and with the use of promises internally, this can lead to nasty unhandled exceptions that are difficult to trace and very difficult to handle properly.
  • In an effort to make this more obvious, the error event will throw a type error if you try to use it. See WebsocketClient.on("error") event throws type error "Argument of type '(data: any) => void' is not assignable to parameter of type 'never'" #413.
• Removed subscribeV3 and unsubscribeV3 methods. The V3 (& older) WebSockets have been deprecated for a while now.
• Consolidated the internal DefaultLogger methods.
  • Into 3 key levels: trace | info | error.
  • Similar to the silly level before this release, the trace level is disabled/silent by default.
• All connect calls now return a promise resolving to WSConnectedResult, instead of the raw WebSocket.
  • This is a simple object containing the WsKey (which can be used to retrieve the raw WebSocket, if needed).
• The "req_id" property shown in ws responses now:
  • For responses to subscribe/unsubscribe requests, has not changed.
  • For responses to all other ws requests/commands, it now has an incremental ID value used to uniquely identify individual requests.
  • This was previously a comma-separated list of topics for that event.
• Deprecated fetchTimeOffsetBeforeAuth.
• Minimal support for using await when subscribing to topics:
  • To reduce the risk of unexpected unhandled promise rejections, this feature is disabled by default. See promiseSubscribeRequests in the WS client configuration.
  • This was originally added in a contributor PR (#218 Returning a promise when subscribing to topic(s) #256), but designing a robust implementation around this introduces quite a bit of complexity.
  • When subscribing to multiple topics in one call, these are automatically batched into smaller requests (to stay within the max-topics-per-request limit).
  • The only way to track which "request" resolved/rejected successfully, requires including a "request id" with the subscribe request, since the confirmation from Bybit does not include a list of successfully subscribed topics.
  • Multiple subscribe requests = multiple promises (array of promises) returned by the subscribeV5 call.
  • The new implementation is an improvement in tracking this reliably, but if you see issues with complex case scenarios (mixing public & private topics in one request), I recommend that you design your own implementation using the "response" and "exception" events.
  • The current design will only work if the connection is opened before making the subscribe call, due to the queued subscription & request batching processes. It's therefore recommended that you do that first, before expecting to await subscribe:

  try {
    console.log('connecting private & public');

    await wsClient.assertIsConnected(WS_KEY_MAP.v5LinearPublic);
    await wsClient.assertIsConnected(WS_KEY_MAP.v5Private);
    await wsClient.assertIsAuthenticated(WS_KEY_MAP.v5Private);

    console.log('should be connected now. subscribing to topics');
    const subRequest = wsClient.subscribeV5(
      ['order', 'wallet', 'position', 'execution'],
      'linear',
    );

    const results = await Promise.all(subRequest);

    console.log(
      'should be subscribed',
      JSON.stringify(results, null, 2),
    );
  } catch (e) {
    console.error('exception subscribing to topics: ', e);
  }

Additional Information

Self todo notes

• Readme updates
• Check any internal logic that assumed req_id had topics in it.
• Check subscription req works the same as before
• Check subscriptions responses are the same behaviour
• Check public data arrives in same format as before
• Check private data arrives in same format as before
• Stress testing public ws
• Stress testing private data
• Check exceptions are emitted in the same format as before
• Test on-connect promise assertion.
• Test on-subscribe promise assertion subscribeV5 unsubscribeV5 promise not resolved #399
• Stress test bulk-subscribe public ws
• Stress test error handling
• Stress test topic deduping

[tiagosiebler]

Published a small beta release:

• 4.0.0-beta.7: feat(feat(): added/updated types with latest documentation changes #419) add/update REST types matching latest changes in API docs

[tiagosiebler]

Published a small beta release:

• feat(v4.0.0-beta.8): add support for bybit's new Websocket API batch order commands: https://bybit-exchange.github.io/docs/v5/websocket/trade/guideline#batch-createamendcancel-order

Unless any issues are discovered, this is most likely the final beta release before the major release goes live.

[tiagosiebler]

Published a small beta release:

• v4.0.0-beta.9: fix() batch order ws api handling

Unless any issues are discovered, this is most likely the final beta release before the major release goes live.

[tiagosiebler]

Final self-review complete. Awaiting CI/CD checks.