KUCOIN API
HomeChange LogAPI DOC V1
Language
  • 繁體中文(即將上綫)
  • Русский (скоро)
HomeChange LogAPI DOC V1
Language
  • 繁體中文(即將上綫)
  • Русский (скоро)
SDK
Telegram
Kucoin
  1. Websocket API
  2. Add/Cancel Order
  • Introduction
  • Authentication
  • Enums Definitions
  • Terms Definitions
  • SDK
  • Rate Limit
  • Change Log
  • User Service
    • Market Making Incentive Scheme
    • VIP Fast Track
    • Broker Program
  • REST
    • Account Info
      • Account & Funding
        • Get Account Summary Info
        • Get Apikey Info
        • Get Account Type - Spot
        • Get Account List - Spot
        • Get Account Detail - Spot
        • Get Account - Cross Margin
        • Get Account - Isolated Margin
        • Get Account - Futures
        • Get Account Ledgers - Spot/Margin
        • Get Account Ledgers - Trade_hf
        • Get Account Ledgers - Margin_hf
        • Get Account Ledgers - Futures
      • Sub Account
        • Add sub-account
        • Add sub-account Margin Permission
        • Add sub-account Futures Permission
        • Get sub-account List - Summary Info
        • Get sub-account Detail - Balance
        • Get sub-account List - Spot Balance (V2)
        • Get sub-account List - Futures Balance (V2)
      • Sub Account API
        • Add sub-account API
        • Modify sub-account API
        • Get sub-account API List
        • Delete sub-account API
      • Deposit
        • Add Deposit Address (V3)
        • Get Deposit Address (V3)
        • Get Deposit History
      • Withdrawals
        • Get Withdrawal Quotas
        • Withdraw (V3)
        • Cancel Withdrawal
        • Get Withdrawal History
        • Get Withdrawal History By ID
      • Transfer
        • Get Transfer Quotas
        • Flex Transfer
      • Trade Fee
        • Get Basic Fee - Spot/Margin
        • Get Actual Fee - Spot/Margin
        • Get Actual Fee - Futures
    • Spot Trading
      • Market Data
        • Get Announcements
        • Get Currency
        • Get All Currencies
        • Get Symbol
        • Get All Symbols
        • Get Ticker
        • Get All Tickers
        • Get Trade History
        • Get Klines
        • Get Part OrderBook
        • Get Full OrderBook
        • Get Call Auction Part OrderBook
        • Get Call Auction Info
        • Get Fiat Price
        • Get 24hr Stats
        • Get Market List
        • Get Client IP Address
        • Get Server Time
        • Get Service Status
      • Orders
        • Add Order
        • Add Order Sync
        • Add Order Test
        • Batch Add Orders
        • Batch Add Orders Sync
        • Cancel Order By OrderId
        • Cancel Order By OrderId Sync
        • Cancel Order By ClientOid
        • Cancel Order By ClientOid Sync
        • Cancel Partial Order
        • Cancel All Orders By Symbol
        • Cancel All Orders
        • Modify Order
        • Get Order By OrderId
        • Get Order By ClientOid
        • Get Symbols With Open Order
        • Get Open Orders
        • Get Open Orders By Page
        • Get Closed Orders
        • Get Trade History
        • Get DCP
        • Set DCP
        • Add Stop Order
        • Cancel Stop Order By ClientOid
        • Cancel Stop Order By OrderId
        • Batch Cancel Stop Orders
        • Get Stop Orders List
        • Get Stop Order By OrderId
        • Get Stop Order By ClientOid
        • Add OCO Order
        • Cancel OCO Order By OrderId
        • Cancel OCO Order By ClientOid
        • Batch Cancel OCO Order
        • Get OCO Order By OrderId
        • Get OCO Order By ClientOid
        • Get OCO Order Detail By OrderId
        • Get OCO Order List
    • Margin Trading
      • Market Data
        • Get Symbols - Cross Margin
        • Get ETF Info
        • Get Mark Price Detail
        • Get Margin Config
        • Get Mark Price List
        • Get Symbols - Isolated Margin
      • Orders
        • Add Order
        • Add Order Test
        • Cancel Order By OrderId
        • Cancel Order By ClientOid
        • Cancel All Orders By Symbol
        • Get Symbols With Open Order
        • Get Open Orders
        • Get Closed Orders
        • Get Trade History
        • Get Order By OrderId
        • Get Order By ClientOid
      • Debit
        • Borrow
        • Get Borrow History
        • Repay
        • Get Repay History
        • Get Interest History
        • Modify Leverage
      • Credit
        • Get Loan Market
        • Get Loan Market Interest Rate
        • Purchase
        • Modify Purchase
        • Get Purchase Orders
        • Redeem
        • Get Redeem Orders
      • Risk Limit
        • Get Margin Risk Limit
    • Futures Trading
      • Introduction
      • Market Data
        • Get Symbol
        • Get All Symbols
        • Get Ticker
        • Get All Tickers
        • Get Full OrderBook
        • Get Part OrderBook
        • Get Trade History
        • Get Klines
        • Get Mark Price
        • Get Spot Index Price
        • Get Interest Rate Index
        • Get Premium Index
        • Get 24hr stats
        • Get Server Time
        • Get Service Status
      • Orders
        • Add Order
        • Add Order Test
        • Batch Add Orders
        • Add Take Profit And Stop Loss Order
        • Cancel Order By OrderId
        • Cancel Order By ClientOid
        • Batch Cancel Orders
        • Cancel All Orders
        • Cancel All Stop orders
        • Get Order By OrderId
        • Get Order By ClientOid
        • Get Order List
        • Get Recent Closed Orders
        • Get Stop Order List
        • Get Open Order Value
        • Get Recent Trade History
        • Get Trade History
      • Positions
        • Get Margin Mode
        • Switch Margin Mode
        • Batch Switch Margin Mode
        • Get Max Open Size
        • Get Position Details
        • Get Position List
        • Get Positions History
        • Get Max Withdraw Margin
        • Get Cross Margin Leverage
        • Modify Cross Margin Leverage
        • Add Isolated Margin
        • Remove Isolated Margin
        • Get Cross Margin Risk Limit
        • Get Isolated Margin Risk Limit
        • Modify Isolated Margin Risk Limit
      • Funding Fees
        • Get Current Funding Rate
        • Get Public Funding History
        • Get Private Funding History
    • Copy Trading
      • Introduction
      • Add Order Test
      • Add Take Profit And Stop Loss Order
      • Cancel Order By OrderId
      • Cancel Order By ClientOid
      • Add Order
      • Get Max Open Size
      • Modify Isolated Margin Auto-Deposit Status
      • Modify Isolated Margin Risk Limit
      • Remove Isolated Margin
      • Add Isolated Margin
      • Get Max Withdraw Margin
    • Convert
      • Introduction
      • Get Convert Symbol
      • Get Convert Currencies
      • Add Convert Order
      • Get Convert Quote
      • Get Convert Order Detail
      • Get Convert Order History
      • Add Convert Limit Order
      • Get Convert Limit Quote
      • Get Convert Limit Order Detail
      • Get Convert Limit Orders
      • Cancel Convert Limit Order
    • Earn
      • Purchase
      • Get Redeem Preview
      • Redeem
      • Get Savings Products
      • Get Promotion Products
      • Get Staking Products
      • Get KCS Staking Products
      • Get ETH Staking Products
      • Get Account Holding
    • VIP Lending
      • Introduction
      • Get Discount Rate Configs
      • Get Loan Info
      • Get Accounts
    • Affiliate
      • Introduction
      • Get Account
    • Broker
      • Introduction
      • Instructions
      • Broker Application
      • API Broker
        • Introduction
        • Get Broker Rebate
      • Exchange Broker
        • Introduction
        • Submit KYC
        • Get KYC Status
        • Get KYC Status List
        • Get Broker Info
        • Add sub-account
        • Get sub-account
        • Add sub-account API
        • Get sub-account API
        • Modify sub-account API
        • Delete sub-account API
        • Transfer
        • Get Transfer History
        • Get Deposit List
        • Get Deposit Detail
        • Get Withdraw Detail
        • Get Broker Rebate
  • Websocket API
    • Base Info
      • Introduction
      • Get Public Token - Spot/Margin
      • Get Private Token - Spot/Margin
      • Get Public Token - Futures
      • Get Private Token - Futures
    • Spot Trading
      • Public Channels
        • Ticker
        • All Tickers
        • Orderbook - Level1
        • Orderbook - Level5
        • Orderbook - Level50
        • Orderbook - Increment
        • Call Auction Orderbook - Level50
        • Call Auction Data
        • Klines
        • Trade
        • Symbol Snapshot
        • Market Snapshot
      • Private Channels
        • Order V2
        • Order V1
        • Balance
        • Stop Order
    • Margin Trading
      • Public Channels
        • Index Price
        • Mark Price
      • Private Channels
        • Cross Margin Position
        • Isolated Margin Position
    • Futures Trading
      • Public Channels
        • Ticker V2
        • Ticker V1
        • Orderbook - Level5
        • Orderbook - Level50
        • Orderbook- Increment
        • Klines
        • Trade
        • Instrument
        • Funding Fee Settlement
        • Symbol Snapshot
      • Private Channels
        • Orders
        • Balance
        • Positions
        • Margin Mode
        • Cross Margin Leverage
        • Stop Orders
    • Add/Cancel Order
      • Add Order
      • Cancel Order
  • Error Code
    • HTTP
    • Spot
    • Margin
    • Futures
    • Earn
    • Broker
    • CopyTrading
  • Abandoned Endpoints
    • Introduction
    • Account & Funding
      • Get sub-account List - Summary Info (V1)
      • Get sub-account List - Spot Balance (V1)
      • Get Deposit Addresses (V2)
      • Get Deposit Addresses - V1
      • Sub-account Transfer
      • Get Deposit History - Old
      • Internal Transfer
      • Get Futures Account Transfer Out Ledger
      • Get Withdrawal History - Old
      • Futures Account Transfer Out
      • Futures Account Transfer In
      • Add Deposit Address - V1
      • Withdraw - V1
    • Spot Trading
      • Orders
        • Add Order - Old
        • Add Order Test - Old
        • Batch Add Orders - Old
        • Cancel Order By OrderId - Old
        • Cancel Order By ClientOid - Old
        • Batch Cancel Order - Old
        • Get Orders List - Old
        • Get Recent Orders List - Old
        • Get Order By OrderId - Old
        • Get Order By ClientOid - Old
        • Get Trade History - Old
        • Get Recent Trade History - Old
    • Margin Trading
      • Get Account Detail - Margin
      • Add Order - V1
      • Add Order Test - V1
      • Get Account List - Isolated Margin - V1
      • Get Account Detail - Isolated Margin - V1
    • Futures Trading
      • Modify Isolated Margin Auto-Deposit Status
      • Cancel All Orders - V1
  • Developing
    • Introduction
    • Margin Trading
      • Add Stop Order
      • Cancel Stop Order By OrderId
      • Cancel Stop Order By ClientOid
      • Batch Cancel Stop Orders
      • Get Stop Orders List
      • Get Stop Order By OrderId
      • Get Stop Order By ClientOid
      • Add OCO Order
      • Cancel OCO Order By OrderId
      • Cancel OCO Order By ClientOid
      • Batch Cancel OCO Order
      • Get OCO Order By OrderId
      • Get OCO Order By ClientOid
      • Get OCO Order Detail By OrderId
      • Get OCO Order List
    • Futures Trading
      • Get Cross Mode Margin Requirement
    • UTA
      • Market data
        • Get Announcements
        • Get Currency
        • Get Symbol
        • Get Ticker
        • Get Recent Trades
        • Get OrderBook
        • Get Klines
        • Get Futures Funding Rate
        • Get Funding Rate History
        • Get Cross Margin Config
        • Get Service Status
      • Account
        • Get Account
        • Get Sub Account
        • Get Actual Fee
        • Get Transfer Quotas
        • Get Account Ledger
      • TRADE
        • Set DCP
        • Get DCP
    • Flex Transfer
  1. Websocket API
  2. Add/Cancel Order

