跳至主要内容

訂閱WebSocket

信息

以下WSS地址僅適用現貨. 要想接收期貨的推送，請前往:

訂閱地址:
測試網:

  • 公有頻道: wss://stream-testnet.bybit.com/spot/public/v3
  • 私有頻道: wss://stream-testnet.bybit.com/spot/private/v3

主網:

  • 公有頻道: wss://stream.bybit.com/spot/public/v3
  • 私有頻道: wss://stream.bybit.com/spot/private/v3
信息

公有頻道不需要鑒權. 以下內容僅適用於私有頻道的訂閱

構建連接時，創建鑒權請求。

注意: 如果您正在使用pybit, bybit-api或者其他第三方庫, 您可以忽略此項-因為鑒權已經內建。

{
    "req_id": "10001", // 可選
    "op": "auth",
    "args": [
        "api_key",
        1662350400000, //過期時間應當大於當前時間戳
        "singature"
    ]
}
# 基於: https://github.com/bybit-exchange/pybit/blob/master/pybit/_http_manager.py

import hmac
import json
import time
import websocket

api_key = ""
api_secret = ""

# 生成expires
expires = int((time.time() + 1) * 1000)

# 生成簽名
signature = str(hmac.new(
    bytes(api_secret, "utf-8"),
    bytes(f"GET/realtime{expires}", "utf-8"), digestmod="sha256"
).hexdigest())

ws = websocket.WebSocketApp(
    url=url,
    ...
)

# 發送鑒權請求
ws.send(
    json.dumps({
        "op": "auth",
        "args": [api_key, expires, signature]
    })
)

鑒權成功的響應示例

{
    "success": true,
    "ret_msg": "",
    "conn_id": "06a3cbfffe5df9cb-0000000e-00026965-fe306ee9ec20f544-4ab7116c",
    "req_id": "",
    "op": "auth"
}
信息

簽名生成的示例可以參考這裡。

警告

由於網絡的複雜性，您可能隨時遇到斷連。請參考以下建議確保您能即時接收到推送：

  1. 通過發送心跳
  2. 遇到斷連時，立即重新連接

IP限頻​

  • 不要嘗試頻繁地構建連接與斷開連接；
  • 不要在5分鐘內構建超過500個連接。

如何發送心跳​

發送ping的示例

// req_id是可選參數
ws.send(JSON.stringify({"req_id": "100001", "op": "ping"}));

接收到pong的響應示例

// 有req_id
{
    "op": "pong",
    "args": [
        1661741630642
    ],
    "req_id": "100001",
    "conn_id": "706b870c"
}

// 沒有req_id
{
    "op": "pong",
    "args": [
        1661741654529
    ],
    "conn_id": "706b870c"
}
警告

為了維持連接，我們推薦您每20秒發送一次心跳。

頻率限制​

僅限私有頻道：

  • 每個api_key最多可以保持100個websocket私有連接，超過100個連接後的新連接會被服務器拒絕。
  • 單個IP同時最多50個websocket私有topic鏈接

如何訂閱topic​

理解Websocket裡的args​

通過傳入args來訂閱指定topic

// 訂閱trade下的BTCUSDT
{
    "req_id": "10001", // 可選
    "op": "subscribe",
    "args": [
        "trade.BTCUSDT"
    ]
}

通過","來訂閱同一個topic下的多個交易對

{
    "req_id": "10001", // 可選
    "op": "subscribe",
    "args": [
        "trade.BTCUSDT",
        "trade.ETHUSDT"
    ]
}

訂閱多個topic

ws.send('{"req_id": "10001", "op": "subscribe", "args": ["trade.BTCUSDT", "trade.ETHUSDT", "tickers.BTCUSDT", "bookticker.BTCUSDT"]}')
提示

每次向單一連接僅能發送不超過10個參數的訂閱請求，但單個公有連接沒有args訂閱限制

理解如何取消訂閱​

您可以通過發送請求來動態地停止訂閱

ws.send('{"req_id": "10002", "op": "unsubscribe", "args": ["trade.BTCUSDT"]}');
// 示例: 取消訂閱BTCUSDT和ETHUSDT
{
    "req_id": "10002", // 可選
    "op": "unsubscribe",
    "args": [
        "trade.BTCUSDT",
        "trade.ETHUSDT"
    ]
}
// 取消訂閱的響應
{
    "op": "unsubscribe",
    "success": true,
    "req_id": "10002",
    "ret_msg": "unsubscribe",
    "conn_id": "46f097b7"
}

理解訂閱的響應​

訂閱成功後的響應示例

// 公共頻道的響應
{
    "op": "subscribe",
    "success": true,
    "req_id": "10001",
    "ret_msg": "subscribe",
    "conn_id": "46f097b7"
}
// 私有頻道的響應
{
    "success": true,
    "ret_msg": "",
    "conn_id": "06a3cbfffe5df9cb-0000000e-00026965-fe306ee9ec20f544-4ab7116c",
    "req_id": "private0001",
    "op": "subscribe"
}

訂閱成功後，您將收到結果信息。可以根據響應判斷訂閱是否成功。