Skip to main content

Connect

WebSocket public stream:

  • Mainnet:
    Spot: wss://stream.bybit.com/v5/public/spot
    USDT, USDC perpetual & USDC Futures: wss://stream.bybit.com/v5/public/linear
    Inverse contract: wss://stream.bybit.com/v5/public/inverse
    USDC Option: wss://stream.bybit.com/v5/public/option

  • Testnet:
    Spot: wss://stream-testnet.bybit.com/v5/public/spot
    USDT and USDC perpetual: wss://stream-testnet.bybit.com/v5/public/linear
    Inverse contract: wss://stream-testnet.bybit.com/v5/public/inverse
    USDC Option: wss://stream-testnet.bybit.com/v5/public/option

WebSocket private stream:

  • Mainnet:
    wss://stream.bybit.com/v5/private

  • Testnet:
    wss://stream-testnet.bybit.com/v5/private

WebSocket Order Entry:

  • Mainnet:
    wss://stream.bybit.com/v5/trade

  • Testnet:
    wss://stream-testnet.bybit.com/v5/trade

info
  • If your account is registered from www.bybit-tr.com, please use stream.bybit-tr.com for mainnet access
  • If your account is registered from www.bybit.kz, please use stream.bybit.kz for mainnet access
Customise Private Connection Alive Time

For private stream and order entry, you can customise alive duration by adding a param max_active_time, the lowest value is 30s (30 seconds), the highest value is 600s (10 minutes). You can also pass 1m, 2m etc when you try to configure by minute level. e.g., wss://stream-testnet.bybit.com/v5/private?max_active_time=1m.

In general, if there is no "ping-pong" and no stream data sent from server end, the connection will be cut off after 10 minutes. When you have a particular need, you can configure connection alive time by max_active_time.

Since ticker scans every 30s, so it is not fully exact, i.e., if you configure 45s, and your last update or ping-pong is occurred on 2023-08-15 17:27:23, your disconnection time maybe happened on 2023-08-15 17:28:15

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

Successful authentication sample response

{
    "success": true,
    "ret_msg": "",
    "op": "auth",
    "conn_id": "cejreaspqfh3sjdnldmg-p"
}
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 the 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.

Public channel - Args limits​

Regardless of Perpetual, Futures, Options or Spot, for one public connection, you cannot have length of "args" array over 21,000 characters.

  • Spot can input up to 10 args for each subscription request sent to one connection
  • Options can input up to 2000 args for a single connection
  • No args limit for Futures for now

How to Send the 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 of public channels

{
    "success": true,
    "ret_msg": "pong",
    "conn_id": "0970e817-426e-429a-a679-ff7f55e0b16a",
    "op": "ping"
}

Pong message example of private channels

{
    "req_id": "test",
    "op": "pong",
    "args": [
        "1675418560633"
    ],
    "conn_id": "cfcb4ocsvfriu23r3er0-1b"
}
caution

To avoid network 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"
    ]
}

Subscribing with multiple symbols and topics is supported.

{
    "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 unsubscribing from the WebSocket like so:

{
    "op": "unsubscribe",
    "args": [
        "publicTrade.ETHUSD"
    ],
    "req_id": "customised_id"
}

Understanding the Subscription Response​

Topic subscription response message example

{
    "success": true,
    "ret_msg": "",
    "op": "subscribe",
    "conn_id": "cejreassvfrsfvb9v1a0-2m"
}