Add Order

wss://***.kucoin.com/v1/private
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://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. 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.
1.
spot.order
2.
margin.order
3.
futures.order
4.
spot.cancel
5.
margin.cancel
6.
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
1.
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)
} 
2.
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}
} 
3.
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
id
string 
required
User-defined generation, used to uniquely represent a request; the server will also return this ID when returning
op
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
id
string 
optional
op
string 
optional
data
array [object {1}] 
optional
orderId
string 
required
Order id
msg
string 
optional
Error return msg
inTime
integer 
required
In time by the websocket gateway (ms)
outTime
integer 
required
Out time by the websocket gateway (ms)
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)#

CodeMessage
400001Please check the URL of your request.
400002Invalid KC-API-TIMESTAMP.
400003KC-API-KEY does not exist.
400004Invalid KC-API-PASSPHRASE.
400005Invalid KC-API-SIGN.
400006Invalid request IP, the current client IP is: %s.
400007Access denied, requires more permission.
400008V1 & V2 API keys are no longer supported by this API. Please create a V3 API key.
400009Invalid KC-API-KEY-VERSION.
400010UID access denied, requires more permission.
400011Session 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.)
400012Session 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)#

CodeMessage
400200Unknown partner.
400201Invalid KC-API-PARTNER-SIGN.
400202Invalid request IP.

3. Regional & KYC Limitations (4003xx)#

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

4. Authorization Errors (4004xx)#

CodeMessage
400400Invalid authorization token.
400401Authorization is required.

5. Data Errors (4001xx)#

CodeMessage
400101Invalid request data.
400102Please check the parameters of your request.

6. Websocket Errors to disconnect#

CodeMessage
420001Too many errors, disconnected. Please try again later.
420002Error receiving data.

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

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

8. User Restriction Errors (411xxx)#

CodeMessage
411200URL is in the user blacklist.

9. Server Errors (5xxxxx)#

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

Request

Query Params
apikey
string 
required
The API key as a string
Example:
xxx
sign
string 
required
The base64-encoded signature
Example:
xxx
passphrase
string 
required
The passphrase you specified when creating the API key.
Example:
xxx
timestamp
string 
required
A timestamp for your request(milliseconds)
Example:
xxx
Modified at 2025-07-09 08:57:17
Previous
Stop Orders
Next
Cancel Order