Connect
Base endpoints:
WebSocket public channel:
Mainnet:
USDT contract: wss://stream.bybit.com/contract/usdt/public/v3
Inverse contract: wss://stream.bybit.com/contract/inverse/public/v3
USDC contract: wss://stream.bybit.com/contract/usdc/public/v3
USDC Option: wss://stream.bybit.com/option/usdc/public/v3Testnet:
USDT contract: wss://stream-testnet.bybit.com/contract/usdt/public/v3
Inverse contract: wss://stream-testnet.bybit.com/contract/inverse/public/v3
USDC contract: wss://stream-testnet.bybit.com/contract/usdc/public/v3
USDC Option: wss://stream-testnet.bybit.com/option/usdc/public/v3
WebSocket private channel:
Mainnet:
Unified margin: wss://stream.bybit.com/unified/private/v3
Contract: wss://stream.bybit.com/contract/private/v3Testnet:
Unified margin: wss://stream-testnet.bybit.com/unified/private/v3
Contract: wss://stream-testnet.bybit.com/contract/private/v3
Authentication
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]
})
)
Authentication success sample response
- contract
- unified
{
"success": true,
"ret_msg": "",
"op": "auth",
"conn_id": "ced97gevha793pjs1t30-ob"
}
{
"success": true,
"conn_id": "1e4335fffebbf409-00000001-00001a94-b5385accb911ee54-5032c2b9",
"ret_msg": "0",
"type": "AUTH_RESP"
}
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
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.
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"}));
Pong message example
- contract-private
- unified-private
- usdt-usdc-inverse-public
- option-public
{
"req_id": "test",
"op": "pong",
"args": [
"1671163042443"
],
"conn_id": "ce3e06kfnonvuu2e3j4g-2t5w"
}
{
"args": [
"1671162870671"
],
"op": "pong"
}
{
"success": true,
"ret_msg": "pong",
"conn_id": "13271fcb-53ed-4e80-948e-2bdbe3a6587d",
"req_id": "",
"op": "ping"
}
{
"args": [
"1671117705244"
],
"op": "pong"
}
To avoid networks or program issues, we recommend that you send the ping
heartbeat packet every 20 seconds to maintain the WebSocket connection.
How to Subscribe to Topics
Understanding Websocket Filters
How to subscribe with a filter
// Subscribing level 1 orderbook
{
"req_id": "test", // optional
"op": "subscribe",
"args": [
"orderbook.1.BTCUSDT"
]
}
Support subscribe multiple symbols and topics, separate with ','.
{
"req_id": "test", // optional
"op": "subscribe",
"args": [
"orderbook.1.BTCUSDT",
"publicTrade.BTCUSDT",
"orderbook.1.ETHUSDT",
]
}
Understanding Websocket Filters unsubscription
You can dynamically subscribe and unsubscribe from topics without websocket disconnection as follows:
{
"op": "unsubscribe",
"args": [
"publicTrade.ETHUSD"
],
"req_id": "customised_id"
}
Understanding Subscription Response
Topic subscription response message example
- contract-private
- unified-private
- usdt-usdc-inverse-public
- option-public
{
"success": true,
"ret_msg": "",
"op": "subscribe",
"conn_id": "ced97gevha793pjs1t30-ob"
}
{
"success": true,
"conn_id": "1e4335fffebbf409-00000001-00001a94-b5385accb911ee54-5032c2b9",
"type": "COMMAND_RESP"
}
{
"success": true,
"ret_msg": "",
"conn_id": "8876a25d-f0e5-46e0-bccf-313a3c4ad731",
"req_id": "",
"op": "subscribe"
}
{
"success": true,
"conn_id": "aa01fbfffe80af37-00000001-0002fc0c-abef9d34758eb879-2505dda0",
"type": "COMMAND_RESP"
}
Once you subscribe successfully, you'd receive result information. You can determine whether the subscription is successful based on the response.