WebSocket API - WhiteBIT

Deprecated. wss://api.whitebit.com/ws is deprecated as of September 1, 2026 and stops accepting connections on March 1, 2027. Connect to wss://wss.whitebit.com/ws instead. Only the host changes — see Host migration.

Connection

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

Host migration

The Global WebSocket host moved from api.whitebit.com to wss.whitebit.com on September 1, 2026. Both hosts serve the same channels over the same /ws path during a 6-month transition window.

Host	Status
`wss://wss.whitebit.com/ws`	Current. Use for all connections.
`wss://api.whitebit.com/ws`	Deprecated September 1, 2026. Rejects connections from March 1, 2027.

Replace the host string in the WebSocket client and redeploy. Nothing in the application protocol changes:

The /ws path is unchanged.
The JSON-RPC request and response format is unchanged.
Every subscription, query, and order-management method name is unchanged.
The authorize flow and the token format are unchanged — see WebSocket Authentication.
Connection and request limits are unchanged — see WebSocket Rate Limits & Error Codes.

One item sits outside the application protocol: a network that allowlists destination hosts must permit wss.whitebit.com before the switch. The legacy host stays fully functional until March 1, 2027, so the switch does not need a coordinated cutover. An integration that resolves the host from configuration needs a configuration change only. An integration that hardcodes the host in more than one place — a reconnect helper, a failover list, a client default — must update every occurrence, because a missed entry keeps working until March 1, 2027 and fails then rather than at deploy time.

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://wss.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://wss.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://wss.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://wss.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.

Order Management

Private methods that place, modify, and cancel orders on spot, margin, and futures markets, from September 2, 2026 (global platform only). Requires authorization. See Order Types for the available types.

Who uses this

Market makers stream the real-time order book and fills — the public Depth and Book Ticker channels plus the private Deals account stream. See Market Maker integration.
Any integration reading private account events (balances, orders, deals, positions) authorizes first — see WebSocket Authentication.

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

Used in these guides

Partner Solutions — the partner router that maps use cases to programs.

​Connection

​Host migration

​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

Order Management

​Who uses this

​Connection best practices

​Related resources

​Used in these guides

Connection

Host migration

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

Who uses this

Connection best practices

Related resources

Used in these guides