新增訂單

Description

此端點允許使用者透過 WebSocket 下單與取消訂單。

1. URL

UTA 與 經典帳戶（Classic Account） 均使用 Pro WebSocket 端點進行 現貨（Spot） 與 合約（Futures） 交易。槓桿（Margin） 僅支援 經典帳戶（UTA 目前尚不支援槓桿）。

Pro WebSocket 端點

wss://wsapi.kucoin.com/v1/private?apikey=689***2b6&timestamp=1768878266952&sign=H/G***%3D&passphrase=aLs***3D

可選 Query 參數

enable_ns=true：回傳 inTime 與 outTime 的單位為納秒

預設（未設定）：inTime 與 outTime 的單位為毫秒

對於 Colo UTA 使用者，inTime / outTime 預設即為納秒；不需要設定 enable_ns=true。

範例

wss://wsapi.kucoin.com/v1/private?apikey=689***2b6&timestamp=1768878266952&sign=H/G***%3D&passphrase=aLs***3D&enable_ns=true

2. 簽名與認證

簽名

在建立 WebSocket 連接時，通過 URL 傳遞 apikey、加密的 passphrase、sign 和 timestamp。這與當前的 REST signature 方法一致。具體參數包括：

apikey: API 金鑰，格式為字串。

timestamp: 請求的時間戳（毫秒）。

sign: Base64 編碼的簽名。使用 API-Secret 對預雜湊字串 {apikey+timestamp} 進行 SHA256 HMAC 加密。請求主體為字串，需與 API 傳遞的參數一致。在填入 URL 前需進行 Base64 編碼及 URL 編碼。

passphrase: 創建 API 金鑰時指定的密碼。使用 API-Secret 對密碼進行 HMAC-SHA256 加密，在傳遞請求前進行 Base64 編碼及 URL 編碼。

partner: 僅適用於 經紀商 用戶，其他用戶請勿輸入此參數。

partner_sign: 僅適用於 經紀商 用戶，其他用戶請勿輸入此參數。

連接成功後，服務器將推送以下消息：

{
    "sessionId": "92f2aec4-d87e-47cc-917d-4e7c93911bdc",
    "timestamp": 1742175983882
}

認證

使用 API-Secret 對上述 JSON 字串響應進行 SHA256 HMAC 加密，然後將其發送至服務器進行認證。認證成功後，服務器將返回歡迎消息：

{
    "sessionId": "92f2aec4-d87e-47cc-917d-4e7c93911bdc",
    "data": "welcome",
    "pingInterval": 18000,
    "pingTimeout": 10000
}

根據響應數據包之間的間隔時間發送 ping 消息可以保持連接活躍。

3. 重新連接

連接可能會斷開，您需要主動重新連接並重新進行認證。

4. Ping

為防止服務器斷開 TCP 鏈接，客戶端需每隔 pingInterval 時間向服務器發送 ping 消息，以保持鏈接活躍：

{
    "id": "ping-123",
    "op": "ping",
    "timestamp": your_timestamp
}

在向服務器發送 ping 消息後，系統將返回 pong 消息給客戶端：

{
    "id": "ping-123",
    "op": "pong",
    "timestamp": server_timestamp
}

如果服務器長時間未收到客戶端的任何消息，連接將被斷開。

WebSocket 的 ping 同樣有效。

5. WS 請求

每個請求的 JSON 本文結構如下：

{
    "id": "759ad5add86b4b09b35145a4d6f49488",
    "op": "spot.order",
    "args": {}
}

Note

若您的帳戶為 UTA 模式，則下單與取消訂單需搭配使用 uta.order 與 uta.cancel，並且需要在請求本文中指定是現貨或合約交易。換言之，透過 uta.order 下的訂單無法使用 spot.cancel 取消。

資料結構（Data Schema）

addOrderRequest

請求範例

op - uta.order

op - spot.order

op - spot.sync_order

op - margin.order

op - futures.order

op - futures.multi_order

更多下單請求範例，請前往線上 REST API 文件中對應的介面頁面查看。

6. WS 回應

成功回應時，JSON 本文結構如下：

{
    "code": "200000",
    "data": {
        "clientOid": "ae0a3849999a498ead7ac5e721a271e0d5fa80cd",
        "orderId": "403004610618449920",
        "tradeType": "FUTURES",
        "ts": 1768896988635000000
    },
    "id": "07910d5513a24fcea60d41e575c641a3",
    "inTime": 1768896988634568000,  // ms 或 ns
    "op": "uta.order",
    "outTime": 1768896988636220000, // ms 或 ns
    "userRateLimit": {
        "limit": 2000,
        "remaining": 1999,
        "reset": 14406
    }
}

資料結構（Data Schema）

addOrderResponse

成功範例

1. UTA 期貨

2. 經典現貨

3. 經典期貨

4. 經典槓桿

例外範例

1. 連線

2. 參數校驗

3. 速率限制

4. 下單

7. Code Example

Python

1. URL#

2. 簽名與認證#

簽名#

認證#

3. 重新連接#

4. Ping#

5. WS 請求#

資料結構（Data Schema）#

請求範例#

6. WS 回應#

資料結構（Data Schema）#

成功範例#

例外範例#

7. Code Example#

Request

1. URL

2. 簽名與認證

簽名

認證

3. 重新連接

4. Ping

5. WS 請求

資料結構（Data Schema）

請求範例

6. WS 回應

資料結構（Data Schema）

成功範例

例外範例

7. Code Example