Skip to main content
WSS
wss://api.hotstuff.trade/ws
/
Subscribe to Level 2 orderbook updates for bids and asks. Each event includes an update_type set to either snapshot (a full orderbook) or delta (only the changes). When you subscribe, you’ll first receive a complete snapshot with its sequence_number. After that, you’ll get delta updates, which only include what’s changed. In a delta, any bid or ask with size: 0 means that price level has been removed. Each delta update should have a sequence number that increases by one. If you notice a gap or jump in sequence numbers, you may have missed updates. In that case, resubscribe to ensure your orderbook is accurate.

​
Example Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "subscribe",
  "params": {
    "channel": "orderbook",
    "symbol": "BTC-PERP"
  }
}

​
Example Response

The first event received after subscribing is a snapshot of the complete orderbook. Subsequent events are delta updates that modify the orderbook state.

​
Snapshot (First Event)

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "channel": "orderbook:BTC-PERP",
    "data": {
      "update_type": "snapshot",
      "books": {
        "instrument_name": "BTC-PERP",
        "bids": [
          {
            "price": 63874,
            "size": 0.0003
          }
        ],
        "asks": [
          {
            "price": 62761,
            "size": 0.05
          }
        ],
        "sequence_number": 11414520,
        "timestamp": 1770859215981
      }
    }
  }
}

​
Delta Updates (Subsequent Events)

After the initial snapshot, subsequent events contain delta updates with "update_type": "delta" that modify the orderbook state. Apply these deltas to maintain an up-to-date orderbook.

​
WebSocket Client Examples

​
Python

import websocket
import json

def on_message(ws, message):
    print(f"Received: {message}")

def on_open(ws):
    subscribe_msg = {
        "jsonrpc": "2.0",
        "id": "1",
        "method": "subscribe",
        "params": {
            "channel": "orderbook",
            "symbol": "BTC-PERP"
        }
    }
    ws.send(json.dumps(subscribe_msg))

ws = websocket.WebSocketApp("wss://api.hotstuff.trade/ws",
                          on_message=on_message,
                          on_open=on_open)
ws.run_forever()

​
JavaScript

const ws = new WebSocket("wss://api.hotstuff.trade/ws");

ws.onopen = function () {
  const subscribeMsg = {
    jsonrpc: "2.0",
    id: "1",
    method: "subscribe",
    params: {
      channel: "orderbook",
      symbol: "BTC-PERP",
    },
  };
  ws.send(JSON.stringify(subscribeMsg));
};

ws.onmessage = function (event) {
  console.log("Received:", event.data);
};
Messages
Subscription request
type:object

Send subscribe/unsubscribe request

Orderbook channel event
type:object

Server-pushed JSON-RPC event