Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/bybit-api/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you from a blank project to a working Bybit integration. You will install the SDK, create API credentials, load them safely via environment variables, fetch public market data, authenticate a private REST call, and subscribe to a live WebSocket stream.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Node.js 16 or later — check with node --version
  • npm, yarn, or pnpm — any one of them works
1
Install bybit-api
2
Add the SDK to your project using your preferred package manager:
3
npm
npm install bybit-api
yarn
yarn add bybit-api
pnpm
pnpm add bybit-api
4
Create API keys on Bybit
5
Public market data calls do not require API keys. For any private endpoint — account info, order placement, position reads — you will need credentials.
6
Create API keys from the relevant Bybit dashboard:
7
  • Live environment: bybit.com — API Management
  • Testnet environment: testnet.bybit.com — API Management
    • 8
    Use testnet keys while developing. Testnet is a safe sandbox where you can verify endpoint connectivity and permissions without any risk to real funds. When you are ready to go live, swap in your live credentials.
    9
    Always grant the minimum permissions your integration actually needs. A market-data monitor does not need trading permissions. A trading bot does not need withdrawal permissions. Use IP whitelisting whenever your deployment environment allows it.
    10
    Set environment variables
    11
    Never hardcode API credentials in source files. Store them in environment variables instead:
    12
    export BYBIT_API_KEY="your-api-key-here"
export BYBIT_API_SECRET="your-api-secret-here"
    13
    For local development you can use a .env file and a package like dotenv:
    14
    # .env
BYBIT_API_KEY=your-api-key-here
BYBIT_API_SECRET=your-api-secret-here
    15
    import 'dotenv/config';
import { RestClientV5 } from 'bybit-api';
    16
    Make your first public REST call
    17
    Public market data endpoints do not require API credentials. Instantiate RestClientV5 with no arguments to make public calls:
    18
    import { RestClientV5 } from 'bybit-api';

// No credentials needed for public market data
const client = new RestClientV5();

async function main() {
  // Fetch the current BTCUSDT order book (linear perpetual)
  const orderBook = await client.getOrderbook({
    category: 'linear',
    symbol: 'BTCUSDT',
    limit: 50,
  });
  console.log('Order book:', orderBook.result);

  // Fetch the latest ticker for BTCUSDT
  const ticker = await client.getTickers({
    category: 'linear',
    symbol: 'BTCUSDT',
  });
  console.log('Ticker:', ticker.result.list[0]);

  // Fetch recent 5-minute candles
  const candles = await client.getKline({
    category: 'linear',
    symbol: 'BTCUSDT',
    interval: '5',
    limit: 5,
  });
  console.log('Candles:', candles.result.list);
}

main().catch(console.error);
    19
    Run it:
    20
    npx ts-node main.ts
# or, for plain JavaScript:
node main.js
    21
    Make your first authenticated REST call
    22
    Provide your API key and secret in the constructor. The SDK automatically attaches timestamps and HMAC signatures to every private request — you never need to sign requests manually.
    23
    import { RestClientV5 } from 'bybit-api';

const client = new RestClientV5({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
  // Uncomment to use the testnet environment:
  // testnet: true,
});

async function main() {
  // Fetch account information (private endpoint — requires credentials)
  const accountInfo = await client.getAccountInfo();
  console.log('Account info:', accountInfo.result);

  // Fetch UNIFIED wallet balance
  const wallet = await client.getWalletBalance({
    accountType: 'UNIFIED',
  });
  console.log('Wallet balance:', wallet.result.list[0]);

  // Fetch open positions for BTCUSDT linear perpetual
  const positions = await client.getPositionInfo({
    category: 'linear',
    symbol: 'BTCUSDT',
  });
  console.log('Positions:', positions.result.list);
}

main().catch(console.error);
    24
    Subscribe to a WebSocket stream
    25
    The WebsocketClient manages all WebSocket connections for you — it handles connecting, authenticating, heartbeats, reconnections, and resubscriptions automatically. Attach event listeners, then call subscribeV5 with the topics you want.
    26
    import { WebsocketClient } from 'bybit-api';

// Public WebSocket — no credentials required for public topics
const ws = new WebsocketClient();

// Listen for streaming data
ws.on('update', (data) => {
  console.log('Stream update:', JSON.stringify(data, null, 2));
});

// Optional: connection lifecycle events
ws.on('open', ({ wsKey }) => {
  console.log('Connection opened:', wsKey);
});

ws.on('response', (response) => {
  console.log('Subscribe response:', response);
});

ws.on('reconnect', ({ wsKey }) => {
  console.log('Reconnecting:', wsKey);
});

ws.on('reconnected', ({ wsKey }) => {
  console.log('Reconnected:', wsKey);
});

// Log errors
ws.on('exception', (err) => {
  console.error('WebSocket error:', err);
});

// Subscribe to public topics on the linear (USDT perpetual) market
ws.subscribeV5(
  ['orderbook.50.BTCUSDT', 'publicTrade.BTCUSDT', 'tickers.BTCUSDT'],
  'linear',
);
    27
    For private account streams, add your credentials and subscribe to private topics:
    28
    import { WebsocketClient } from 'bybit-api';

const ws = new WebsocketClient({
  key: process.env.BYBIT_API_KEY,
  secret: process.env.BYBIT_API_SECRET,
});

ws.on('authenticated', ({ wsKey }) => {
  console.log('Authenticated:', wsKey);
});

ws.on('update', (data) => {
  console.log('Account event:', JSON.stringify(data, null, 2));
});

ws.on('exception', console.error);

// Subscribe to private account topics
ws.subscribeV5(['order', 'execution', 'position', 'wallet'], 'linear');

    ​
    Next steps

    Authentication

    Learn how HMAC and RSA key types work, configure recvWindow, and set up environment variables securely.

    REST API

    Browse all RestClientV5 methods — market data, order management, positions, wallet, and more.

    WebSockets

    Explore all public and private stream topics and learn how to use the WebSocket API for order commands.

    Configuration

    Tune recv_window, enable rate-limit parsing, configure regional domains, and set up keep-alive connections.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us