;
};
## Connection
WebSocket endpoint: **`wss://api.whitebit.com/ws`**
The API is based on [JSON RPC](https://www.jsonrpc.org/specification) 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.
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
};
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
setInterval(() => {
if (socket.readyState === WebSocket.OPEN) {
socket.send(JSON.stringify({
id: 0,
method: "ping",
params: [],
}));
}
}, 50000);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "id": 0, "result": "pong", "error": null }
```
### Step 3: Subscribe to last price updates
Subscribe to the [Last Price](/websocket/market-streams/lastprice) channel to receive real-time price updates for one or more markets.
Send the subscription message using the connection from Step 1:
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
socket.send(JSON.stringify({
id: 1,
method: "lastprice_subscribe",
params: ["BTC_USDT", "ETH_USDT"]
}));
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "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:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ⤴️ Request
{ "id": 0, "method": "ping", "params": [] }
// ⤵️ Response
{ "id": 0, "result": "pong", "error": null }
```
**Subscription:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ⤴️ Request
{ "id": 0, "method": "candles_subscribe", "params": [] }
// ⤵️ Response
{ "id": 0, "result": { "status": "success" }, "error": null }
```
**Update event:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "id": null, "method": "candles_update", "params": [] }
```
***
For connection limits, request limits, and error codes, see [WebSocket Rate Limits & Error Codes](/websocket/rate-limits).
Private channels require authorization. See [WebSocket Authentication](/websocket/authentication) for the full setup flow.
***
## Channels
Public channels for market data — kline, last price, trades, depth, book ticker, and more. See [Markets & Trading Pairs](/concepts/markets) for pair notation.
Private channels for account data — balances, orders, deals, positions, and borrows. Requires authorization. See [Balances & Transfers](/concepts/balances) 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](/websocket/rate-limits) for connection and request limits, timeout behavior, and reconnection guidance.
## Related resources
* [WebSocket Authentication](/websocket/authentication) — Authorization flow for private Account Stream channels
* [WebSocket Rate Limits & Error Codes](/websocket/rate-limits) — Connection limits, request limits, and error codes
* [API Reference Overview](/api-reference/overview) — Base URL, quickstart, and endpoint groups
* [Market Streams](/websocket/market-streams/overview) — All public channels (kline, trades, depth, book ticker)
* [Account Streams](/websocket/account-streams/overview) — Private channels for balances, orders, and positions