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

[tiagosiebler]

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

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.

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 has an incremental ID value used to uniquely identify individual requests.
• 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, 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]

Who wants to help stress test the latest Bybit SDK? I have been heavily testing on the go, and the automated tests are still all passing without any code change, but this next phase is important.

The latest changes (including the REST-like WS API integration) are now available as a beta release:

npm install bybit-api@beta

You can test on testnet and/or demo trading if preferred. Even if you only test really simple things, the more testing the better - higher chance of catching any accidental mistakes.

Everything should work as it did before, even after upgrading to the beta release. Except for the few breaking changes I’ve documented in the PR, there should be no code change necessary to upgrade to this release. Impact of the few breaking changes should (hopefully) be relatively tiny:
#398

If you notice any breaking changes I have not documented, or you’re not sure about a behaviour, please let me know - I’d rather double check something than risk missing it.

Even if you try it out and don’t notice any issues, please let me know - helps to know it’s been tested successfully! Even just a simple 👍 on the PR or comment would be great.

As always, you can ping me here, or in the telegram community, or drop me a private message on telegram.

[tiagosiebler]

Hello everyone, friendly reminder if you’re using the Node.js bybit-api SDK for Bybit, would appreciate any help you can provide in testing the latest beta version before the next major release!

Even the simplest testing, even on testnet, would help - this is the last push to catch any issues that might have slipped through the cracks.

Bonus appreciation if you can help stress test the latest upgrades to the WebsocketClient. Subscribe to tons of topics. Mess around with your network. Even better if you can try out the WS API.

More info here: #398 (comment)

[tiagosiebler]

Published two key updates:

• 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.

[tiagosiebler]

Published a small beta release:

• 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.

[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