The WebSocket connections go through the following lifecycle:

  • Establish a WebSocket connection with the endpoint
    • wss://ws.testnet.bsx.exchange - testnet
    • wss://ws.bsx.exchange : mainnet
  • Subscribe to a channel:
{"op": "sub", "channel": "book", "product": "BTC-PERP"}
  • Receive subscription confirmation messages:
{
    "channel": "book",
    "product": "ETH-PERP",
    "type": "subscribed"
}
  • And receive data:
// Response
{
    "channel": "book",
  	"product": "BTC-PERP",
    "type": "snapshot",
    "data": {
        "bids": [ 
            ["36000", "50"],
            ["36200", "20"],
            ["36300", "10"]
        ], 
        "asks": [ 
            ["36500", "10"],
            ["36650", "20"],
            ["36800", "50"]
        ],
        "timestamp": "1699536383000"
    }
}
  • To unsubscribe from a channel, send an unsub message
{"op": "unsub", "channel": "book", "product": "BTC-PERP"}

and receive the unsubscribe confirmation

{ 
    "type": "unsubscribed",
    "channel": "book",
  	"product": "BTC-PERP"
}

Connection heartbeat

The WebSocket feed uses PING/PONG messages to keep the connection alive. The server will close an idle connection after 10 minutes.

In order to sustain a connection, send ping messages at regular intervals (every 15 seconds): {'op': 'ping'}. You will see an {'type': 'pong'} response.

Connection end

Before web-socket server closes the connection, it should return message(s) indicate why it closes the connection. Example:

{
    "type": "message",
    "message": "bye - service is shutting down"
}