Bybit TypeScript SDK

TypeScript SDK Usage

Use typed requests, responses, and event flows in stricter TypeScript services and shared libraries.

In TypeScript, use the package types to check request shapes, response fields, WebSocket payloads, and refactors around exchange-specific code.

What This SDK Covers

• Complete Bybit REST API integrations for exchange-specific workflows.
• Robust Bybit WebSocket support for market and account stream handling.
• TypeScript-friendly usage patterns for production integration work.
• Adaptable TypeScript examples & guides under /examples for implementation reference.
• Type-rich examples that emphasize request and response shapes, editor hints, and safer refactors.
• Implementation patterns for larger TypeScript services, shared libraries, and stricter TypeScript application code.

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();

Endpoint Function Reference

Source: View endpoint map source

Bybit TypeScript FAQ

Direct Example Files

Open the example files for typed patterns that translate well into shared interfaces, services, and stricter application code.

• 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