WebSocket Quickstart

Connect to the WhiteBIT WebSocket API — subscribe to real-time prices, orderbook updates, and private balance changes.

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. The walkthrough covers connecting to the WebSocket endpoint, subscribing to public price updates, subscribing to orderbook depth, authenticating for private channels, and receiving balance updates.

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

1. Connect to the WebSocket endpoint

   Establish a WebSocket connection.

   Python

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

   wscat

   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.

2. Subscribe to last price updates

   Subscribe to real-time price updates for BTC_USDT.

   Python

   # 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}")
   

   wscat

   > {"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.

3. Subscribe to orderbook depth

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

   Python

   # 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}")
   

   wscat

   > {"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.

4. 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

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

   wscat

   # 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}
   
5. Subscribe to spot balance updates

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

   Python

   # 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}")
   

   wscat

   > {"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).

6. 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

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

   wscat

   > {"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 walkthrough covered connecting to the WebSocket API, receiving real-time price updates and orderbook depth on public channels, authenticating for private data, and subscribing to balance updates. The WebSocket API provides the real-time data layer for trading bots, price feeds, and account monitoring.

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 a production-grade 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.