簡介 - KUCOIN API

1.簡介

REST API 有嚴格的存取頻率控制，所以我們強烈建議 API 用戶利用 Websocket 來取得即時資料。

提示

建議的方式是直接建立 Websocket 連線，然後訂閱多個頻道。

2.申請連線代幣

在建立 Websocket連線之前，您需要申請一個Token

注意

此 Token 有效期限僅為 24 小時，該連線預計將於 24 小時後中斷。

應該注意的是：

如果您訂閱幣幣/杠杆資料，您需要透過幣幣基礎 URL 取得代幣：
取得公眾代幣- 幣幣/杠杆
取得私人代幣- 幣幣/杠杆

如果您訂閱合約資料，您需要透過合約基本 URL 取得代幣，而這兩個 URL 不能混用：
取得公眾代幣- 合約
取得私人代幣- 合約

3.建立連線

連線成功建立後，系統會傳送歡迎訊息。

提示

只有在收到歡迎訊息後，連線才會可用

{
  "id": "hQvf8jkno",
  "type": "welcome"
}

connectId: 連線 ID 是從用戶端取得的唯一值。歡迎訊息 ID 和錯誤訊息 ID 都是 connectId。

如果您只想接收指定主題的私人訊息，請在訂閱時設定 privateChannel 為 true。

4.心跳

{
  "id": "1545910590801",
  "type": "ping"

WebSocket 心跳機制說明

WebSocket 的心跳機制定義於以下四個 RESTful Token 生成端點中取得的參數：

Get Public Token – Classic Spot/Margin

Get Private Token – Classic Spot/Margin

Get Public Token – Classic Futures

Get Private Token – Classic Futures

上述接口會回傳以下兩個心跳參數：

pingInterval — 心跳訊息的發送間隔

pingTimeout — 心跳超時閾值

1. 參數定義

pingInterval

表示客戶端應每隔多少秒發送一次 ping。

建議依照伺服器回傳的值，在 pingInterval 內發送一次 ping。

目前伺服器設定值：18 秒。

pingTimeout

表示客戶端在送出 ping 後，應等待伺服器 pong 的最長等待時間。

若在該時間內未收到 pong，則應視為連線已斷開。

目前伺服器設定值：10 秒。

2. 行為說明

2.1 WebSocket 集群的斷線邏輯
WebSocket 集群的 Session 斷線邏輯 並不是 簡單的 pingInterval + pingTimeout。

客戶端只需確保在 每個 pingInterval 內至少發送一個 ping，不需關注額外的後端細節。

2.2 超時計時器（Timeout）重置規則
超時計時是基於最近的出站訊息，包含：

ping 訊息

業務訊息（如下單、撤單等）

任意出站訊息皆會刷新計時器。

網路延遲也需考量，一些用戶會將心跳週期設為 9 秒 以提升穩定性。

2.3 多 WebSocket Session 的心跳
每一個 WebSocket Session 都必須 實作獨立的心跳維持邏輯。
所有 Session 均需自身的 keepalive 措施，以確保不會被系統中斷。

2.4 超時情況的處理
如果客戶端設定的 pingInterval：

> 10 秒且 < 18 秒

當送出 ping 後若在 10 秒（pingTimeout） 內沒有收到 pong，
客戶端應 立即再發送一次 ping，而不是等待下一次排程的 ping。

< 10 秒

因為下一次 ping 會在超時前發出，因此不必額外添加「偵測 pong 是否回來」的邏輯。

3. 總結

pingInterval 決定 心跳發送頻率。
pingTimeout 決定 多久未收到回應視為斷線。

正確的心跳實作需遵循：

在 pingInterval 內發送心跳

依 pingTimeout 偵測伺服器是否失聯

任意出站訊息可刷新超時計時

每個 WebSocket Session 都需獨立實作心跳

此規範可確保 Classic Spot/Margin 與 Classic Futures API 下的 WebSocket 連線穩定且長時間保持活躍。

{
  "id": "1545910590801",
  "type": "pong"
}

5.訂閱

若要訂閱特定伺服器的頻道訊息，用戶端應該傳送訂閱的訊息給伺服器。

參數

ID ：ID 是標記要求的唯一字串，與 ack 的 ID 屬性相同。

topic ：您要訂閱的主題。

PrivateChannel ：您可以透過 privateChannel 參數訂閱一些私人主題。此參數預設為 "false"。當設定為 "true "時，您只能收到與您訂閱的主題相關的內容推送。

response 如果回應設定為 true，系統會在訂閱成功後傳回 ack 訊息。

//Spot Demo
{
  "id":1545910660739, //The ID should be a unique value
  "type": "subscribe",
  "topic": "/market/ticker:BTC-USDT,ETH-USDT", //Topic needs to be subscribed.Some topics support subscribing to information on multiple trading pairs by separating them with a comma (“,”).
  "privateChannel": false, //Adopted the private channel or not.Set as false by default.
  "response": true //Whether the server needs to return the receipt information of this subscription or not.Set as false by default.
}

//Future Demo
{
  "id":1545910660739, //The ID should be a unique value
  "type": "subscribe",
  "topic": "/market/ticker:XBTUSDM", //Subscribed topic.Some topics support subscribing to information on multiple trading pairs by separating them with a comma (“,”).
  "privateChannel": false, //Adopted the private channel or not.Set as false by default.
  "response": true //Whether the server needs to return the receipt information of this subscription or not.Set as false by default.
}

如果訂閱成功，系統會傳送 ack 訊息給您，這時回應會設定為 true。

{
  "id": "1545910660739",
  "type": "ack"
}

每當主題訊息產生時，系統會將相對應的訊息傳送至客戶端。關於訊息格式的詳細資訊，請查看主題的定義。

6.取消訂閱

取消訂閱您已訂閱的主題。

參數

ID ：ID 用來標記請求的唯一字串。

主題：您要取消訂閱的主題。

PrivateChannel ：您可以透過 privateChannel 參數取消訂閱某些私人主題。設定為 "true"，您可以取消訂閱相關的私人頻道推送。

回應：如果回應設定為 true，系統會在取消訂閱成功後傳回 ack 訊息。

//Spot Unsubscribe Topic
{
  "id": "1545910660739, //The ID should be a unique value
  "type": "subscribe",
  "topic": "/market/ticker:XBTUSDM", //Subscribed topic.Some topics support unsubscribing from information on multiple trading pairs by separating them with a comma (“,”).
  "privateChannel": false,
  "response": true //Whether the server needs to return the receipt information of this subscription or not.Set as false by default.
}

//合約退訂主題
{
  "id": "1545910840805", // id 應該是唯一值
  "type": "unsubscribe",
  "topic": "/market/ticker:XBTUSDM", //Topic 需要取消訂閱。Some topics support unsubscribing from information on multiple trading pairs by separating them with a comma (“,”).
  "privateChannel": false,
  "response": true //Whether the server needs to return the receipt information of this subscription or not.Set as false by default.
}

如果取消訂閱成功，系統會傳送 ack 訊息給您，這時回應會設定為 true。

{
  "id": "1545910840805",
  "type": "ack"
}

簡介

1.簡介#

2.申請連線代幣#

3.建立連線#

4.心跳#

5.訂閱#

參數#

6.取消訂閱#

參數#

1.簡介

2.申請連線代幣

3.建立連線

4.心跳

5.訂閱

參數

6.取消訂閱

參數