WebSocket Quickstart

Connect to the WhiteBIT WebSocket API for real-time streaming data. The guide targets developers building trading bots, live price feeds, or account monitoring dashboards.

Prerequisites

A terminal with a WebSocket client (Python websocket-client library, or wscat for interactive testing)
For private channels: a WhiteBIT API key with Trading permission and familiarity with Authentication
No special setup for public channels — same zero-authentication principle as the Market Data API

WhiteBIT has no public testnet or sandbox. Private channel subscriptions expose live account data. Store API credentials securely — never commit secrets to version control or expose them in shared environments. For risk-free balance-change testing, use Demo Tokens (DBTC/DUSDT) — activate from the WhiteBIT Codes page.

Connection parameters

Detail	Value
Endpoint	`wss://api.whitebit.com/ws`
Protocol	JSON-RPC 2.0 over WebSocket
Inactivity timeout	60 seconds — send `ping` every 50 seconds or less
Rate limit	200 requests per minute per connection

Connect to the WebSocket endpoint

Establish a WebSocket connection.

Python
wscat

import websocket
import json

ws = websocket.create_connection("wss://api.whitebit.com/ws")
print("Connected to WebSocket API")

wscat -c wss://api.whitebit.com/ws

A successful connection produces no immediate response. The server is ready to receive subscription messages.For Go and PHP examples, see SDKs.

Subscribe to last price updates

Subscribe to real-time price updates for BTC_USDT.

Python
wscat

# Subscribe to BTC_USDT last price
subscribe_msg = {
    "id": 1,
    "method": "lastprice_subscribe",
    "params": ["BTC_USDT"]
}
ws.send(json.dumps(subscribe_msg))

# Receive subscribe confirmation
result = json.loads(ws.recv())
print(f"Subscribe result: {result}")

# Receive price updates
update = json.loads(ws.recv())
print(f"Price update: {update}")

> {"id": 1, "method": "lastprice_subscribe", "params": ["BTC_USDT"]}

Subscribe confirmation:

{"id": 1, "result": {"status": "success"}, "error": null}

Update message:

{
  "id": null,
  "method": "lastprice_update",
  "params": ["BTC_USDT", "65432.10"]
}

The params array contains: market name (index 0) and last traded price (index 1). Updates arrive whenever a trade executes on the pair.

Subscribe to orderbook depth

Subscribe to orderbook depth updates for BTC_USDT with 5 price levels.

Python
wscat

# Subscribe to BTC_USDT depth, 5 levels, no aggregation
depth_msg = {
    "id": 2,
    "method": "depth_subscribe",
    "params": ["BTC_USDT", 5, "0", True]
}
ws.send(json.dumps(depth_msg))

# Receive subscribe confirmation
result = json.loads(ws.recv())
print(f"Depth subscribe: {result}")

# Receive depth snapshot/update
depth = json.loads(ws.recv())
print(f"Depth update: {depth}")

> {"id": 2, "method": "depth_subscribe", "params": ["BTC_USDT", 5, "0", true]}

Parameters: market name, depth limit (1/5/10/20/30/50/100), price aggregation interval ("0" = no aggregation), and multiple subscription flag. Set the flag to true to add a subscription alongside existing depth subscriptions. Setting the flag to false unsubscribes from all active depth subscriptions. Full parameter details: Depth channel.Update message:

{
  "id": null,
  "method": "depth_update",
  "params": [
    true,
    {
      "asks": [["65450.00", "0.500"], ["65460.00", "1.200"]],
      "bids": [["65430.00", "0.800"], ["65420.00", "1.500"]],
      "timestamp": 1700000000,
      "update_id": 12345
    },
    "BTC_USDT"
  ]
}

The first element in params is a boolean: true = full snapshot, false = incremental update. For local orderbook maintenance, apply incremental updates to the initial snapshot.

Authenticate for private channels

Steps 1–3 cover public channels (no authentication required). Steps 4–5 require an API key — see Authentication for key creation and HMAC-SHA512 signing details.

Private channels (balance updates, order updates) require authentication. First obtain a WebSocket token via the REST API, then send an authorize message.

Python
wscat

