Node.js & JavaScript SDK for Bybit REST API & WebSockets

Node.js & JavaScript SDK for the Bybit REST APIs and WebSockets:

• Complete integration with all Bybit REST APIs & WebSockets.
• Actively maintained with a modern, promise-driven interface.
• TypeScript support (with type declarations for most API requests & responses).
• Over 450 end-to-end tests making real API calls & WebSocket connections, validating any changes before they reach npm.
• Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows.
  • Event driven messaging.
  • Smart websocket persistence
    • Automatically handle silent websocket disconnections through timed heartbeats, including the scheduled 24hr disconnect.
    • Automatically handle listenKey persistence and expiration/refresh.
    • Emit reconnected event when dropped connection is restored.
• Proxy support via axios integration.
• Active community support & collaboration in telegram: Node.js Algo Traders.

Installation

npm install --save bybit-api

Issues & Discussion

• Issues? Check the issues tab.
• Discuss & collaborate with other node devs? Join our Node.js Algo Traders engineering community on telegram.
• Follow our announcement channel for real-time updates on X/Twitter

Related projects

Check out my related JavaScript/TypeScript/Node.js projects:

• Try my REST API & WebSocket SDKs:
  • Bybit-api Node.js SDK
  • Okx-api Node.js SDK
  • Binance Node.js SDK
  • Gateio-api Node.js SDK
  • Bitget-api Node.js SDK
  • Kucoin-api Node.js SDK
  • Coinbase-api Node.js SDK
  • Bitmart-api Node.js SDK
• Try my misc utilities:
  • OrderBooks Node.js
  • Crypto Exchange Account State Cache
• Check out my examples:
  • awesome-crypto-examples Node.js

Documentation

Most methods accept JS objects. These can be populated using parameters specified by Bybit's API documentation, or check the type definition in each class within the github repository (see table below for convenient links to each class).

• Bybit API Docs
• REST Endpoint Function List
• TSDoc Documentation (generated using typedoc via npm module)

Structure

This connector is fully compatible with both TypeScript and pure JavaScript projects, while the connector is written in TypeScript. A pure JavaScript version can be built using npm run build, which is also the version published to npm.

The version on npm is the output from the build command and can be used in projects without TypeScript (although TypeScript is definitely recommended).

• src - the whole connector written in TypeScript
• lib - the JavaScript version of the project (built from TypeScript). This should not be edited directly, as it will be overwritten with each release.
• examples - examples & demonstrations. Contributions are welcome!

REST API Clients

Bybit has several API groups (originally one per product). Each generation is labelled with the version number (e.g. v1/v2/v3/v5). New projects & developments should use the newest available API generation (e.g. use the V5 APIs instead of V3).

Refer to the V5 interface mapping page for more information on which V5 endpoints can be used instead of previous V3 endpoints.

Here are the available REST clients and the corresponding API groups described in the documentation:

Deprecated/Obsolete APIs

The following API clients are for previous generation REST APIs and will be removed in the next major release. Some have already stopped working (because bybit stopped supporting them). You should use the V5 APIs for all new development.

Examples for using each client can be found in:

• the examples folder.
• the awesome-crypto-examples repository.

If you're missing an example, you're welcome to request one. Priority will be given to github sponsors.

Usage

Create API credentials on Bybit's website:

• Livenet
• Testnet

All REST clients have can be used in a similar way. However, method names, parameters and responses may vary depending on the API category you're using!

Not sure which function to call or which parameters to use? Click the class name in the table above to look at all the function names (they are in the same order as the official API docs), and check the API docs for a list of endpoints/parameters/responses.

The following is a minimal example for using the REST clients included with this SDK. For more detailed examples, refer to the examples folder in the repository on GitHub:

1const {
2  InverseClient,
3  LinearClient,
4  InverseFuturesClient,
5  SpotClientV3,
6  UnifiedMarginClient,
7  USDCOptionClient,
8  USDCPerpetualClient,
9  AccountAssetClient,
10  CopyTradingClient,
11  RestClientV5,
12} = require('bybit-api');
13
14const restClientOptions = {
15  /** Your API key. Optional, if you plan on making private api calls */
16  key?: string;
17
18  /** Your API secret. Optional, if you plan on making private api calls */
19  secret?: string;
20
21  /** Set to `true` to connect to testnet. Uses the live environment by default. */
22  testnet?: boolean;
23
24  /** Override the max size of the request window (in ms) */
25  recv_window?: number;
26
27  /** Default: false. If true, we'll throw errors if any params are undefined */
28  strict_param_validation?: boolean;
29
30  /**
31   * Optionally override API protocol + domain
32   * e.g baseUrl: 'https://api.bytick.com'
33   **/
34  baseUrl?: string;
35
36  /** Default: true. whether to try and post-process request exceptions. */
37  parse_exceptions?: boolean;
38
39  /** Default: false. Enable to parse/include per-API/endpoint rate limits in responses. */
40  parseAPIRateLimits?: boolean;
41
42  /** Default: false. Enable to throw error if rate limit parser fails */
43  throwOnFailedRateLimitParse?: boolean;
44};
45
46const API_KEY = 'xxx';
47const API_SECRET = 'yyy';
48const useTestnet = false;
49
50const client = new RestClientV5({
51  key: API_KEY,
52  secret: API_SECRET,
53  testnet: useTestnet,
54  // Optional: enable to try parsing rate limit values from responses
55  // parseAPIRateLimits: true
56},
57  // requestLibraryOptions
58);
59
60// For public-only API calls, simply don't provide a key & secret or set them to undefined
61// const client = new RestClientV5({});
62
63client.getAccountInfo()
64  .then(result => {
65    console.log("getAccountInfo result: ", result);
66  })
67  .catch(err => {
68    console.error("getAccountInfo error: ", err);
69  });
70
71client.getOrderbook({ category: 'linear', symbol: 'BTCUSD' })
72  .then(result => {
73    console.log("getOrderBook result: ", result);
74  })
75  .catch(err => {
76    console.error("getOrderBook error: ", err);
77  });

WebSockets

All API groups can be used via a shared WebsocketClient. However, to listen to multiple API groups at once, you will need to make one WebsocketClient instance per API group.

The WebsocketClient can be configured to a specific API group using the market parameter. These are the currently available API groups:

Older Websocket APIs

The following API groups are still available in the WebsocketClient but are deprecated and may no longer work. They will be removed in the next major release:

1const { WebsocketClient } = require('bybit-api');
2
3const API_KEY = 'xxx';
4const PRIVATE_KEY = 'yyy';
5
6const wsConfig = {
7  key: API_KEY,
8  secret: PRIVATE_KEY,
9
10  /*
11    The following parameters are optional:
12  */
13
14  // Connects to livenet by default. Set testnet to true to use the testnet environment.
15  // testnet: true
16
17  // If you can, use the v5 market (the newest generation of Bybit's websockets)
18  market: 'v5',
19
20  // how long to wait (in ms) before deciding the connection should be terminated & reconnected
21  // pongTimeout: 1000,
22
23  // how often to check (in ms) that WS connection is still alive
24  // pingInterval: 10000,
25
26  // how long to wait before attempting to reconnect (in ms) after connection is closed
27  // reconnectTimeout: 500,
28
29  // recv window size for authenticated websocket requests (higher latency connections (VPN) can cause authentication to fail if the recv window is too small)
30  // recvWindow: 5000,
31
32  // config options sent to RestClient (used for time sync). See RestClient docs.
33  // restOptions: { },
34
35  // config for axios used for HTTP requests. E.g for proxy support
36  // requestOptions: { }
37
38  // override which URL to use for websocket connections
39  // wsUrl: 'wss://stream.bytick.com/realtime'
40};
41
42const ws = new WebsocketClient(wsConfig);
43
44// (before v5) subscribe to multiple topics at once
45ws.subscribe(['position', 'execution', 'trade']);
46
47// (before v5) and/or subscribe to individual topics on demand
48ws.subscribe('kline.BTCUSD.1m');
49
50// (v5) subscribe to multiple topics at once
51ws.subscribeV5(['orderbook.50.BTCUSDT', 'orderbook.50.ETHUSDT'], 'linear');
52
53// (v5) and/or subscribe to individual topics on demand
54ws.subscribeV5('position', 'linear');
55ws.subscribeV5('publicTrade.BTC', 'option');
56
57// Listen to events coming from websockets. This is the primary data source
58ws.on('update', (data) => {
59  console.log('update', data);
60});
61
62// Optional: Listen to websocket connection open event (automatic after subscribing to one or more topics)
63ws.on('open', ({ wsKey, event }) => {
64  console.log('connection open for websocket with ID: ' + wsKey);
65});
66
67// Optional: Listen to responses to websocket queries (e.g. the response after subscribing to a topic)
68ws.on('response', (response) => {
69  console.log('response', response);
70});
71
72// Optional: Listen to connection close event. Unexpected connection closes are automatically reconnected.
73ws.on('close', () => {
74  console.log('connection closed');
75});
76
77// Optional: Listen to raw error events. Recommended.
78ws.on('error', (err) => {
79  console.error('error', err);
80});

1const { WebsocketClient, DefaultLogger } = require('bybit-api');
2
3// Disable all logging on the silly level
4const customLogger = {
5  ...DefaultLogger,
6  silly: () => {},
7};
8
9const ws = new WebsocketClient({ key: 'xxx', secret: 'yyy' }, customLogger);