新增訂單

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

範例：

{
    "id": "759ad5add86b4b09b35145a4d6f49488",
    "op": "uta.order",
    "args": {
        "tradeType": "FUTURES",
        "symbol": "XBTUSDTM",
        "side": "BUY",
        "orderType": "LIMIT",
        "sizeUnit": "UNIT",
        "size": "2",
        "price": "9000.0"
    }
}

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

GATEWAY ERROR CODE

1. 請求錯誤 (`400xxx`)

Code	Message
`400001`	請檢查您的請求URL。
`400002`	無效的 `KC-API-TIMESTAMP`.
`400003`	`KC-API-KEY` 不存在。
`400004`	無效的 `KC-API-PASSPHRASE`.
`400005`	無效的 `KC-API-SIGN`.
`400006`	無效的請求IP，當前客戶端IP為 `%s`.
`400007`	存取被拒絕，需要更多權限。
`400008`	此API不再支援V1和V2 API密鑰。請創建V3 API密鑰。
`400009`	無效的 `KC-API-KEY-VERSION`.
`400010`	UID存取被拒絕，需要更多權限。
`400011`	會話驗證失敗。（服務器返回sessionId後，客戶端必須使用其密鑰簽署請求並回傳，但簽名不正確，與服務器預期不符。）
`400012`	會話驗證已超時。（服務器返回sessionId後，客戶端未在允許的時間窗口（例如30秒）內發送簽署的請求，因此服務器中止驗證。

2. Partner Errors (`4002xx`)

Code	Message
`400200`	未知的合作夥伴。
`400201`	無效的 `KC-API-PARTNER-SIGN`.
`400202`	無效的請求IP。

3. Regional & KYC Limitations (`4003xx`)

Code	Message
`400301`	由於您所在國家或地區的當地法律、規定或政策，操作受到限制。
`400302`	根據您的IP，由於法規限制，您的地區無法使用服務。請聯繫支援。
`400303`	需要進行身份驗證以存取全部功能。
`400304`	請使用您的主帳戶登錄以完成身份驗證。

4. Authorization Errors (`4004xx`)

Code	Message
`400400`	無效的授權令牌。
`400401`	需要授權。

5. Data Errors (`4001xx`)

Code	Message
`400101`	無效的請求數據。
`400102`	請檢查您的請求參數。

6. Websocket Errors to disconnect

Code	Message
`420001`	錯誤過多，已斷線。請稍後重試。
`420002`	接收數據時發生錯誤。

7. Rate Limiting & Frequency Errors (`429xxx`)

Code	Message
`429000`	短時間內請求過多，請稍後重試。（UID限制）
`429001`	短時間內總請求過多，請稍後重試。（系統限制）
`429002`	短時間內請求過多，請稍後重試。（每連接多重限制）

8. User Restriction Errors (`411xxx`)

Code	Message
`411200`	URL在使用者黑名單中。

9. Server Errors (`5xxxxx`)

Code	Message
`500000`	內部服務器錯誤。
`503000`	服務器忙碌，請稍後重試。
`504000`	網關超時。
`505000`	未知錯誤。

1. URL#

2. 簽名與認證#

簽名#

認證#

3. 重新連接#

4. Ping#

5. WS 請求#

資料結構（Data Schema）#

範例：#

6. WS 回應#

資料結構（Data Schema）#

成功示例#

例外示例#

7. Code Example#

GATEWAY ERROR CODE#

1. 請求錯誤 (400xxx)#

2. Partner Errors (4002xx)#

3. Regional & KYC Limitations (4003xx)#

4. Authorization Errors (4004xx)#

5. Data Errors (4001xx)#

6. Websocket Errors to disconnect#

7. Rate Limiting & Frequency Errors (429xxx)#

8. User Restriction Errors (411xxx)#

9. Server Errors (5xxxxx)#

Request

1. URL

2. 簽名與認證

簽名

認證

3. 重新連接

4. Ping

5. WS 請求

資料結構（Data Schema）

範例：

6. WS 回應

資料結構（Data Schema）

成功示例

例外示例

7. Code Example

GATEWAY ERROR CODE

1. 請求錯誤 (`400xxx`)

2. Partner Errors (`4002xx`)

3. Regional & KYC Limitations (`4003xx`)

4. Authorization Errors (`4004xx`)

5. Data Errors (`4001xx`)

6. Websocket Errors to disconnect

7. Rate Limiting & Frequency Errors (`429xxx`)

8. User Restriction Errors (`411xxx`)

9. Server Errors (`5xxxxx`)