Add Order
wss://***.kucoin.com/v1/private
Description
1. URL link
wss://wsapi.kucoin.com/v1/private?apikey=xxx&sign=xxx&passphrase=xxx×tamp=xxx
2. Signature and Authentication
Signature
{"sessionId":"92f2aec4-d87e-47cc-917d-4e7c93911bdc", "timestamp": 1742175983882}
Authentication
{"sessionId":"92f2aec4-d87e-47cc-917d-4e7c93911bdc", "data": "welcome", "pingInterval": 18000, "pingTimeout": 10000}
3. Ping
{"id": "ping-123", "op": "ping", "timestamp": timestamp}
{"id": "ping-123", "op": "pong", "timestamp": timestamp}
4. Request
{
"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
}
}
1.
2.
3.
4.
5.
6.
5. Response
1.
{
"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)
}
2.
{
"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}
}
3.
{
"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}
}
An error occurs during connection.
{
"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
}
{
"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 SchemaUser-defined generation, used to uniquely represent a request; the server will also return this ID when returning Operation type Business parameters, same as RestAPI
addOrderRequest
id
string
required
op
enum<string>
required
Allowed values:
spot.orderfutures.ordermargin.order
args
object
required
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 SchemaOrder id Error return msg In time by the websocket gateway (ms) Out time by the websocket gateway (ms)
addOrderResponse
id
string
optional
op
string
optional
data
array [object {1}]
optional
orderId
string
required
msg
string
optional
inTime
integer
required
outTime
integer
required
userRateLimit
object
optional
limit
integer
optional
reset
integer
optional
remaining
integer
optional
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. |
Request
Query Params
apikey
string
required
Example:
xxx
sign
string
required
Example:
xxx
passphrase
string
required
Example:
xxx
timestamp
string
required
Example:
xxx
Modified at 2025-07-09 08:57:17