Skip to main content

​
Connection

WebSocket endpoint: wss://api.whitebit.com/ws The API is based on JSON RPC over the WebSocket protocol. The API returns time in Unix-time format.

​
Quickstart

​
Prerequisites

  • A WebSocket client (browser, Node.js, Python, or similar)
No API key is required for public channels.

​
Step 1: Establish a connection

Open a WebSocket connection to the endpoint. 
const socket = new WebSocket("wss://api.whitebit.com/ws");

socket.onopen = () => {
  console.log("Connected");
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};
The connection opens when the WebSocket handshake completes.

​
Step 2: Keep the connection alive

The server closes the connection after 60 seconds of inactivity. Send a ping message every 50 seconds to keep the connection alive. Add the following to the connection established in Step 1: 
setInterval(() => {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify({
      id: 0,
      method: "ping",
      params: [],
    }));
  }
}, 50000);
Expected response: 
{ "id": 0, "result": "pong", "error": null }

​
Step 3: Subscribe to last price updates

Subscribe to the Last Price channel to receive real-time price updates for one or more markets. Send the subscription message using the connection from Step 1: 
socket.send(JSON.stringify({
  id: 1,
  method: "lastprice_subscribe",
  params: ["BTC_USDT", "ETH_USDT"]
}));
Expected subscription response: 
{ "id": 1, "result": { "status": "success" }, "error": null }

​
Step 4: Receive update events

After a successful subscription, the server sends update events every second. Each event contains the market name and the latest price. Example update event: 
{
  "id": null,
  "method": "lastprice_update",
  "params": ["BTC_USDT", "67500.50"]
}
The params array contains [market_name, last_price]. Parse each lastprice_update event to display real-time prices.

​
Message Format

​
Request message

FieldTypeDescription
idIntegerUnique identifier to match the response to the request
methodStringName of the method to call
paramsArrayParameters for the method
The connection will be closed if invalid JSON is sent.
Types of request messages:
  • Query — one-time requests (ping, candles_request, balanceSpot_request, etc.)
  • Subscription — streaming updates (candles_subscribe, lastprice_subscribe, balanceSpot_subscribe, etc.). Repeating a subscription cancels the previous one for the same data type.

​
Response message

FieldTypeDescription
idIntegerID of the original request
resultObject / nullnull on failure; see channel docs for success payloads
errorObject / nullnull on success; error object on failure
Types of response messages:
  • Query result — direct response to a query request
  • Subscription status — success or failure of a subscription request
  • Update events — pushed by the server when subscribed data changes

​
Examples

Query — ping/pong: 
// ⤴️ Request
{ "id": 0, "method": "ping", "params": [] }

// ⤵️ Response
{ "id": 0, "result": "pong", "error": null }
Subscription: 
// ⤴️ Request
{ "id": 0, "method": "candles_subscribe", "params": [] }

// ⤵️ Response
{ "id": 0, "result": { "status": "success" }, "error": null }
Update event: 
{ "id": null, "method": "candles_update", "params": [] }
For connection limits, request limits, and error codes, see WebSocket Rate Limits & Error Codes. Private channels require authorization. See WebSocket Authentication for the full setup flow.

​
Channels

Market Streams

Public channels for market data — kline, last price, trades, depth, book ticker, and more.

Account Streams

Private channels for account data — balances, orders, deals, positions, and borrows. Requires authorization.

​
Connection best practices

Reuse a single WebSocket connection for multiple subscriptions instead of opening a new connection per channel. See WebSocket Rate Limits & Error Codes for connection and request limits, timeout behavior, and reconnection guidance.