> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket API

> WhiteBIT WebSocket API — connection details, quickstart examples, message format, and links to all available channels.

WebSocket URL

:

> [!WARNING]
>
> **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](#host-migration).

## Connection

WebSocket endpoint: **`wss://wss.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.

### 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](/websocket/authentication).
* Connection and request limits are unchanged — see [WebSocket Rate Limits & Error Codes](/websocket/rate-limits).

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)

> [!NOTE]
>
> 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://wss.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://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:

```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://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:**

```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://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:**

```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 |

> [!WARNING]
>
> 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

> **[Market Streams](/websocket/market-streams/overview)**
>
> Public channels for market data — kline, last price, trades, depth, book ticker, and more. See [Markets & Trading Pairs](/concepts/markets) for pair notation.

> **[Account Streams](/websocket/account-streams/overview)**
>
> Private channels for account data — balances, orders, deals, positions, and borrows. Requires authorization. See [Balances & Transfers](/concepts/balances) for account types.

> **[Order Management](/websocket/order-management/overview)**
>
> Private methods that place, modify, and cancel orders on spot, margin, and futures markets (global platform only). Requires authorization. See [Order Types](/concepts/order-types) for the available types.

## Who uses this

* **Market makers** stream the real-time order book and fills — the public [Depth](/websocket/market-streams/depth) and [Book Ticker](/websocket/market-streams/book-ticker) channels plus the private [Deals](/websocket/account-streams/deals) account stream. See [Market Maker integration](/guides/market-maker-integration).
* Any integration reading private account events (balances, orders, deals, positions) authorizes first — see [WebSocket Authentication](/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](/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

## Used in these guides

* [Partner Solutions](/guides/partner-solutions) — the partner router that maps use cases to programs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.