Skip to main content

Connect

info

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
info
Public topics do not require authentication. The following section applies to private topics only.

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]
    })
)
info

Example signature algorithms can be found here.

caution

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:

  1. Keep connection alive by sending heartbeat packet
  2. 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"}
caution

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"]}')
tip

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.