跳至主要内容

訂閱WebSocket

WebSocket 連接地址​

請選擇對應的連接環境。

WebSocket 公共頻道

市場WebSocket URL
現貨wss://stream.bybit.com/v5/public/spot
USDT、USDC 永續及 USDT 交割wss://stream.bybit.com/v5/public/linear
反向合約wss://stream.bybit.com/v5/public/inverse
價差交易wss://stream.bybit.com/v5/public/spread
RFQwss://stream.bybit.com/v5/public/rfq
期權wss://stream.bybit.com/v5/public/option
事件合約wss://stream.bybit.com/v5/public/event

私有頻道、WebSocket 交易及系統狀態

連接類型WebSocket URL
WebSocket 私有頻道wss://stream.bybit.com/v5/private
WebSocket 交易wss://stream.bybit.com/v5/trade
取得系統狀態wss://stream.bybit.com/v5/public/misc/status

備註: 事件合約目前僅對做市商(MM)開放,未來可能考慮向公眾開放。WebSocket 交易不支援價差交易。

地區主網域名

主網連接請使用與帳戶註冊站點對應的 WebSocket 域名。

註冊站點主網域名
土耳其站(www.bybit.tr)stream.bybit.tr
印尼站(www.bybit.id)stream.bybit.id
哈薩克斯坦站(www.bybit.kz)stream.bybit.kz
喬治亞站(www.bybitgeorgia.ge)stream.bybitgeorgia.ge
日本站(www.manepa.jp)stream.manepa.jp
香港站(www.spark-fintech.com)stream.spark-fintech.com

巴西或阿根廷國際站帳戶請繼續使用 stream.bybit.com;用戶端無須修改代碼。

自定義私有連接存活時長

針對私有頻道和交易, 您可以自定義連接存活時長, 通過增加參數max_active_time, 最小支持30s (30秒), 最大支持600s (10分鐘). 如果您需要按分鐘級別配置, 您也可以傳遞1m, 2m等. 例如, wss://stream-testnet.bybit.com/v5/private?max_active_time=1m.

一般來說, 當客戶端與服務端沒有上下行數據, 包括心跳和交易數據下發, 那麼該連接會在最後一條交互後維持10分鐘, 由服務端斷開. 當您由特別的需求時, 可以通過該字段max_active_time自行控制存活時間.

由於系統每30秒掃描一次, 因此配置的時長可能無法非常精確, 換句話說, 如果您配置了45秒, 然後最後一條數據下發或者心跳發生在2023-08-15 17:27:23, 您的私有連接可能在2023-08-15 17:28:15發生斷連.

鑒權​

信息
公共頻道不需要鑒權,以下部分僅適用於私有頻道的訂閱。

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

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

{
"req_id": "10001", // 可選項
"op": "auth",
"args": [
"api_key",
1662350400000, //過期時間應當大於當前時間戳
"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]
})
)

鑒權成功的響應示例

{
"success": true,
"ret_msg": "",
"op": "auth",
"conn_id": "cejreaspqfh3sjdnldmg-p"
}
備註

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

警告

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

  1. 通過發送心跳來維持連接;
  2. 遇到斷連時,立即重新連接。

IP限頻​

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

公有頻道訂閱參數限制​

不管是期貨、現貨、期權, 對於單個連接, args裡的數組元素長度總和不能超過21,000個字符

  • 現貨每次向單一連接僅能發送不超過10個參數的訂閱請求
  • 期權單個連接,至多訂閱2000個args
  • 期貨、價差交易單個連接沒有args限制

如何發送心跳​

// req_id is a customised id, which is optional
ws.send(JSON.stringify({"req_id": "100001", "op": "ping"}));

公共頻道接收到pong的響應示例

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

私有頻道接收到pong的響應示例

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

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

如何訂閱topic​

理解Websocket裡的args​

通過傳入args來訂閱指定topic

// 訂閱1檔的orderbook
{
"req_id": "test", // 可選
"op": "subscribe",
"args": [
"orderbook.1.BTCUSDT"
]
}

通過逗號隔開,可以同時訂閱多個topic或者多個symbol

{
"req_id": "test", // 可選
"op": "subscribe",
"args": [
"orderbook.1.BTCUSDT",
"publicTrade.BTCUSDT",
"orderbook.1.ETHUSDT"
]
}

理解如何取消訂閱​

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

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

理解訂閱的響應​

訂閱成功後的響應示例

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