簡介 - KUCOIN API

重要通知：

目前已上線「自動負載均衡機制」，以進一步提升 API 服務穩定性與延遲表現。系統將根據各實例的即時負載情況，動態進行流量均衡與資源調配，幫助客戶獲得更穩定的連接品質與更優的延遲體驗。

後續在進行負載切換時，部分 WebSocket 連接可能出現服務器主動斷開的情況。此類負載切換預計每週最多發生一至兩次，重新建立連接後即可恢復正常。

1. 介紹

雖然 REST API 有嚴格的存取頻率控制，我們強烈建議 API 使用者使用 WebSocket 取得即時資料。

提示

建議方式是建立一個 WebSocket 連線，並訂閱多個頻道。

2. 建立連線

公開市場資料推送（public market data）

私有資料推送（private data）

Websocket 交易

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

提示

針對公共頻道（Public Channel）與私有頻道（Private Channel）：

一旦連線建立，系統將發送一則歡迎訊息（welcome message）。但若為私有頻道，仍需自行發送身份驗證訊息（authentication message）至伺服器。此外，為維持連線（keepalive），伺服器會提供建議的 ping 訊息發送間隔（以毫秒為單位），應依此間隔向伺服器發送 ping 訊息。

// 公開市場資料推送（public market data）
{"sessionId":"81f56400-e7e3-4f2b-b0f6-5e649f48c302","message":"welcome","pingInterval":18000}
// 私有資料推送（private data
{"sessionId":"f39d99cb-8aef-41c0-b859-97753b9101e2","message":"welcome","pingInterval":18000,"pingTimeout":10000}

sessionId: sessionId 為識別連線的唯一編號，可供 KuCoin 開發團隊進行問題排查。
pingInterval: 客戶端傳送 ping 訊息至伺服器以維持連線的建議間隔，單位為毫秒。
pingTimeout: 客戶端預期收到伺服器 pong 回應的時間區間，單位為毫秒。

3. 生成簽名

提示

公有行情推送, 請跳過 step 3 and step 4

使用 API-Secret 以 sha256 HMAC 加密預湊字串{timestamp+POST/api/websocket/users/verify} 以生成kc-api-sign

使用 API-Secret 以 sha256 HMAC 加密passphrase(API key創建時設定的) 以生成kc-api-passphrase

4. 發送鑒權信息

Header	Required	Description
op	Yes	設為 'auth'。
kc-api-key	Yes	您的 API Key（字串）。
kc-api-sign	Yes	請求所產生的 Base64 編碼簽名。
kc-api-timestamp	Yes	請求時間戳（毫秒）。
kc-api-passphrase	Yes	請求所產生的 Base64 passphrase。
kc-api-partner	No	僅適用於websocket 交易連接和經紀商用戶。
kc-api-partner-sign	No	僅適用於websocket 交易連接和經紀商用戶。
enable_ns	No	僅適用於websocket 交易連接。預設（不攜帶參數）：inTime/outTime 單位為毫秒；設定 enable_ns=true 將回傳納秒格式（Colo UTA 使用者：預設即為納秒，無需額外指定 enable_ns=true）。

提示

鑒權後，系統將發送以下訊息。

// Websocket 私有頻道, 成功回應:
{"id":"71611efd-925e-4683-9363-367d479b5713","result":true}
// Websocket 私有頻道, 失敗回應:
{"id":"dfc046e6-35e7-4d34-80f2-2a51415b35b9","result":false,"message":"auth failed"}
   
// Websocket 交易, 成功回應:
{"pingTimeout":10000,"sessionId":"cbb32567-489d-4102-a35e-9dcd61dc0919","pingInterval":18000,"data":"welcome"}
// Websocket Trade, 失敗回應:
{"code":"400003","msg":"KC-API-KEY not exists.","inTime":1787905765509,"outTime":1787905768657}

Python

PHP

5. Ping

{
  "id": "1545910590801",    // No special restriction
  "op": "ping",
  "timestamp": your_timestamp // optional
}

為避免 TCP 連線被伺服器端斷開，客戶端需要每隔 pingInterval 時間向伺服器送出 ping 訊息以維持連線。

當伺服器收到 ping 訊息後，會回傳 pong 訊息給客戶端。

若伺服器長時間未收到客戶端任何訊息，將由伺服器端斷開連線。此外，若客戶端在一段時間內（例如 3 秒）未收到伺服器回傳的 pong 訊息，則應視為連線已中斷，建議重新初始化連線。

最快1秒ping一次，超出該頻率該連接會被斷連。

{
  "id": "1545910590801",    // No special restriction
  "op": "pong",
  "timestamp": server_timestamp
}

6. 訂閱（Subscribe）

為接收市場推送或私有推送，客戶端需要向伺服器送出訂閱訊息。

參數

id：用於標識請求的可選唯一字串。若在訂閱請求中傳入 id，伺服器會在確認回應中返回相同的 id；若未傳入 id，則確認回應中也不會包含 id。限制規則如下：

頻道類型	允許字元	長度限制
Pro WS Public Channel	僅支援 `A-Z`、`a-z`、`0-9`、`_`、`.`、`!`、`@`、`#`、`$`、`%`、`^`、`&`、`*`、`-`	最長 40 個字元
Pro WS Private Channel	無特殊限制	無特殊限制

action：subscribe

channel：要訂閱的頻道。

symbol：該頻道對應的交易對。

tradeType：SPOT 或 FUTURES

//現貨示例
{
  "id": "1545910660739",
  "action": "subscribe",
  "channel": "ticker",
  "symbol": "BTC-USDT",
  "tradeType": "SPOT"
}

//合約示例
{
  "id": "1545910660739",
  "action": "subscribe",
  "channel": "trade",
  "symbol": "ETHUSDTM",
  "tradeType": "FUTURES"
}

若訂閱成功，且 response 設為 true，系統會回傳 ack 訊息。

{
  "id": "1545910660739",
  "result": "true"
}

當 topic 訊息生成時，系統會將對應訊息推送至客戶端。關於訊息格式，請參考各 topic 的定義說明。

7. 取消訂閱（UnSubscribe）

取消訂閱您已訂閱的頻道。

參數

頻道類型	允許字元	長度限制
Pro WS Public Channel	僅支援 `A-Z`、`a-z`、`0-9`、`_`、`.`、`!`、`@`、`#`、`$`、`%`、`^`、`&`、`*`、`-`	最長 40 個字元
Pro WS Private Channel	無特殊限制	無特殊限制

action：固定為 unsubscribe。

channel：要取消訂閱的頻道。

symbol：該頻道對應的交易對名稱。

tradeType：SPOT 或 FUTURES。

//現貨取消訂閱示例
{
  "id": "1545910840805",
  "action": "unsubscribe",
  "channel": "ticker",
  "symbol": "BTC-USDT",
  "tradeType": "SPOT"
}

//合約取消訂閱示例
{
  "id": "1545910840805",
  "action": "unsubscribe",
  "channel": "trade",
  "symbol": "ETHUSDTM",
  "tradeType": "FUTURES"

}

若取消訂閱成功，且 response 設為 true，系統會回傳 ack 訊息。

{
  "id": "1545910840805",
  "result": "true"
}

簡介

1. 介紹#

2. 建立連線#

3. 生成簽名#

4. 發送鑒權信息#

5. Ping#

6. 訂閱（Subscribe）#

參數#

7. 取消訂閱（UnSubscribe）#

參數#

1. 介紹

2. 建立連線

3. 生成簽名

4. 發送鑒權信息

5. Ping

6. 訂閱（Subscribe）

參數

7. 取消訂閱（UnSubscribe）

參數