import base64
import hashlib
import hmac
import time
import requests

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
BASE_URL = "https://whitebit.com"

# Part A — Get WebSocket token via REST API
path = "/api/v4/profile/websocket_token"
data = {"request": path, "nonce": str(int(time.time() * 1000))}
data_json = json.dumps(data)
payload_b64 = base64.b64encode(data_json.encode()).decode()
signature = hmac.new(
    API_SECRET.encode(), payload_b64.encode(), hashlib.sha512
).hexdigest()
headers = {
    "Content-Type": "application/json",
    "X-TXC-APIKEY": API_KEY,
    "X-TXC-PAYLOAD": payload_b64,
    "X-TXC-SIGNATURE": signature,
}
token_response = requests.post(BASE_URL + path, headers=headers, data=data_json)
ws_token = token_response.json().get("websocket_token")
print(f"WebSocket token obtained")

# Part B — Send authorize message over WebSocket
auth_msg = {
    "id": 3,
    "method": "authorize",
    "params": [ws_token, "public"]
}
ws.send(json.dumps(auth_msg))
auth_result = json.loads(ws.recv())
print(f"Auth result: {auth_result}")

# First obtain a token via REST (see Python example),
# then send in wscat:
> {"id": 3, "method": "authorize", "params": ["YOUR_WS_TOKEN", "public"]}

Token endpoint: POST /api/v4/profile/websocket_token (authenticated REST call).Authorization response:

{"id": 3, "result": {"status": "success"}, "error": null}

Subscribe to spot balance updates

After authentication, subscribe to real-time spot balance changes.

Python
wscat

# Subscribe to USDT and BTC balance updates
balance_msg = {
    "id": 4,
    "method": "balanceSpot_subscribe",
    "params": ["USDT", "BTC"]
}
ws.send(json.dumps(balance_msg))

# Receive subscribe confirmation
result = json.loads(ws.recv())
print(f"Balance subscribe: {result}")

# Balance updates arrive when trades execute or transfers occur
update = json.loads(ws.recv())
print(f"Balance update: {update}")

> {"id": 4, "method": "balanceSpot_subscribe", "params": ["USDT", "BTC"]}

Update message (triggered by a trade or transfer):

{
  "id": null,
  "method": "balanceSpot_update",
  "params": [
    {
      "USDT": {
        "available": "985.50",
        "freeze": "14.50"
      }
    }
  ]
}

Key fields: available (funds ready for trading), freeze (funds locked in open orders).

Send a keepalive ping

The server closes the connection after 60 seconds of inactivity. Send a ping message to verify the connection is alive.

Python
wscat

ping_msg = {"id": 0, "method": "ping", "params": []}
ws.send(json.dumps(ping_msg))
pong = json.loads(ws.recv())
print(f"Ping result: {pong}")

> {"id": 0, "method": "ping", "params": []}

Expected response:

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

In production, send a ping every 50 seconds or less to prevent disconnection.

The six steps above cover a single connection. Production integrations need automatic reconnection and state recovery, covered next.

Reconnection and state recovery

WebSocket connections can drop due to network issues or server maintenance. Production integrations require automatic reconnection, re-authentication, and state recovery logic.

Reconnection with exponential backoff

import asyncio, json, random, time, websockets, requests, base64, hashlib, hmac

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
BASE_URL = "https://whitebit.com"

# Channels to subscribe after every (re)connect
PUBLIC_SUBS = [
    {"method": "depth_subscribe", "params": ["BTC_USDT", 20, "0", True]},
    {"method": "lastprice_subscribe", "params": ["BTC_USDT"]},
]
PRIVATE_SUBS = [
    {"method": "balanceSpot_subscribe", "params": ["USDT", "BTC"]},
    {"method": "ordersPending_subscribe", "params": ["BTC_USDT"]},
]

def get_ws_token():
    """Fetch a fresh WebSocket token via the REST API."""
    path = "/api/v4/profile/websocket_token"
    data = json.dumps({"request": path, "nonce": str(int(time.time() * 1000))})
    payload = base64.b64encode(data.encode()).decode()
    sig = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha512).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "X-TXC-APIKEY": API_KEY,
        "X-TXC-PAYLOAD": payload,
        "X-TXC-SIGNATURE": sig,
    }
    resp = requests.post(BASE_URL + path, headers=headers, data=data)
    return resp.json()["websocket_token"]

