Batch Add Orders

POST

https://api-futures.kucoin.com/api/v1/orders/multi

domain:Futures

api-channel:Private

api-permission:Futures

api-rate-limit-pool:Futures

sdk-service:Futures

sdk-sub-service:Order

sdk-method-name:batchAddOrders

api-rate-limit-weight:20

Description

Place multiple order to the futures trading system, you can place two major types of orders: limit and market. Orders can only be placed if your account has sufficient funds. Once an order is placed, your funds will be put on hold for the duration of the order. The amount of funds on hold depends on the order type and parameters specified.
You can place up to 20 orders at one time, including limit orders, market orders, and stop orders

Please be noted that the system would hold the fees from the orders entered the orderbook in advance.

Do NOT include extra spaces in JSON strings.

Place Order Limit
The maximum limit orders for a single contract is 100 per account, and the maximum stop orders for a single contract is 50 per account.

Tips

The maximum limit orders for a single contract is 100 per account, and the maximum stop orders for a single contract is 50 per account.

Request

Body Params application/json

array of:

clientOid

string

required

Unique order id created by users to identify their orders, the maximum length cannot exceed 40, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)

Example:

5c52e11203aa677f33e493fb

side

enum<string>

required

specify if the order is to 'buy' or 'sell'

Allowed values:

buysell

Example:

buy

symbol

string

required

Symbol of the contract, Please refer to Get Symbol endpoint: symbol

Example:

XBTUSDTM

leverage

integer

required

Used to calculate the margin to be frozen for the order. If you are to close the position, this parameter is not required.

Example:

type

enum<string>

optional

specify if the order is an 'limit' order or 'market' order

Allowed values:

limitmarket

Default:

limit

Example:

limit

remark

string

optional

remark for the order, length cannot exceed 100 utf8 characters

stop

enum<string>

optional

Either 'down' or 'up'. If stop is used,parameter stopPrice and stopPriceType also need to be provieded.

Allowed values:

downup

stopPriceType

enum<string>

optional

Either 'TP', 'IP' or 'MP', Need to be defined if stop is specified.

Allowed values:

TPMPIP

stopPrice

string

optional

Need to be defined if stop is specified.

reduceOnly

boolean

optional

A mark to reduce the position size only. Set to false by default. Need to set the position size when reduceOnly is true. If set to true, only the orders reducing the position size will be executed. If the reduce-only order size exceeds the position size, the extra size will be canceled.

Default:

false

closeOrder

boolean

optional

A mark to close the position. Set to false by default. If closeOrder is set to true, the system will close the position and the position size will become 0. Side, Size and Leverage fields can be left empty and the system will determine the side and size automatically.

Default:

false

forceHold

boolean

optional

A mark to forcely hold the funds for an order, even though it's an order to reduce the position size. This helps the order stay on the order book and not get canceled when the position size changes. Set to false by default. The system will forcely freeze certain amount of funds for this order, including orders whose direction is opposite to the current positions. This feature is to ensure that the order won’t be canceled by the matching engine in such a circumstance that not enough funds are frozen for the order.

Default:

false

stp

enum<string>

optional

Self Trade Prevention is divided into these strategies: CN, CO, CB. Not supported DC at the moment.

Allowed values:

CNCOCB

marginMode

enum<string>

optional

Margin mode: ISOLATED, CROSS, default: ISOLATED

Allowed values:

ISOLATEDCROSS

Default:

ISOLATED

price

string

optional

Required for type is 'limit' order, indicating the operating price

Example:

0.1

size

integer

optional

Choose one of size, qty, valueQty, Order size (Lot), must be a positive integer. The quantity unit of coin-swap contracts is size(lot), and other units are not supported.

qty

string

optional

Choose one of size, qty, valueQty, Order size (Base currency) must be an integer multiple of the multiplier. The unit of the quantity of coin-swap is size(lot), which is not supported

valueQty

string

optional

Choose one of size, qty, valueQty, Order size (Value), USDS-Swap correspond to USDT or USDC. The unit of the quantity of coin-swap is size(lot), which is not supported

timeInForce

enum<string>

optional

Optional for type is 'limit' order, Time in force is a special strategy used during trading, default is GTC

Allowed values:

GTCIOC

Default:

GTC

postOnly

boolean

optional

Optional for type is 'limit' order, post only flag, invalid when timeInForce is IOC. When postOnly is true, not allowed choose hidden or iceberg. The post-only flag ensures that the trader always pays the maker fee and provides liquidity to the order book. If any part of the order is going to pay taker fee, the order will be fully rejected.

Default:

false

hidden

boolean

optional

Optional for type is 'limit' order, orders not displaying in order book. When hidden chose, not allowed choose postOnly.

Default:

false

iceberg

boolean

optional

Optional for type is 'limit' order, Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.

Default:

false

visibleSize

string

optional

Optional for type is 'limit' order, The maximum visible size of an iceberg order. please place order in size (lots), The units of qty (base currency) and valueQty (value) are not supported.

Example

[
  {
    "clientOid": "5c52e11203aa677f33e493fb",
    "side": "buy",
    "symbol": "XBTUSDTM",
    "leverage": 3,
    "type": "limit",
    "remark": "order remarks",
    "reduceOnly": false,
    "marginMode": "ISOLATED",
    "price": "0.1",
    "size": 1,
    "timeInForce": "GTC"
  },
  {
    "clientOid": "5c52e11203aa677f33e493fc",
    "side": "buy",
    "symbol": "XBTUSDTM",
    "leverage": 3,
    "type": "limit",
    "remark": "order remarks",
    "reduceOnly": false,
    "marginMode": "ISOLATED",
    "price": "0.1",
    "size": 1,
    "timeInForce": "GTC"
  }
]

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api-futures.kucoin.com/api/v1/orders/multi' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "clientOid": "5c52e11203aa677f33e493fb",
        "side": "buy",
        "symbol": "XBTUSDTM",
        "leverage": 3,
        "type": "limit",
        "remark": "order remarks",
        "reduceOnly": false,
        "marginMode": "ISOLATED",
        "price": "0.1",
        "size": 1,
        "timeInForce": "GTC"
    },
    {
        "clientOid": "5c52e11203aa677f33e493fc",
        "side": "buy",
        "symbol": "XBTUSDTM",
        "leverage": 3,
        "type": "limit",
        "remark": "order remarks",
        "reduceOnly": false,
        "marginMode": "ISOLATED",
        "price": "0.1",
        "size": 1,
        "timeInForce": "GTC"
    }
]'

Responses

🟢200OK

application/json

Body

code

string

required

data

array [object {5}]

required

orderId

string

required

The unique order id generated by the trading system,which can be used later for further actions such as canceling the order.

clientOid

string

required

Unique order id created by users to identify their orders, the maximum length cannot exceed 40, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)

symbol

string

required

Symbol of the contract, Please refer to Get Symbol endpoint: symbol

code

string

required

msg

string

required

Example

{
  "code": "200000",
  "data": [
    {
      "orderId": "235919387779985408",
      "clientOid": "5c52e11203aa677f33e493fb",
      "symbol": "XBTUSDTM",
      "code": "200000",
      "msg": "success"
    },
    {
      "orderId": "235919387855482880",
      "clientOid": "5c52e11203aa677f33e493fc",
      "symbol": "XBTUSDTM",
      "code": "200000",
      "msg": "success"
    }
  ]
}

Modified at 2025-03-19 02:11:53

Add Order Test

Add Take Profit And Stop Loss Order