Private WebSocket API

WebSocket Token

Authorize

Balance Spot

Balance Margin

Orders Pending

Orders Executed

Deals

Positions

Margin Positions Events

Borrows

Borrows Events

WebSocket Connection Management

WebSocket endpoint is wss://api.whitebit.com/ws

The API is based on JSON RPC of WebSocket protocol.

⚠️️ Connection Timeout ⚠️️

• Server closes websocket connection after 60 seconds of inactivity
• Inactivity is defined as no messages sent by the client

Maintaining Connection

To keep the websocket connection active:

• Send periodic ping messages every 50 seconds
• Handle potential connection closures gracefully in your application logic

Example Implementation

// Establish websocket connection
const socket = new WebSocket("wss://api.whitebit.com/ws");

// Set up periodic ping
setInterval(() => {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify({
            id: 0,
            method: "ping",
            params: [],
        }));
  }
}, 50000); // Every 50 seconds

Rate limit 1000 ws connections per minute and 200 requests per minute in one connection.

All endpoints return time in Unix-time format.

Order types

Order type ID	Description
1	Limit
2	Market
202	Market stock
3	Stop limit
4	Stop market
7	Margin limit
8	Margin market
9	Margin stop limit
10	Margin trigger-stop market
14	Margin normalization

⤴️ Request message

JSON Structure of request message:

• id - Integer. Should be unique to handle response for your request.
• method - String. Name of request.
• params - Array. Here you pass params for method.

🚫 WebSocket connection will be closed if invalid JSON was sent.

Types of request messages

• Query (balanceSpot_request, ordersPending_request, etc)
• Subscription (balanceSpot_subscribe, ordersPending_subscribe, etc). Repeated subscription will be cancelled for the same data type.

⤵️ Response message

JSON Structure of response message:

• id - Integer. Request ID.
• result - Null for failure, for success - look for responses below
• error - Null for success, JSON Object for failure:
  • message - Detailed text
  • code - Error code

Code	Message
1	invalid argument
2	internal error
3	service unavailable
4	method not found
5	service timeout

Types of response messages

• Query result
• Subscription status (success/failed)
• Update events

---

Examples

Example messages for request with response:

⤴️ Request:

{
  "id": 0,
  "method": "authorize",
  "params": ["<get_your_token_via_api>", ""]
}

⤵️ Response:

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

Example subscription:

⤴️ Request:

{
  "id": 0,
  "method": "balanceSpot_subscribe",
  "params": []
}

⤵️ Response:

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

🔄 Update events:

{
  "id": null,
  "method": "balanceSpot_update",
  "params": [] // look below for params
}