簡介 - KUCOIN API

重要通知：

UTA API 目前仍在積極開發中，尚未正式發布。

在目前階段（Phase 1），僅支援現貨（Spot）與合約（Futures）。槓桿交易（Margin）與期權（Options）尚未提供。我們計畫在 2026 年逐步新增對這些產品的支援。

請勿在任何情況下將此 API 用於生產環境或實盤交易。端點 URL、參數、回應結構以及整體行為皆可能在未事先通知的情況下變更。

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

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

1. 介紹

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

提示

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

2. 申請 Connect Token

在建立 WebSocket 連線之前，您需要取得 WebSocket Base URL 並申請 Token。

Note

Token 僅有效 24 小時，且單一連線預期會在 24 小時後斷線。

需要注意的是：

若您訂閱的是公開資料（public data），不需要取得 token

若您訂閱的是私有資料（private data），需要透過以下端點取得代表您身分的 token：
Get Private Token - Pro API Private Channels

3. 建立連線

私有資料推送（private data）

公開市場資料推送（public market data），不需要 token

當連線成功建立後，系統會發送一則 welcome 訊息。

提示

只有在收到 welcome 訊息後，連線才可用。welcome 訊息中會包含建議的 ping 間隔（毫秒），客戶端應依此間隔向伺服器送出 ping 以維持連線。

{"sessionId":"7245afa1-a57c-4f90-b4bd-90126387214b","message":"welcome","pingInterval":30000}

sessionId：sessionId 是用於識別連線的唯一 ID，可用於 KuCoin 開發團隊的問題排查。
pingInterval：建議客戶端送出 ping 訊息以維持連線的間隔（毫秒）。

4. Ping

{
  "id": "1545910590801",    // 無特殊限制
  "type": "ping"
}

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

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

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

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

{
  "id": "1545910590801",    // 無特殊限制
  "type": "pong",
  "ts": 1764577015970496582
}

5. 訂閱（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 的定義說明。

6. 取消訂閱（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. 申請 Connect Token#

3. 建立連線#

4. Ping#

5. 訂閱（Subscribe）#

參數#

6. 取消訂閱（UnSubscribe）#

參數#

1. 介紹

2. 申請 Connect Token

3. 建立連線

4. Ping

5. 訂閱（Subscribe）

參數

6. 取消訂閱（UnSubscribe）

參數