WebSocket API - WhiteBIT

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

import asyncio
import websockets
import json

async def connect():
    async with websockets.connect("wss://api.whitebit.com/ws") as ws:
        print("Connected")
        async for message in ws:
            data = json.loads(message)
            print("Received:", data)

asyncio.run(connect())

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

import asyncio
import websockets
import json

async def connect():
    async with websockets.connect("wss://api.whitebit.com/ws") as ws:
        async def keepalive():
            while True:
                await asyncio.sleep(50)
                await ws.send(json.dumps({"id": 0, "method": "ping", "params": []}))

        asyncio.create_task(keepalive())
        async for message in ws:
            data = json.loads(message)
            print("Received:", data)

asyncio.run(connect())

Expected response:

{ "id": 0, "result": "pong", "error": null }

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"]
}));

import asyncio
import websockets
import json

async def connect():
    async with websockets.connect("wss://api.whitebit.com/ws") as ws:
        async def keepalive():
            while True:
                await asyncio.sleep(50)
                await ws.send(json.dumps({"id": 0, "method": "ping", "params": []}))

        asyncio.create_task(keepalive())

        await ws.send(json.dumps({
            "id": 1,
            "method": "lastprice_subscribe",
            "params": ["BTC_USDT", "ETH_USDT"]
        }))

        async for message in ws:
            data = json.loads(message)
            print("Received:", data)

asyncio.run(connect())

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

Field	Type	Description
`id`	Integer	Unique identifier to match the response to the request
`method`	String	Name of the method to call
`params`	Array	Parameters 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

Field	Type	Description
`id`	Integer	ID of the original request
`result`	Object / null	`null` on failure; see channel docs for success payloads
`error`	Object / null	`null` 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. See Markets & Trading Pairs for pair notation.

Account Streams

Private channels for account data — balances, orders, deals, positions, and borrows. Requires authorization. See Balances & Transfers for account types.

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.

WebSocket Authentication — Authorization flow for private Account Stream channels
WebSocket Rate Limits & Error Codes — Connection limits, request limits, and error codes
API Reference Overview — Base URL, quickstart, and endpoint groups
Market Streams — All public channels (kline, trades, depth, book ticker)
Account Streams — Private channels for balances, orders, and positions

​Connection

​Quickstart

​Prerequisites

​Step 1: Establish a connection

​Step 2: Keep the connection alive

​Step 3: Subscribe to last price updates

​Step 4: Receive update events

​Message Format

​Request message

​Response message

​Examples

​Channels

Market Streams

Account Streams

​Connection best practices

​Related resources

Connection

Quickstart

Prerequisites

Step 1: Establish a connection

Step 2: Keep the connection alive

Step 3: Subscribe to last price updates

Step 4: Receive update events

Message Format

Request message

Response message

Examples

Channels

Connection best practices

Related resources