Add Order

Description

This endpoint allow users to add / cancel order through Websocket

1. URL link

UTA/Spot/Margin/Futures adopts a unified trading API, which is unified as follows:

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

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. Request

For each request, the json body structure is

{
  "id": "123421", //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
  "args": {
    //Business parameters, same as RestAPI
  }
}

The "op" parameter is one of the following enum values.
For specific business line request parameters, please refer to REST endpoint paramater:

Unified Account Mode

uta.order

uta.cancel

Classic Account Mode:

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

Example:

{
  "id" : "req001",
  "op" : "uta.order",
  "args" : {
    "symbol" : "KCS-USDT",
    "tradeType" : "SPOT",
    "price" : "12",
    "sizeUnit" : "BASECCY",
    "size" : "0.1",
    "side" : "BUY",
    "orderType" : "LIMIT"
  }
}

6. Response

For successful response, the json body structure is

{
    "id": "req001", //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 or ns)
    "outTime": 169519049142   //Gateway out time(ms or ns)
}

Example

UTA

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

classic 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)
}

classic 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}
}

classic 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}
}

For failed responses, there are several scenarios:
An error occurs during connection.

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

An error occurs during parameter validation after a successful connection.

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

(Before the parameter "id" passes, the parameters "id" are not returned.)

An error occurs due to rate limiting or insufficient permissions.

{
    "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}
}

An error occurs during order placement.

{
    "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. Request Errors (`400xxx`)

Code	Message
`400001`	Please check the URL of your request.
`400002`	Invalid `KC-API-TIMESTAMP`.
`400003`	`KC-API-KEY` does not exist.
`400004`	Invalid `KC-API-PASSPHRASE`.
`400005`	Invalid `KC-API-SIGN`.
`400006`	Invalid request IP, the current client IP is: `%s`.
`400007`	Access denied, requires more permission.
`400008`	V1 & V2 API keys are no longer supported by this API. Please create a V3 API key.
`400009`	Invalid `KC-API-KEY-VERSION`.
`400010`	UID access denied, requires more permission.
`400011`	Session verification failed. (After the server returns the sessionId, the client must sign the request with its secret and send it back, but the signature is incorrect and does not match what the server expects.)
`400012`	Session verification has timed out. (After the server returns the sessionId, the client did not send the signed request within the allowed time window (e.g. 30 seconds), so the server aborted verification.)

2. Partner Errors (`4002xx`)

Code	Message
`400200`	Unknown partner.
`400201`	Invalid `KC-API-PARTNER-SIGN`.
`400202`	Invalid request IP.

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

Code	Message
`400301`	Operation restricted due to local laws, regulations, or policies in your country or region.
`400302`	Based on your IP, services are unavailable in your region due to regulations. Please contact support.
`400303`	Identity verification required to access full features.
`400304`	Please log in with your master account to complete identity verification.

4. Authorization Errors (`4004xx`)

Code	Message
`400400`	Invalid authorization token.
`400401`	Authorization is required.

5. Data Errors (`4001xx`)

Code	Message
`400101`	Invalid request data.
`400102`	Please check the parameters of your request.

6. Websocket Errors to disconnect

Code	Message
`420001`	Too many errors, disconnected. Please try again later.
`420002`	Error receiving data.

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

Code	Message
`429000`	Too many requests in a short period. Please retry later.(UID LIMIT)
`429001`	Too many total requests in a short period. Please retry later.(SYSTEM LIMIT)
`429002`	Too many requests in a short period. Please retry later. (MULTY LIMIT PER CONNECTION)

8. User Restriction Errors (`411xxx`)

Code	Message
`411200`	URL is in the user blacklist.

9. Server Errors (`5xxxxx`)

Code	Message
`500000`	Internal server error.
`503000`	Server is busy. Please retry later.
`504000`	Gateway timeout.
`505000`	Unknown error.

1. URL link#

2. Signature and Authentication#

Signature#

Authentication#

3. Reconnection#

4. Ping#

5. Request#

Unified Account Mode#

Classic Account Mode:#

Example:#

6. Response#

Example#

7. Python Example#

Request#

Response#

GATEWAY ERROR CODE#

1. Request Errors (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. Signature and Authentication

Signature

Authentication

3. Reconnection

4. Ping

5. Request

Unified Account Mode

Classic Account Mode:

Example:

6. Response

Example

7. Python Example

Request

Response

GATEWAY ERROR CODE

1. Request Errors (`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`)