Skip to main content

Documentation Index

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

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

The WebsocketClient is the single entry point for all real-time data on BitMart. It manages six persistent WebSocket connections — covering spot and futures markets, public and private channels, across both API v1 and v2 — and handles connection lifecycle, heartbeats, authentication, and topic resubscription transparently so your application code only needs to react to events.

​
WebSocket Connections

BitMart exposes distinct WebSocket endpoints for each combination of market (spot / futures), channel visibility (public / private), and API generation (v1 / v2). The WebsocketClient maps these to six internal connection keys defined in WS_KEY_MAP.
WsKeyURLNotes
spotPublicV1wss://ws-manager-compress.bitmart.com/api?protocol=1.1Spot public channels
spotPrivateV1wss://ws-manager-compress.bitmart.com/user?protocol=1.1Spot private channels
futuresPublicV1wss://openapi-ws.bitmart.com/api?protocol=1.1Futures public (legacy v1)
futuresPrivateV1wss://openapi-ws.bitmart.com/user?protocol=1.1Futures private (legacy v1)
futuresPublicV2wss://openapi-ws-v2.bitmart.com/api?protocol=1.1Futures public v2 (recommended)
futuresPrivateV2wss://openapi-ws-v2.bitmart.com/user?protocol=1.1Futures private v2 (recommended)
New integrations should use the v2 futures endpoints (futuresPublicV2 / futuresPrivateV2). The v1 futures endpoints are maintained for backwards compatibility. Demo trading is only available on the v2 futures connections.
The library automatically routes every subscription to the correct connection based on the topic string prefix (spot/ or futures/) and whether the topic is private.

​
Events

The WebsocketClient extends Node.js EventEmitter. Bind handlers with .on(event, handler) before subscribing to any topics. 
import { WebsocketClient } from 'bitmart-api';

const client = new WebsocketClient();

// Connection opened (fires once per WS connection, identified by wsKey)
client.on('open', (data) => {
  console.log('Connection opened:', data?.wsKey);
});

// Market data or account update received
client.on('update', (data) => {
  console.log('Data received:', JSON.stringify(data));
});

// Library is attempting to reconnect after a disconnect
client.on('reconnect', (data) => {
  console.log('Reconnecting:', data);
});

// Reconnect completed — topics have been resubscribed automatically
client.on('reconnected', (data) => {
  console.log('Reconnected:', data);
});

// Server confirmed successful WebSocket authentication
client.on('authenticated', (data) => {
  console.log('Authenticated:', data);
});

// Server replied to a subscribe / unsubscribe request
client.on('response', (data) => {
  console.log('Server response:', data);
});

// An error occurred (parse failure, auth error, server rejection, etc.)
client.on('exception', (data) => {
  console.error('Exception:', data);
});

// Connection closed (precedes reconnect if unexpected)
client.on('close', (data) => {
  console.error('Connection closed:', data);
});
EventWhen it fires
openA WebSocket connection is established
updateA market data or account data message is received
reconnectThe library detected a dropped connection and is retrying
reconnectedA dropped connection has been restored
authenticatedThe server accepted the login / access request on a private channel
responseThe server replied to a subscribe or unsubscribe request
exceptionAn error occurred (auth failure, bad message, etc.)
closeA connection closed (may precede a reconnect cycle)

​
Core Methods

​
subscribe(topics, market)

The primary subscription method. Accepts a single topic string or an array of topic strings, plus the market name ('spot' or 'futures'). Automatically routes each topic to the correct underlying WebSocket connection and handles authentication when needed. 
// Single topic
client.subscribe('spot/ticker:BTC_USDT', 'spot');

// Multiple topics at once
client.subscribe(
  ['spot/ticker:BTC_USDT', 'spot/ticker:ETH_USDT'],
  'spot',
);

​
unsubscribe(topics, market)

Removes topics from the active subscription list and sends an unsubscribe request to the server. Topics removed this way will not be resubscribed after a reconnect. 
client.unsubscribe('spot/ticker:BTC_USDT', 'spot');

​
subscribeTopics(topics)

Lower-level method that accepts an array of topic strings and automatically determines the correct connection and market from the topic name prefix. Useful when managing mixed spot + futures topics in one call. 
client.subscribeTopics([
  'spot/ticker:BTC_USDT',
  'futures/ticker',
]);

​
unsubscribeTopics(topics)

Lower-level counterpart to subscribeTopics. Sends unsubscribe requests and removes topics from the reconnect cache. 
client.unsubscribeTopics(['spot/ticker:BTC_USDT']);

​
connectAll()

Pre-establishes all four primary connections (spot public, spot private, futures public v2, futures private v2) immediately, rather than waiting for the first subscription to trigger lazy connection. Returns an array of promises that resolve when each connection is ready. 
await Promise.all(client.connectAll());
console.log('All connections ready');
Calling connectAll() is optional. If you omit it, connections are created automatically on the first subscribe() call for each market/visibility combination.

​
Topic Format

BitMart WebSocket topics follow the pattern {market}/{channel}:{symbol} for symbol-specific channels, or {market}/{channel} for market-wide channels. 
spot/ticker:BTC_USDT        ← spot ticker for BTC_USDT
spot/depth20:ETH_USDT       ← spot 20-level order book for ETH_USDT
spot/kline1m:BTC_USDT       ← spot 1-minute kline for BTC_USDT
futures/ticker              ← all futures tickers (no symbol suffix)
futures/depth20:BTCUSDT     ← futures 20-level order book for BTCUSDT
futures/klineBin1m:BTCUSDT  ← futures 1-minute kline for BTCUSDT
spot/user/order:BTC_USDT    ← private: spot order updates for BTC_USDT
futures/asset:USDT          ← private: futures asset (balance) for USDT
futures/position            ← private: all futures positions
Spot symbols use underscores (BTC_USDT). Futures symbols omit the underscore (BTCUSDT). Use the correct format for each market to avoid subscription errors.
The library inspects the topic prefix to determine the market (spot vs futures) and inspects sub-components like user, asset, order, and position to determine whether the topic is private. You never need to manually specify isPrivate unless you are using a custom or undocumented topic string.

​
Connection Lifecycle

Connections are created lazily — no network activity occurs until the first subscribe() call for a given market/visibility combination. Once a connection is open, the library sends a periodic ping (raw string 'ping' for spot; {"action":"ping"} for futures) and monitors the pong response to detect dead connections. When a disconnect is detected, the library emits reconnect, re-establishes the connection, re-authenticates if needed, and resubscribes every topic that was previously active — then emits reconnected. Your event handlers continue to work without any manual intervention. 
First subscribe()
       │
       ▼
  Open WS connection
       │
       ▼
  (private?) ──yes──► Send login/access request ──► emit 'authenticated'
       │
       ▼
  Send subscribe request ──► emit 'response'
       │
       ▼
  Receive updates ──────────────────────────────────► emit 'update'
       │
  (disconnected?)
       │
       ▼
  emit 'reconnect' ──► Re-open connection ──► Re-auth ──► Resubscribe ──► emit 'reconnected'

Public Streams

Subscribe to market data — tickers, order books, trades, and klines — for spot and futures markets without credentials.

Private Streams

Subscribe to account-level streams — orders, positions, and balances — using your API key, secret, and memo.

Build docs developers (and LLMs) love

Get started for freeTalk to us