async def subscribe_all(ws):
    """Authenticate and subscribe to all channels."""
    # Authenticate for private channels
    token = get_ws_token()
    await ws.send(json.dumps({"id": 1, "method": "authorize", "params": [token, "public"]}))
    auth = json.loads(await ws.recv())
    if auth.get("error"):
        raise Exception(f"Auth failed: {auth['error']}")

    # Subscribe to all channels
    msg_id = 2
    for sub in PUBLIC_SUBS + PRIVATE_SUBS:
        await ws.send(json.dumps({"id": msg_id, **sub}))
        msg_id += 1

async def run():
    """Main loop with automatic reconnection."""
    delay = 1
    while True:
        try:
            async with websockets.connect("wss://api.whitebit.com/ws") as ws:
                delay = 1  # reset backoff on successful connection
                await subscribe_all(ws)
                while True:
                    msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=55))
                    # Process updates here
        except (asyncio.TimeoutError, websockets.exceptions.ConnectionClosed):
            jitter = random.uniform(0, delay * 0.5)
            wait = min(delay + jitter, 30)
            print(f"Disconnected — reconnecting in {wait:.1f}s")
            await asyncio.sleep(wait)
            delay = min(delay * 2, 30)  # exponential backoff, max 30s

asyncio.run(run())

Key points:

Exponential backoff — delays double on each failure (1s → 2s → 4s → … → 30s max) with random jitter to prevent thundering herd
Fresh token — obtain a new WebSocket token on every reconnect; tokens may expire during long disconnections
Full resubscription — re-subscribe to all channels after reconnecting; the server does not remember previous subscriptions

For an implementation with fill monitoring, grid strategy logic, and error recovery, see Building a Trading Bot — Auto-resubscription.

State recovery after reconnect

Different channels use different update models. The recovery strategy depends on the channel type:

Update model	Channels	Recovery strategy
Snapshot on subscribe	Depth	First message after subscribe is a full snapshot — local state auto-recovers. Apply incremental updates from subsequent messages. Detect gaps via `update_id` sequencing.
Periodic full snapshot	Positions, Borrows, Market, Market Today	Full state arrives within 1–1.5s of subscribing — no gap to fill.
Incremental delta	Balance Spot, Balance Margin	Query first, then subscribe. Send a one-time query (`balanceSpot_request` / `balanceMargin_request`) to get full state, then subscribe for incremental changes.
Event stream	Orders Pending, Orders Executed, Deals	Query first, then subscribe. Events during disconnection are lost. Use the one-time query operation or the REST equivalent to backfill, then subscribe.
Event-only (no snapshot)	Margin Positions Events, Borrows Events	Pair with the snapshot channel (Positions / Borrows) for complete state awareness.
Simple replacement	Last Price, Book Ticker, Kline	Each message replaces previous value — no gap handling needed.

For incremental-delta and event-stream channels, use a query-then-subscribe pattern:

async def recover_and_subscribe(ws):
    """Query current state, then subscribe for live updates."""
    # Step 1 — query full state
    await ws.send(json.dumps({
        "id": 10, "method": "balanceSpot_request", "params": []
    }))
    snapshot = json.loads(await ws.recv())
    # Initialize local state from snapshot["result"]

    # Step 2 — subscribe for incremental updates
    await ws.send(json.dumps({
        "id": 11, "method": "balanceSpot_subscribe", "params": ["USDT", "BTC"]
    }))

What’s next

Market Data Overview

REST API counterpart — polling-based market data for simpler integrations.

Building a Trading Bot

Combine WebSocket data with REST order placement for automated trading.

WebSocket Channels

Full channel catalog — 10 market streams and 11 account streams with schema references.

​Prerequisites

​Connection parameters

​Reconnection and state recovery

​Reconnection with exponential backoff

​State recovery after reconnect

​What’s next

Market Data Overview

Building a Trading Bot

WebSocket Channels

Prerequisites

Connection parameters

Reconnection and state recovery

Reconnection with exponential backoff

State recovery after reconnect

What’s next