Connect
Note that the following endpoints only apply to Spot. To listen to other websockets, go to:
Base endpoints:
- Testnet:
- Public Topics: wss://stream-testnet.bybit.com/spot/public/v3
- Private Topics: wss://stream-testnet.bybit.com/spot/private/v3
- Mainnet:
- Public Topics: wss://stream.bybit.com/spot/public/v3
- Private Topics: wss://stream.bybit.com/spot/private/v3
Apply for authentication when establishing a connection.
Note: if you're using pybit, bybit-api or another high-level library, you can ignore this code - as authentication is handled for you.
{
"req_id": "10001", // optional
"op": "auth",
"args": [
"api_key",
1662350400000, //expires; is greater than your current timestamp
"singature"
]
}
# based on: https://github.com/bybit-exchange/pybit/blob/master/pybit/_http_manager.py
import hmac
import json
import time
import websocket
api_key = ""
api_secret = ""
# Generate expires.
expires = int((time.time() + 1) * 1000)
# Generate signature.
signature = str(hmac.new(
bytes(api_secret, "utf-8"),
bytes(f"GET/realtime{expires}", "utf-8"), digestmod="sha256"
).hexdigest())
ws = websocket.WebSocketApp(
url=url,
...
)
# Authenticate with API.
ws.send(
json.dumps({
"op": "auth",
"args": [api_key, expires, signature]
})
)
Example signature algorithms can be found here.
Due to network complexity, your may get disconnected at any time. Please follow the instructions below to ensure that you receive WebSocket messages on time:
- Keep connection alive by sending heartbeat packet
- Reconnect as soon as possible if disconnected
How to Send Heartbeat Packet
How to Send
// req_id is a customised id, which is optional
ws.send(JSON.stringify({"req_id": "100001", "op": "ping"}));
The response sample of Pong
// with req_id
{"op":"pong","args":[1661741630642],"req_id":"100001","conn_id":"706b870c"}
// without req_id
{"op":"pong","args":[1661741654529],"conn_id":"706b870c"}
To avoid networks or program issues, we recommend that you send the ping
heartbeat packet every 20 seconds to maintain the WebSocket connection.
IP Limits
- Do not frequently connect and disconnect the connection.
- Do not build over 500 connections in 5 minutes. This is counted separately per WebSocket endpoint.
Rate Limits
Private channel only:
- Each API key may have a maximum of 100 private WebSocket connections. The 101st connection will be rejected.
- An IP can connect to a maximum of 50 private spot websocket connections simultaneously.
How to Subscribe to Topics
Understanding Websocket Filters
How to subscribe with a filter
// Subscribing to the trade data for BTCUSDT
{
"req_id": "10001", // optional
"op": "subscribe",
"args": [
"trade.BTCUSDT"
]
}
support many symbol, separate with ','.
// Example: Subscribing to the trade data for BTCUSDT and ETHUSDT
{
"req_id": "10001", // optional
"op": "subscribe",
"args": [
"trade.BTCUSDT",
"trade.ETHUSDT"
]
}
After establishing the connection, you can subscribe to a new topic by sending a JSON request. The request formats are as follows:
ws.send('{"req_id": "10001", "op": "subscribe", "args": ["trade.BTCUSDT", "trade.ETHUSDT", "tickers.BTCUSDT", "bookticker.BTCUSDT"]}')
You can input up to 10 args for each subscription request sent to one connection
Understanding Websocket Filters unsubscription
After successful subscription, you can unsubscribe by sending a JSON request. The request formats are as follows:
ws.send('{"req_id": "10002", "op": "unsubscribe", "args": ["trade.BTCUSDT"]}');
// Example: unsubscribing to the trade data for BTCUSDT and ETHUSDT
{
"req_id": "10002", // optional
"op": "unsubscribe",
"args": [
"trade.BTCUSDT",
"trade.ETHUSDT"
]
}
// unsubscribe response sample
{
"op": "unsubscribe",
"success": true,
"req_id": "10002",
"ret_msg": "unsubscribe",
"conn_id": "46f097b7"
}
Understanding Subscription Response
Subscription Response
{
"op": "subscribe",
"success": true,
"req_id": "10001",
"ret_msg": "subscribe",
"conn_id": "46f097b7"
}
Once you subscribe successfully, you'd receive result information. You can determine whether the subscription is successful based on the response.