WebsocketClientV2: Bitget Classic WebSocket Streams

WebsocketClientV2 provides real-time WebSocket streams for Bitget’s classic (non-UTA) spot and futures accounts. It handles two separate connections — a public one for market data and a private one for account events — and takes care of authentication, heartbeat management, and automatic reconnection for you. If your account has not been upgraded to Unified Account mode, this is the correct client for live market data and order tracking.

If your Bitget account has been upgraded to Unified Account (UTA) mode, use WebsocketClientV3 instead, which supports the V3 topic set and account-level aggregation.

Installation

npm install bitget-api

Instantiation

Public-only client

For read-only market data topics, no credentials are required:

import { WebsocketClientV2 } from 'bitget-api';

const wsClient = new WebsocketClientV2({});

Authenticated client

Provide API credentials to access private account topics:

import { WebsocketClientV2 } from 'bitget-api';

const wsClient = new WebsocketClientV2({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  apiPass: process.env.API_PASS,
});

Demo trading client

Set demoTrading: true to route connections to Bitget’s paper-trading environment:

import { WebsocketClientV2 } from 'bitget-api';

const wsClient = new WebsocketClientV2({
  apiKey: process.env.DEMO_API_KEY,
  apiSecret: process.env.DEMO_API_SECRET,
  apiPass: process.env.DEMO_API_PASS,
  demoTrading: true,
});

Event Listeners

import { DefaultLogger, WebsocketClientV2, WS_KEY_MAP } from 'bitget-api';

const wsClient = new WebsocketClientV2(
  { apiKey: '...', apiSecret: '...', apiPass: '...' },
  DefaultLogger,
);

// Real-time data from all subscribed topics
wsClient.on('update', (data) => {
  console.log('WS raw message received:', data);
});

// A WebSocket connection was opened
wsClient.on('open', (data) => {
  console.log('WS connection opened:', data.wsKey);
});

// Server acknowledged a subscribe/unsubscribe or sent a protocol frame
wsClient.on('response', (data) => {
  console.log('WS response:', JSON.stringify(data, null, 2));
});

// Connection lost — automatic reconnect is starting
wsClient.on('reconnect', ({ wsKey }) => {
  console.log('WS automatically reconnecting...', wsKey);
});

// Connection was successfully restored
wsClient.on('reconnected', (data) => {
  console.log('WS reconnected:', data?.wsKey);
});

// The private connection completed authentication
wsClient.on('authenticated', (data) => {
  console.log('WS authenticated:', data);
});

// A server-side error or exception was received
wsClient.on('exception', (data) => {
  console.error('WS error:', data);
});

Event Reference

Event	When it fires
`update`	A subscribed topic pushed new data (ticker, candle, order book, account, etc.)
`open`	A WebSocket connection was opened or re-opened
`response`	Non-data server frame (subscription confirmation, login acknowledgement)
`reconnect`	The client detected a dropped connection and is about to reconnect
`reconnected`	The connection was successfully re-established
`authenticated`	The private connection completed the login handshake
`exception`	A server-side error event was received

`subscribeTopic()` Method

WebsocketClientV2 exposes a convenient helper that automatically routes subscriptions to the correct connection (public or private) based on the topic name:

wsClient.subscribeTopic(
  instType: BitgetInstTypeV2,  // e.g. 'SPOT', 'USDT-FUTURES'
  topic: WsTopicV2,            // e.g. 'ticker', 'orders', 'account'
  coin?: string,               // symbol or 'default' for account-level topics
): Promise<unknown>

The coin parameter is the instrument ID for market data topics (e.g. 'BTCUSDT'). For account-level topics such as account, it defaults to 'default' and can be omitted.

Public Topics (`WsPublicTopicV2`)

Public topics stream market data and require no authentication. Valid instType values are 'SPOT', 'USDT-FUTURES', 'COIN-FUTURES', 'USDC-FUTURES', 'SUSDT-FUTURES', 'SCOIN-FUTURES', and 'SUSDC-FUTURES' (the S-prefixed variants are for simulated/demo trading).

Topic	Description
`ticker`	Best bid/ask and last-trade snapshot
`trade`	Individual trade executions
`books`	Full order book depth updates
`books1`	Best bid/ask order book (level 1)
`books5`	Top 5 bids and asks
`books15`	Top 15 bids and asks
`candle1m`	1-minute OHLCV candlestick
`candle5m`	5-minute OHLCV candlestick
`candle15m`	15-minute OHLCV candlestick
`candle30m`	30-minute OHLCV candlestick
`candle1H`	1-hour OHLCV candlestick
`candle4H`	4-hour OHLCV candlestick
`candle6H`	6-hour OHLCV candlestick
`candle12H`	12-hour OHLCV candlestick
`candle1D`	1-day OHLCV candlestick
`candle3D`	3-day OHLCV candlestick
`candle1W`	1-week OHLCV candlestick
`candle1M`	1-month OHLCV candlestick
`candle6Hutc`	6-hour OHLCV candlestick (UTC aligned)
`candle12Hutc`	12-hour OHLCV candlestick (UTC aligned)
`candle1Dutc`	1-day OHLCV candlestick (UTC aligned)
`candle3Dutc`	3-day OHLCV candlestick (UTC aligned)
`candle1Wutc`	1-week OHLCV candlestick (UTC aligned)
`candle1Mutc`	1-month OHLCV candlestick (UTC aligned)
`index-price`	Index price (margin trading only)

