Bybit JavaScript SDK

JavaScript SDK Usage

Use framework-neutral JavaScript request and event flows across Node.js-compatible runtimes.

In JavaScript, use the package directly from readable examples. TypeScript remains useful for larger integrations, but the same client patterns work in plain JavaScript.

What This SDK Covers

• Complete Bybit REST API integrations for exchange-specific workflows.
• Robust Bybit WebSocket support for market and account stream handling.
• JavaScript-friendly usage patterns for production integration work.
• Adaptable JavaScript examples & guides under /examples for implementation reference.
• Framework-neutral JavaScript snippets that stay approachable in all JavaScript runtimes.

Install Package

npm install bybit-api
# or
pnpm install bybit-api
yarn add bybit-api

Quickstart REST API Walkthrough

Quickstart REST API Example

import { RestClientV5 } from 'bybit-api';

const key = process.env.API_KEY_COM;
const secret = process.env.API_SECRET_COM;

const client = new RestClientV5({
  key: key,
  secret: secret,
});

(async () => {
  try {
    /** Simple examples for private REST API calls with bybit's V5 REST APIs */
    const response = await client.getPositionInfo({
      category: 'linear',
      symbol: 'BTCUSDT',
    });

    console.log('response:', response);

    // Trade USDT linear perps
    const buyOrderResult = await client.submitOrder({
      category: 'linear',
      symbol: 'BTCUSDT',
      orderType: 'Market',
      qty: '1',
      side: 'Buy',
    });
    console.log('buyOrderResult:', buyOrderResult);

    const sellOrderResult = await client.submitOrder({
      category: 'linear',
      symbol: 'BTCUSDT',
      orderType: 'Market',
      qty: '1',
      side: 'Sell',
    });
    console.log('sellOrderResult:', sellOrderResult);
  } catch (e) {
    console.error('request failed: ', e);
  }
})();

Quickstart WebSocket Walkthrough

Quickstart WebSocket Example

/* eslint-disable @typescript-eslint/no-empty-function */
import { DefaultLogger, WebsocketClient, WS_KEY_MAP } from 'bybit-api';

// Create & inject a custom logger to enable the trace logging level (empty function)
const logger = {
  ...DefaultLogger,
  // trace: (...params) => console.log('trace', ...params),
};

const key = process.env.API_KEY_COM;
const secret = process.env.API_SECRET_COM;

/**
 * Prepare an instance of the WebSocket client. This client handles all aspects of connectivity for you:
 * - Connections are opened when you subscribe to topics
 * - If key & secret are provided, authentication is handled automatically
 * - If you subscribe to topics from different v5 products (e.g. spot and linear perps),
 *    subscription events are automatically routed to the different ws endpoints on bybit's side
 * - Heartbeats/ping/pong/reconnects are all handled automatically.
 *    If a connection drops, the client will clean it up, respawn a fresh connection and resubscribe for you.
 */
const wsClient = new WebsocketClient(
  {
    key: key,
    secret: secret,
    // testnet: false,
    // demoTrading: false, // set testnet to false, if you plan on using demo trading
  },
  logger,
);

wsClient.on('update', (data) => {
  console.log('raw message received ', JSON.stringify(data));
  // console.log('raw message received ', JSON.stringify(data, null, 2));
});

wsClient.on('open', (data) => {
  console.log('connection opened open:', data.wsKey);
});
wsClient.on('response', (data) => {
  console.log('log response: ', JSON.stringify(data, null, 2));
});
wsClient.on('reconnect', ({ wsKey }) => {
  console.log('ws automatically reconnecting.... ', wsKey);
});
wsClient.on('reconnected', (data) => {
  console.log('ws has reconnected ', data?.wsKey);
});
wsClient.on('exception', (data) => {
  console.error('ws exception: ', data);
});

/**
 * For private V5 topics, us the subscribeV5() method on the ws client or use the original subscribe() method.
 *
 * Note: for private endpoints the "category" field is ignored since there is only one private endpoint
 * (compared to one public one per category).
 * The "category" is only needed for public topics since bybit has one endpoint for public events per category.
 */

