Skip to main content

Private WebSocket API

Methods

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

The API is based on JSON RPC of WebSocket protocol.

⚠️ Connection will be closed by server in cause of inactivity after 60s.

❗ Rate limit 100 ws connections per minute.

All endpoints return time in Unix-time format.

Order types

Order type IDDescription
1Limit
2Market
3Stop limit
4Stop market
5Conditional limit
6Conditional market
8Margin market
10Margin trigger-stop market

⤴️ 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
CodeMessage
1invalid argument
2internal error
3service unavailable
4method not found
5service 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
}

API

Websocket token

[POST] /api/v4/profile/websocket_token

This V4 endpoint can be used to retrieve the websocket token for user.

Request BODY raw:

{
"request": "{{request}}",
"nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
{
"websocket_token": "your_current_token"
}

Authorize

When you establish WS connection, you should authorize this ws connection via authorize method. After successful authorization you will be able to send requests for balances, orders etc.

It only needs to be done successfully once.

⤴️ Request:
{
"id": 0,
"method": "authorize",
"params": [
"<get_your_token_via_api>", // WebSocket Token,
"public" // constant string, always should be "public"
]
}
⤵️ Response:
{
"id": 0,
"result": {
"status": "success"
},
"error": null
}

Balance Spot

Query

⤴️ Request:
{
"id": 2,
"method": "balanceSpot_request",
"params": [
"ETH", // asset
"BTC", // asset
...
]
}
⤵️ Response:
{
"id": 2,
"result": {
"ETH": {
"available": "0", // Amount available for trade
"freeze": "0" // Amount in active orders
},
"BTC": {
"available": "0", // Amount available for trade
"freeze": "0" // Amount in active orders
}
},
"error": null
}

Subscribe

Subscribe to receive updates in spot balances.

⤴️ Request:
{
"id": 3,
"method": "balanceSpot_subscribe",
"params": [
"USDT", // asset
"ETH", // asset
...
]
}
⤵️ Response:
{
"id": 3,
"result": {
"status": "success"
},
"error": null
}
🔄 Update events:
{
"id": null,
"method": "balanceSpot_update",
"params": [
{
"USDT": {
"available": "100.1885", // Amount available for trade
"freeze": "0" // Amount in active orders
}
},
...
]
}

Unsubscribe

⤴️ Request:
{
"id": 4,
"method": "balanceSpot_unsubscribe",
"params": []
}
⤵️ Response:
{
"id": 4,
"result": {
"status": "success"
},
"error": null
}

Balance Margin

Query

Request for amount on margin balance. Balance available for margin trade is equal to balance * leverage and it depends on liquidity in orderbook and your open positions. When you open position, your balance will not change, but amount available for trade will decrease

⤴️ Request:
{
"id": 2,
"method": "balanceMargin_request",
"params": [
"BTC", // asset
"USDT" // asset
]
}
⤵️ Response:
{
"id": 2,
"result": {
"BTC": "0", // Amount on margin balance
"USDT": "0" // Amount on margin balance
},
"error": null
}

Subscribe

Subscribe to receive updates in spot balances.

⤴️ Request:
{
"id": 3,
"method": "balanceMargin_subscribe",
"params": [
"BTC", // asset
"USDT" // asset
]
}
⤵️ Response:
{
"id": 3,
"result": {
"status": "success"
},
"error": null
}
🔄 Update events:
{
"id": null,
"method": "balanceMargin_update",
"params": [
{
"USDT": "100.1885" // Amount on margin balance
}
]
}

Unsubscribe

⤴️ Request:
{
"id": 4,
"method": "balanceMargin_unsubscribe",
"params": []
}
⤵️ Response:
{
"id": 4,
"result": {
"status": "success"
},
"error": null
}

Orders Pending

Query

⤴️ Request:

Market should exist. The maximum limit is 100.

{
"id": 8,
"method": "ordersPending_request",
"params": [
"BTC_USDT", // market
0, // offset
30 // limit
],
}
⤵️ Response:

All possible order types

{
"id": 8,
"result": {
"limit": 100, // Limit from request
"offset": 0, // Offset from request
"total": 124, // Total count of records
"records": [
{
"id": 6880290, // Order ID
"market": "BTC_USDT", // Market
"type": 1, // Order type. All types in table above
"side": 1, // Side 1 - sell, 2 - bid
"ctime": 1601464682.998461, // Created at in Unix time
"mtime": 1601464682.998461, // Modified at in Unix time
"price": "10900", // Order price
"amount": "0.773232", // Stock amount
"left": "0.773232", // Stock amount that left to be executed
"deal_stock": "0", // Stock amount that executed
"deal_money": "0", // Money amount that executed
"deal_fee": "0", // Charged fee amount in money,
"client_order_id": "22" // Custom client order id
},
...
]
},
"error": null
}

Subscribe

⤴️ Request:
{
"id": 9,
"method": "ordersPending_subscribe",
"params": [
"BTC_USDT", // market
"ETH_BTC" // market
]
}
⤵️ Response:
{
"id": 9,
"result": {
"status": "success"
},
"error": null
}
🔄 Update events:
Update event IDDescription
1New order
2Update order
3Finish order (cancel or execute)

If new order instantly matches an order from orderbook, then you will receive only one message with update event ID equal to 3.

{
"id": null,
"method": "ordersPending_update",
"params": [
2, // Update event ID (see above)
{
"id": 621879, // Order ID
"market": "BTC_USDT", // Market
"type": 1, // Order type. All types in table above
"side": 1, // Side 1 - sell, 2 - bid
"ctime": 1601475234.656275, // Created at in Unix time
"mtime": 1601475266.733574, // Modified at in Unix time
"price": "10646.12", // Order price
"amount": "0.01", // Stock amount
"left": "0.008026", // Stock amount that left to be executed.
"deal_stock": "0.001974", // Stock amount that executed
"deal_money": "21.01544088", // Money amount that executed
"deal_fee": "2.101544088", // Charged fee amount in money,
"client_order_id": "22" // Custom client order id
}
]
}

Unsubscribe

⤴️ Request:
{
"id": 10,
"method": "ordersPending_unsubscribe",
"params": []
}
⤵️ Response:
{
"id": 10,
"result": {
"status": "success"
},
"error": null
}

Orders Executed

Query

⤴️ Request:

Market should exist. The maximum limit is 100. All possible order types

{
"id": 11,
"method": "ordersExecuted_request",
"params": [
{
"market": "BTC_USDT", // market
"order_types": [1, 2] // Order types filter. See above
},
0, // offset
30 // limit
]
}
⤵️ Response:

All possible order types

{
"id": 11,
"result": {
"limit": 100,
"offset": 0,
"total": 124,
"records": [
{
"id": 3848860, // Order ID
"ctime": 1594999374.147639, // Created at in Unix time
"ftime": 1594999817.987435, // Finished at in Unix time
"market": "BTC_USDT", // Market
"type": 1, // Order type. All types in table above
"side": 2, // Side 1 - sell, 2 - bid
"price": "9157.95", // Order price
"amount": "0.633232", // Stock amount
"deal_stock": "0.633232", // Stock amount that executed
"deal_money": "5799.1069944", // Money amount that executed
"deal_fee": "5.7991069944", // Charged fee amount in money,
"client_order_id": "-a-a-a" // Custom client order id
},
...
]
},
"error": null
}

Subscribe

⤴️ Request:
{
"id": 12,
"method": "ordersExecuted_subscribe",
"params": [
[
"BTC_USDT", // market
"ETH_BTC" // market
],
0 // filter executed limit or market orders
]
}
FilterExecuted orders
0Limit and Market
1Limit
2Market
⤵️ Response:
{
"id": 12,
"result": {
"status": "success"
},
"error": null
}
🔄 Update events:
{
"id": null,
"method": "ordersExecuted_update",
"params": [
{
"id": 6887337167, // Order ID
"market": "BTC_USDT", // Market
"type": 1, // Order type. All types in table above
"side": 1, // Side 1 - sell, 2 - bid
"ctime": 1601478710.197908, // Created at in Unix time
"mtime": 1601478710.197917, // Modified at in Unix time
"price": "10745.42", // Order price
"amount": "0.001", // Stock amount
"left": "0", // Stock amount that left to be executed.
"deal_stock": "0.001", // Stock amount that executed
"deal_money": "10.74563", // Money amount that executed
"deal_fee": "0.01074563" // Charged fee amount in money
}
]
}

Unsubscribe

⤴️ Request:
{
"id": 13,
"method": "ordersExecuted_unsubscribe",
"params": []
}
⤵️ Response:
{
"id": 13,
"result": {
"status": "success"
},
"error": null
}

Deals

Query

⤴️ Request:

Market should exist. The maximum limit is 100.

{
"id": 14,
"method": "deals_request",
"params": [
"BTC_USDT", // market
0, // offset
30 // limit
]
}
⤵️ Response:
{
"id": 14,
"result": {
"limit": 100,
"offset": 0,
"total": 124,
"records": [
{
"time": 1602760519.688911, // Deal time
"id": 251923106, // Deal ID
"side": 1, // Side 1 - sell, 2 - bid
"role": 2, // Your role. 1 - maker, 2 - taker
"price": "11303.76", // Deal price
"amount": "0.001", // Stock amount
"deal": "11.30376", // Money amount
"fee": "0.01130376", // Deal fee in money
"market": "BTC_USDT", // Market
"deal_order_id": 7421295951 // Order ID
},
...
]
},
"error": null
}

Subscribe

⤴️ Request:
{
"id": 15,
"method": "deals_subscribe",
"params": [
[
"BTC_USDT", // market
"ETH_BTC" // market
]
]
}
⤵️ Response:
{
"id": 15,
"result": {
"status": "success"
},
"error": null
}
🔄 Update events:
{
"id": null,
"method": "deals_update",
"params": [
252104486, // Deal ID
1602770801.015587, // Deal time
"BTC_USDT", // Market
7425988844, // Order ID
"11399.24", // Price
"0.008256", // Stock amount
"0.094112125440", // Deal fee
"1234" // Custom client order id
]
}

Unsubscribe

⤴️ Request:
{
"id": 16,
"method": "deals_unsubscribe",
"params": []
}
⤵️ Response:
{
"id": 16,
"result": {
"status": "success"
},
"error": null
}