import { WebsocketClientV2 } from 'bitget-api';

const wsClient = new WebsocketClientV2({});

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

const symbol = 'BTCUSDT';

// Spot ticker
wsClient.subscribeTopic('SPOT', 'ticker', symbol);

// Spot 1-minute candles
wsClient.subscribeTopic('SPOT', 'candle1m', symbol);

// Spot order book
wsClient.subscribeTopic('SPOT', 'books', symbol);

// USDT-Futures ticker
wsClient.subscribeTopic('USDT-FUTURES', 'ticker', symbol);

// USDT-Futures 1-hour candles
wsClient.subscribeTopic('USDT-FUTURES', 'candle1H', symbol);

Private Topics (`WsPrivateTopicV2`)

Private topics stream account-level events and require API credentials. The client will authenticate the private connection automatically on the first private-topic subscription.

Topic	Description
`account`	Spot/futures balance and asset changes
`orders`	Spot/futures order state changes
`positions`	Futures position updates
`orders-algo`	Algo/plan order lifecycle events
`positions-history`	Historical position close records
`orders-crossed`	Margin crossed-mode order updates
`orders-isolated`	Margin isolated-mode order updates
`account-crossed`	Margin crossed-mode account balance updates
`account-isolated`	Margin isolated-mode account balance updates

import { WebsocketClientV2 } from 'bitget-api';

const wsClient = new WebsocketClientV2({
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  apiPass: process.env.API_PASS,
});

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

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

// Spot account balance updates
wsClient.subscribeTopic('SPOT', 'account');

// USDT-Futures account balance updates
wsClient.subscribeTopic('USDT-FUTURES', 'account');

// USDC-Futures account balance updates
wsClient.subscribeTopic('USDC-FUTURES', 'account');

// USDT-Futures position updates
wsClient.subscribeTopic('USDT-FUTURES', 'positions');

// USDT-Futures order updates for a specific symbol
wsClient.subscribeTopic('USDT-FUTURES', 'orders', 'BTCUSDT');

// USDT-Futures algo/plan order updates
wsClient.subscribeTopic('USDT-FUTURES', 'orders-algo');

`connectAll()` Method

Eagerly open both the public and private connections before the first subscription:

const connections = wsClient.connectAll();
await Promise.all(connections);
console.log('Both V2 connections are ready');

`unsubscribeTopic()` Method

Remove an active subscription from the connection and the internal store:

// Remove a specific futures position subscription
wsClient.unsubscribeTopic('USDT-FUTURES', 'account');

// Remove a symbol-level order subscription
wsClient.unsubscribeTopic('USDT-FUTURES', 'orders', 'BTCUSDT');

For advanced use cases you can bypass subscribeTopic() and call the lower-level methods directly, providing the WsKey explicitly:

import { WebsocketClientV2, WS_KEY_MAP } from 'bitget-api';

wsClient.subscribe(
  {
    topic: 'ticker',
    payload: { instType: 'SPOT', instId: 'ETHUSDT' },
  },
  WS_KEY_MAP.v2Public,
);

Auto-Reconnect Behaviour

The client sends periodic ping frames and expects pong responses within pongTimeout milliseconds. If the pong does not arrive the connection is torn down and a fresh one is opened after reconnectTimeout milliseconds. All subscriptions in the internal store are automatically replayed on reconnect — no manual intervention is needed. Listen to the reconnect and reconnected events to log or react to these lifecycle changes.

Get Started

REST Clients

WebSockets

Guides

WebsocketClientV2: Bitget Classic WebSocket Streams

Installation

Instantiation

Event Listeners

Event Reference

`subscribeTopic()` Method

Public Topics (`WsPublicTopicV2`)

Private Topics (`WsPrivateTopicV2`)

`connectAll()` Method

`unsubscribeTopic()` Method

Auto-Reconnect Behaviour

Build docs developers (and LLMs) love

Get Started

REST Clients

WebSockets

Guides

Documentation Index

​Installation

​Instantiation

​Event Listeners

​Event Reference

​subscribeTopic() Method

​Public Topics (WsPublicTopicV2)

​Public Subscribe Example

​Private Topics (WsPrivateTopicV2)

​Private Subscribe Example

​connectAll() Method

​unsubscribeTopic() Method

​Low-Level subscribe() / unsubscribe()

​Auto-Reconnect Behaviour

Build docs developers (and LLMs) love

Installation

Instantiation

Event Listeners

Event Reference

`subscribeTopic()` Method

Public Topics (`WsPublicTopicV2`)

Public Subscribe Example

Private Topics (`WsPrivateTopicV2`)

Private Subscribe Example

`connectAll()` Method

`unsubscribeTopic()` Method

Low-Level `subscribe()` / `unsubscribe()`

Auto-Reconnect Behaviour