Add Order

Description

This endpoint allows users to place and cancel orders via WebSocket.

1. URL

Both UTA and Classic Account use the Pro WebSocket endpoint for Spot and Futures trading. Margin trading is supported for Classic Account only (UTA does not support Margin yet).

Pro WebSocket Endpoint

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

Optional Query Parameter

enable_ns=true: returns inTime and outTime in nanoseconds

Default (not set): inTime and outTime are in milliseconds

For Colo UTA users, inTime / outTime are nanoseconds by default; enable_ns=true is not required.

Example

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

2. Signature and Authentication

Signature

When making a websocket connection, pass in the apikey, encrypted passphrase, sign and timestamp through the URL. This is consistent with the current REST signature method. The specific params include:

apikey: The API key as a string.

timestamp: A timestamp for your request(milliseconds).

sign: The base64-encoded signature. Use API-Secret to encrypt the pre-hash string {apikey+timestamp} with sha256 HMAC. The request body is a string and need to be the same with the parameters passed by the API. Encode contents by base64 before you pass the request.URL encoding is also required when filling in the URL.

passphrase: The passphrase you specified when creating the API key. Encrypt passphrase with HMAC-sha256 via API-Secret, Encode contents by base64 before you pass the request.URL encoding is also required when filling in the URL.

partner: Only Applicable to Broker user, Other users please do not enter this param.

partner_sign: Only Applicable to Broker user, Other users please do not enter this param.

After the connection is successful, the server will push message:

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

Authentication

Use the API-Secret to encrypt the pre-hash JSON string response above with SHA256 HMAC. Send it to the server for authentication. Upon successful authentication, the server will return a welcome message:

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

Sending ping messages based on the interval between response packets can keep the connection alive.

3. Reconnection

The connection may be disconnected, and you need to actively reconnect and re-authenticate.

4. Ping

To prevent the TCP link being disconnected by the server, the client side needs to send ping messages every pingInterval time to the server to keep alive the link.

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

After the ping message is sent to the server, the system would return a pong message to the client side.

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

If the server has not received any message from the client for a long time, the connection will be disconnected.

The WebSocket ping frame also works.

5. WS Request

For each request, the json body structure is

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

Note

If your account is in UTA mode, then op must be used in conjunction with uta.order and uta.cancel for placing and canceling orders, and you need to specify in the request body whether it's for spot or contract trading. In other words, orders placed under uta.order cannot be canceled by spot.cancel.

Data Schema

addOrderRequest

WS Request Example

op - uta.order

op - spot.order

op - spot.sync_order

op - margin.order

op - futures.order

op - futures.multi_order

For more order request examples, please refer to the corresponding endpoint page in the online REST API documentation.

6. WS Response

For successful response, the json body structure is

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

Data Schema

addOrderResponse

WS Response Example

1. UTA Futures

2. Classic Spot

3. Classic Futures

4. Classic Margin

Exception Example

1. Connection

An Error occurs during connection.

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

2. Parameter Validation

3. Rate Limit

4. Place Order

7. Code Example

Python

1. URL#

2. Signature and Authentication#

Signature#

Authentication#

3. Reconnection#

4. Ping#

5. WS Request#

Data Schema#

WS Request Example#

6. WS Response#

Data Schema#

WS Response Example#

Exception Example#

7. Code Example#

Request

1. URL

2. Signature and Authentication

Signature

Authentication

3. Reconnection

4. Ping

5. WS Request

Data Schema

WS Request Example

6. WS Response

Data Schema

WS Response Example

Exception Example

7. Code Example