wsClient.subscribeV5('position', 'linear');
wsClient.subscribeV5(['order', 'wallet'], 'linear');

wsClient.subscribeV5('execution', 'linear');
// wsClient.subscribeV5('execution.fast', 'linear');
// wsClient.subscribeV5('execution.fast.linear', 'linear');

/**
 * The following has the same effect as above, since there's only one private endpoint for V5 account topics:
 */
// wsClient.subscribe('position');
// wsClient.subscribe('execution');
// wsClient.subscribe(['order', 'wallet', 'greek']);

// To unsubscribe from topics (after a 5 second delay, in this example):
// setTimeout(() => {
//   console.log('unsubscribing');
//   wsClient.unsubscribeV5('execution', 'linear');
// }, 5 * 1000);

// Topics are tracked per websocket type
// Get a list of subscribed topics (e.g. for public v3 spot topics) (after a 5 second delay)
setTimeout(() => {
  const activePrivateTopics = wsClient
    .getWsStore()
    .getTopics(WS_KEY_MAP.v5Private);
  console.log('Active private v5 topics: ', activePrivateTopics);

  const activePublicLinearTopics = wsClient
    .getWsStore()
    .getTopics(WS_KEY_MAP.v5LinearPublic);
  console.log('Active public linear v5 topics: ', activePublicLinearTopics);

  const activePublicSpotTopis = wsClient
    .getWsStore()
    .getTopics(WS_KEY_MAP.v5SpotPublic);
  console.log('Active public spot v5 topics: ', activePublicSpotTopis);

  const activePublicOptionsTopics = wsClient
    .getWsStore()
    .getTopics(WS_KEY_MAP.v5OptionPublic);
  console.log('Active public option v5 topics: ', activePublicOptionsTopics);
}, 5 * 1000);

Quickstart WebSocket API Walkthrough

Quickstart WebSocket API Example

import { DefaultLogger, WebsocketAPIClient } from 'bybit-api';

// const { DefaultLogger, WebsocketAPIClient } = require('bybit-api');

const key = process.env.API_KEY_COM;
const secret = process.env.API_SECRET_COM;

// function attachEventHandlers<TWSClient extends WebsocketClient>(
//   wsClient: TWSClient,
// ): void {
//   wsClient.on('update', (data) => {
//     console.log('raw message received ', JSON.stringify(data));
//   });
//   wsClient.on('open', (data) => {
//     console.log('ws connected', data.wsKey);
//   });
//   wsClient.on('reconnect', ({ wsKey }) => {
//     console.log('ws automatically reconnecting.... ', wsKey);
//   });
//   wsClient.on('reconnected', (data) => {
//     console.log('ws has reconnected ', data?.wsKey);
//   });
//   wsClient.on('authenticated', (data) => {
//     console.log('ws has authenticated ', data?.wsKey);
//   });
// }

