Batch Add Orders Sync - KUCOIN API

Description

This endpoint supports sequential batch order placement through a single endpoint.

You can place up to 20 orders in one request.

Compared with "Batch Add Orders", this endpoint synchronously returns order information after matching is completed.

If you prefer lower latency, use "Batch Add Orders".

If you require complete return data, use this endpoint.

This endpoint only supports order placement requests.

To obtain order placement results, you must either:

query the order status, or

subscribe to WebSocket to receive order updates.

Tips

Once an order enters the order book, the system will pre-freeze the handling fee for the order.

Before placing an order, make sure you understand the parameter definitions for the specific trading pair.

Limits

Max active orders per account: 2000.

Max active orders per trading pair: 200.

Public order placement request parameters

Param	Type	Mandatory	Description
clientOid	String	No	Client Order ID, unique identifier created by the user, the use of UUID is recommended
symbol	String	Yes	symbol
type	String	Yes	Order type ‘limit’ and ‘market’
side	String	Yes	‘buy’ or ‘sell’
stp	String	No	self trade prevention is divided into four strategies: ‘CN’, ‘CO’, ‘CB’, and ‘DC’
tags	String	No	Order tag, length cannot exceed ‘20’ characters (ASCII)
remark	String	No	Order placement remarks, length cannot exceed ‘20’ characters (ASCII)

Additional Request Parameters Required by ‘limit’ Orders

Param	Type	Mandatory	Description
price	String	Yes	Specify price for currency
size	String	Yes	Specify quantity for currency
timeInForce	String	No	Order timing strategy ‘GTC’, ‘GTT’, ‘IOC’, ‘FOK’ (the default is ‘GTC’)
cancelAfter	long	No	Cancel after ‘n’ seconds, the order timing strategy is ‘GTT’
postOnly	boolean	No	passive order labels, this is disabled when the order timing strategy is ‘IOC’ or ‘FOK’
hidden	boolean	No	Hidden or not (not shown in order book)
iceberg	boolean	No	Whether or not only visible portions of orders are shown in iceberg orders
visibleSize	String	No	Maximum visible quantity in iceberg orders

Additional request parameters required by ‘market’ orders

Param	Type	Mandatory	Description
size	String	No	(Select one out of two: ‘size’ or ‘funds’)
funds	String	No	(Select one out of two: ‘size’ or ‘funds’)

Hold

For limit price purchase orders, we will hold the amount of funds (price * size) required for your purchase order. Similarly, for limit price sell orders, we will also hold you sell order assets. When the transaction is executed, the service fees will be calculated. If you cancel a portion of a filled or unfilled order, then the remaining funds or amounts will be released and returned to your account. For market price buy/sell orders that require specific funds, we will hold the required funds in from your account. If only the size is specified, we may freeze (usually for a very short amount of time) all of the funds in your account prior to the order being filled or canceled.

Order Lifecycle

When an order placement request is successful (the matching engine receives the order) or denied (due to there being insufficient funds or illegal parameter values, etc.), the system will respond to the HTTP request. When an order is successfully placed, the order ID is returned. The order will be matched, which could result in it being fully or partially filled. When an order is fully or partially filled, the remaining portions of the order will be in an active state awaiting to be matched (this does not include IOC orders). Orders that are fully or partially filled (already canceled) will be put into the “done” state.

Users that have subscribed to the Market Data Channel can use the order ID (orderId) and client ID (clientOid) to identify messages.

Price Protection Mechanisms

Price protection mechanisms ae enabled for order placements. Rules are detailed below:

If the spot trading market order/limit order placed by the user can be directly matched with an order in the current order book, the system will judge whether deviation between the price corresponding to the transaction depth and the spread exceeds the threshold value (the threshold value can be obtained using the symbol API endpoint);

If it is exceeded, for limit orders, the order will be directly canceled;

If it is a market order, then the system will partially execute the order. The execution limit will be the order size within the price range corresponding to the threshold value. The remaining orders will not be filled.

For example: If the threshold value is 10%, when a user places a market price purchase order in the KCS/USDT trading market for 10,000 USDT (the selling price is currently 1.20000), the system will determine that after the order is completely filled, the final price will be 1.40000. (1.40000-1.20000)/1.20000=16.7%>10%. The threshold value is 1.32000. The user’s market price purchase order will be filled only to a maximum of 1.32000. The remaining order portions will not be matched with orders in the order book. Note: This feature may not be able to determine depth with complete accuracy. If your order is not completely filled, it may be because the portion exceeding the threshold value was not filled.

Request

Body Params application/json

Example

{
    "orderList": [
        {
            "clientOid": "client order id 13",
            "symbol": "BTC-USDT",
            "type": "limit",
            "side": "buy",
            "price": "30000",
            "size": "0.00001"
        },
        {
            "clientOid": "client order id 14",
            "symbol": "ETH-USDT",
            "type": "limit",
            "side": "sell",
            "price": "2000",
            "size": "0.00001"
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

Example

{"code":"200000","data":[{"orderId":"6711195e5584bc0007bd5aef","clientOid":"client order id 13","orderTime":1729173854299,"originSize":"0.00001","dealSize":"0","remainSize":"0.00001","canceledSize":"0","status":"open","matchTime":1729173854326,"success":true},{"success":false,"failMsg":"The order funds should more then 0.1 USDT."}]}