新增訂單

Description

此端點允許用戶通過 WebSocket 新增訂單

推送頻率: 實時

1. URL link

統一帳戶/幣幣/槓桿/合約採用統一的交易 API，統一如下:

wss://wsapi.kucoin.com/v1/private?apikey=xxx&sign=xxx&passphrase=xxx&timestamp=xxx

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": timestamp}

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

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

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

WebSocket 的 ping 同樣有效。

5. Request

對於每個請求，JSON 主體結構如下：

{
  "id": "123421", //User-defined ID (not orderid) is used to uniquely represent a request. The server will also return this ID when returning."id" 參數不得超過 32 字節，總長度不得超過 1023 字節。
  "op": "spot.order",  //Command options
  "args": {
    //Business parameters, same as RestAPI
  }
}

"op" 參數為以下枚舉值之一, 有關具體業務線請求參數，請參考对应的REST接口参数

經典帳戶模式

uta.order

uta.cancel

統一帳戶模式

spot.order

margin.order

futures.order

spot.cancel，spot.cancel

margin.cancel， margin.cancel

futures.cancel，futures.cancel

10.

11.

spot.sync_cancel，spot.sync_cancel

示例:

{
  "id" : "ce5f74b8-df21-4d82-829a-1041a43a5bf4",
  "op" : "uta.order",
  "args" : {
    "symbol" : "KCS-USDT",
    "tradeType" : "SPOT",
    "price" : "12",
    "sizeUnit" : "BASECCY",
    "size" : "0.1",
    "side" : "BUY",
    "orderType" : "LIMIT"
  }
}

6. 響應

對於成功的響應，JSON 主體結構如下：

{
    "id": "request-001", //User-defined ID (not orderid) is used to uniquely represent a request. The server will also return this ID when returning. The "id" parameter must not exceed 32 bytes, and the total length must not exceed 1023 bytes.
    "op": "spot.order", //Command options
    "code": "200000",
    "data": {
       //Business parameters, same as RestAPI
    },
    "inTime": 1695190491421,   //Gateway in time(ms)
    "outTime": 1695190491420   //Gateway out time(ms)
}

示例

UTA

{
  "code" : "200000",
  "op" : "uta.order",
  "data" : {
    "ts" : 1.764580529696e+18,
    "orderId" : "384900069482139648",
    "tradeType" : "SPOT",
    "clientOid" : null
  },
  "id" : "ce5f74b8-df21-4d82-829a-1041a43a5bf4",
  "outTime" : 1764580529697,
  "inTime" : 1764580529645
}

spot:

{
    "id": "request-001",
    "op": "spot.order",
    "code": "200000",
    "data": {
        "orderId": "670fd33bf9406e0007ab3945",
        "clientOid": "5c52e11203aa677f33e493fb"
    },
    "inTime": 1695190491421,   //Gateway in time(ms)
    "outTime": 1695190491420   //Gateway out time(ms)
}

futures:

{
    "id": "request-001",
    "op": "futures.order",
    "code": "200000",
    "data": {
        "orderId": "234125150956625920",
        "clientOid": "5c52e11203aa677f33e493fb"
    },
    "inTime": 1695190491421,   //Gateway in time(ms)
    "outTime": 1695190491420,   //Gateway out time(ms)
    "rateLimit":{"limit":1600,"reset":15244,"remaining":1528}
}

margin:

{
    "id": "request-001",
    "op": "margin.order",
    "code": "200000",
    "data": {
        "orderId": "671663e02188630007e21c9c",
        "clientOid": "5c52e11203aa677f33e1493fb",
        "borrowSize": "10.2",
        "loanApplyId": "600656d9a33ac90009de4f6f"
    },
    "inTime": 1695190491421,   //Gateway in time(ms)
    "outTime": 1695190491420,   //Gateway out time(ms)
    "rateLimit":{"limit":1600,"reset":15244,"remaining":1528}
}

對於失敗的響應，有以下幾種情況：

連接過程中發生錯誤：

{
    "code":"400003",
    "msg":"KC-API-KEY not exists.",
    "inTime":1741589088843,
    "outTime":1741589088848
}

成功連接後，參數驗證過程中發生錯誤：

{
    "code":"4001002",
    "msg":"Please check the param of your request: Field 'id' must be a non-empty string.",
    "inTime":1741589852155,
    "outTime":1741589852155
}

（在參數 "id" 通過驗證之前，不會返回參數 "id"。）

因速率限制或權限不足導致的錯誤：

{
    "code":"429000",
    "id":"order-1741590647179",
    "op":"futures.order",
    "msg":"Too many requests in a short period of time, please retry later.",
    "inTime":1741589852255,
    "outTime":1741589852355,
    "rateLimit":{"limit":1600,"reset":15244,"remaining":1528}
}

下單過程中發生錯誤：

{
    "code":"100003",
    "id":"order-1741587922100",
    "op":"futures.order",
    "msg":"Contract parameter invalid.",
    "inTime":1741587922123,
    "outTime":1741587922128,
    "rateLimit":{"limit":1600,"reset":15244,"remaining":1528}
}

7. Python Example

Request

Data Schema

addOrderRequest

Example

{
    "id": "request-001",
    "op": "futures.order",
    "args": {
        "price": "43187.00",
        "quantity": 0.1,
        "side": "BUY",
        "symbol": "BTCUSDT",
        "timeInForce": "GTC",
        "timestamp": 1702555533821,
        "type": "LIMIT",
    }
}

Response

Data Schema

addOrderResponse

Example

{
    "id": "request-001",
    "data": {
        "orderId": "189227113527341368",
    },
    "code": "200000",
    "op": "futures.order",
    "inTime": 1695190491421,   //Gateway in time(ms)
    "outTime": 1695190491420,   //Gateway out time(ms)
    "rateLimit":{"limit":1600,"reset":15244,"remaining":1528}
}

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 link#

2. 簽名與認證#

簽名#

認證#

3. 重新連接#

4. Ping#

5. Request#

經典帳戶模式#

統一帳戶模式#

示例:#

6. 響應#

示例#

7. Python Example#

Request#

Response#

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 link

2. 簽名與認證

簽名

認證

3. 重新連接

4. Ping

5. Request

經典帳戶模式

統一帳戶模式

示例:

6. 響應

示例

7. Python Example

Request

Response

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`)