Add Order

Description

This endpoint allow users to add order through Websocket

Push frequency: real-time

1. URL link

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

wss://mixed-ws-colo.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

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. 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": 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": 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.

4. 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.
  "op": "spot.order",  //Command options
  "args": {
    //Business parameters, same as RestAPI
  }
}

The "id" parameter must not exceed 32 bytes, and the total length must not exceed 1023 bytes.

The "op" parameter is one of the following six enum values.

spot.order

margin.order

futures.order

spot.cancel

margin.cancel

futures.cancel

For specific business line request parameters, please refer to:

Spot Add Order

Margin Add Order

Futures Add Order

5. Response

For successful response, the json body structure is

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

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

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
}

An error occurs during order placement.

{
    "code":"100003",
    "id":"order-1741587922100",
    "op":"futures.order",
    "msg":"Contract parameter invalid.",
    "inTime":1741587922123,
    "outTime":1741587922128,
}

7. Python Example

Request

Data Schema

addOrderRequest

string

required

User-defined generation, used to uniquely represent a request; the server will also return this ID when returning

enum<string>

required

Operation type

Allowed values:

spot.orderfutures.ordermargin.order

args

object

required

Business parameters, same as RestAPI

price

string

required

quantity

number

required

side

string

required

symbol

string

required

timeInForce

string

required

timestamp

integer

required

type

string

required

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

string

required

string

required

data

array [object {1}]

required

orderId

string

required

Order id

inTime

integer

required

In time by the websocket gateway (ms)

outTime

integer

required

Out time by the websocket gateway (ms)

Example

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

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.
`400012`	Session verification has timed out.

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. Ping#

4. Request#

5. Response#

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

4. Request

5. Response

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