async function main() {
  // Optional
  const logger = {
    ...DefaultLogger,
    // For a more detailed view of the WebsocketClient, enable the `trace` level by uncommenting the below line:
    // trace: (...params) => console.log('trace', ...params),
  };

  const wsClient = new WebsocketAPIClient(
    {
      key: key,
      secret: secret,
      // testnet: true, // Whether to use the testnet environment: https://testnet.bybit.com/app/user/api-management

      // Whether to use the livenet demo trading environment
      // Note: As of Jan 2025, demo trading only supports consuming events, it does
      // NOT support the WS API.
      // demoTrading: false,

      // If you want your own event handlers instead of the default ones with logs,
      // disable this setting and see the `attachEventHandlers` example below:
      // attachEventListeners: false
    },
    logger, // Optional: inject a custom logger
  );

  // Optional, see above "attachEventListeners". Attach basic event handlers, so nothing is left unhandled
  // attachEventHandlers(wsClient.getWSClient());

  // Optional, if you see RECV Window errors, you can use this to manage time issues.
  // ! However, make sure you sync your system clock first!
  // https://github.com/tiagosiebler/awesome-crypto-examples/wiki/Timestamp-for-this-request-is-outside-of-the-recvWindow
  // wsClient.setTimeOffsetMs(-5000);

  // Optional: prepare the WebSocket API connection in advance.
  // This happens automatically but you can do this early before making any API calls, to prevent delays from a cold start.
  // await wsClient.getWSClient().connectWSAPI();

  try {
    const response = await wsClient.submitNewOrder({
      category: 'linear',
      symbol: 'BTCUSDT',
      orderType: 'Limit',
      qty: '0.001',
      side: 'Buy',
      price: '50000',
    });
    console.log('submitNewOrder response: ', response);
  } catch (e) {
    console.log('submitNewOrder error: ', e);
  }

  try {
    const response = await wsClient.amendOrder({
      category: 'linear',
      symbol: 'BTCUSDT',
      orderId: 'b4b9e205-793c-4777-8112-0bf3c2d26b6e',
      qty: '0.001',
      price: '60000',
    });
    console.log('amendOrder response: ', response);
  } catch (e) {
    console.log('amendOrder error: ', e);
  }

  try {
    const response = await wsClient.cancelOrder({
      category: 'linear',
      symbol: 'BTCUSDT',
      orderId: 'b4b9e205-793c-4777-8112-0bf3c2d26b6e',
    });
    console.log('cancelOrder response: ', response);
  } catch (e) {
    console.log('cancelOrder error: ', e);
  }

  try {
    const response = await wsClient.batchSubmitOrders('linear', [
      {
        symbol: 'BTCUSDT',
        orderType: 'Limit',
        qty: '0.001',
        side: 'Buy',
        price: '50000',
      },
      {
        symbol: 'BTCUSDT',
        orderType: 'Limit',
        qty: '0.001',
        side: 'Buy',
        price: '60000',
      },
      {
        symbol: 'BTCUSDT',
        orderType: 'Limit',
        qty: '0.001',
        side: 'Buy',
        price: '70000',
      },
    ]);
    console.log('batchSubmitOrders response: ', response);
  } catch (e) {
    console.log('batchSubmitOrders error: ', e);
  }

  try {
    const response = await wsClient.batchAmendOrder('linear', [
      {
        symbol: 'BTCUSDT',
        orderId: '2473ee58',
        price: '80000',
      },
      {
        symbol: 'BTCUSDT',
        orderId: 'b4b9e205-793c-4777-8112-0bf3c2d26b6e',
        price: '80000',
      },
    ]);
    console.log('batchAmendOrder response: ', response);
  } catch (e) {
    console.log('batchAmendOrder error: ', e);
  }

  try {
    const response = await wsClient.batchCancelOrder('linear', [
      {
        symbol: 'BTCUSDT',
        orderId: '2473ee58',
      },
      {
        symbol: 'BTCUSDT',
        orderId: 'b4b9e205-793c-4777-8112-0bf3c2d26b6e',
      },
    ]);
    console.log('batchCancelOrder response: ', response);
  } catch (e) {
    console.log('batchCancelOrder error: ', e);
  }
}

main();

Complete Bybit API JavaScript Tutorial

Open the full Bybit API JavaScript tutorial for a practical guide to the REST API, category-based product routing, public and private WebSockets, demo trading, testnet, regional routing, WebSocket API commands, reconnect handling, and production rollout checks.

• Read the Bybit API JavaScript Tutorial
• Bybit private REST API example
• Bybit WebSocket API example

Endpoint Function Reference

Source: View endpoint map source

Bybit JavaScript FAQ

Direct Example Files

Open the example files below if you want the clearest general-purpose starting point for REST API, WebSocket, and authentication workflows in plain JavaScript.

• Bybit REST API example file (Bybit/Rest/rest-v5-private.ts)
• Bybit WebSocket example file (Bybit/Websocket/Private/ws-private-v5.ts)
• Bybit WebSocket API example file (Bybit/Websocket/WS-API/ws-api-client.ts)

Reference Links

• npm: bybit-api
• GitHub: bybit-api
• Release feed
• Support and feature requests