Connect

caution

Note that currently Copy Trading only supports USDT perpetual and the following endpoints only apply to USDT Perpetual

Base endpoints:

• Testnet:
• Public Channel: wss://stream-testnet.bybit.com/contract/usdt/public/v3
• Private Channel: wss://stream-testnet.bybit.com/realtime_private
• Mainnet:
• Public Channel: wss://stream.bybit.com/contract/usdt/public/v3
• Private Channel: wss://stream.bybit.com/realtime_private

info

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

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

The response sample of authentication success

{
    "success": true,
    "ret_msg": "",
    "conn_id": "16c79bf6-267d-4e06-a0c1-3ca4ed3a293d",
    "request": {
        "op": "auth",
        "args": [
            "OZUDHROKUZZNVZWHKN",
            "1673261297304",
            "63ae5f1064130d8e931b5d937500461b87c00b2a939284e455fe8ea1e27387f6"
        ]
    }
}

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

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

ws.send('{"op":"ping"}');

Pong response Example

// Pong example of public channel
{
    "success": true,
    "ret_msg": "pong",
    "conn_id": "13271fcb-53ed-4e80-948e-2bdbe3a6587d",
    "req_id": "",
    "op": "ping"
}

// Pong example of private channel
{
    "success": true,
    "ret_msg": "pong",
    "conn_id": "16c79bf6-267d-4e06-a0c1-3ca4ed3a293d",
    "request": {
        "op": "ping",
        "args": null
    }
}

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 ','.

// Example: Subscribing to the trade data for BTCUSDT and ETHUSDT
{
    "req_id": "test", // optional
    "op": "subscribe",
    "args": [
        "publicTrade.BTCUSDT",
        "publicTrade.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('{"op": "subscribe", "args": ["orderbook.1.BTCUSDT","publicTrade.BTCUSDT","orderbook.1.ETHUSDT]}')

Understanding Websocket Filters unsubscription

After successful subscription, you can unsubscribe by sending a JSON request. The request formats are as follows:

ws.send('{"op": "unsubscribe", "args": ["publicTrade.BTCUSDT"]}');

{
    "op": "unsubscribe",
    "args": [
        "publicTrade.BTCUSDT"
    ]
}

Understanding Subscription Response

Subscription Response

// Subscription response of public channel
{
    "success": true,
    "ret_msg": "",
    "conn_id": "322b49ce-d6a5-494a-9019-f1d51cd541ae",
    "req_id": "",
    "op": "subscribe"
}

// Subscription response of private channel
{
    "success": true,
    "ret_msg": "",
    "conn_id": "16c79bf6-267d-4e06-a0c1-3ca4ed3a293d",
    "request": {
        "op": "subscribe",
        "args": [
            "copyTradePosition",
            "copyTradeOrder",
            "copyTradeExecution"
        ]
    }
}

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