Skip to main content

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/v3

  • Testnet:
    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/v3

  • Testnet:
    Unified margin: wss://stream-testnet.bybit.com/unified/private/v3
    Contract: wss://stream-testnet.bybit.com/contract/private/v3

Authentication​

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

Authentication success sample response

{
    "success": true,
    "ret_msg": "",
    "op": "auth",
    "conn_id": "ced97gevha793pjs1t30-ob"
}
note

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

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

{
    "req_id": "test",
    "op": "pong",
    "args": [
    "1671163042443"
    ],
    "conn_id": "ce3e06kfnonvuu2e3j4g-2t5w"
}
caution

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

{
    "success": true,
    "ret_msg": "",
    "op": "subscribe",
    "conn_id": "ced97gevha793pjs1t30-ob"
}

Once you subscribe successfully, you'd receive result information. You can determine whether the subscription is successful based on the response.