Orders

Place Order

//Request
{
  "clientOid": "5c52e11203aa677f33e493fb",
  "reduceOnly": false,
  "closeOrder": false,
  "forceHold": false,
  "hidden": false,
  "iceberg": false,
  "leverage": 20,
  "postOnly": false,
  "price": 8000,
  "remark": "remark",
  "side": "buy",
  "size": 20,
  "stop": "",
  "stopPrice": 0,
  "stopPriceType": "",
  "symbol": "XBTUSDM",
  "timeInForce": "",
  "type": "limit",
  "visibleSize": 0
}

//Response
{
  "code": "200000",
  "data": {
    "orderId": "5bd6e9286d99522a52e458de"
  }
}

You can place two 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.

Please be noted that the system would hold the fees from the orders entered the orderbook in advance. Read Get Fills to learn more.

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.

HTTP REQUEST

POST /api/v1/orders

Example

POST /api/v1/orders

API KEY PERMISSIONS

This endpoint requires the Futures Trading permission.

REQUEST URL

This endpoint support Futures URL

REQUEST RATE LIMIT

Futures weight：limit 2, market 2

PARAMETERS

Public order placement request parameters

Param	Type	Mandatory	Description
clientOid	String	Yes	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(-)
side	String	Yes	buy or sell
symbol	String	Yes	a valid contract code. e.g. XBTUSDM
leverage	String	Yes	Used to calculate the margin to be frozen for the order. If you are to close the position, this parameter is not required.
type	String	No	Either limit or market,The default type is limit
remark	String	No	remark for the order, length cannot exceed 100 utf8 characters
stop	String	No	Either down or up. Requires stopPrice and stopPriceType to be defined
stopPriceType	String	No	Either TP, IP or MP, Need to be defined if stop is specified.
stopPrice	String	No	Need to be defined if stop is specified.
reduceOnly	boolean	No	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.
closeOrder	boolean	No	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.
forceHold	boolean	No	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.
stp	String	No	self trade prevention, CN, CO, CB. Not supported DC at the moment

Additional Request Parameters Required by limit Orders

Param	Type	Mandatory	Description
price	String	Yes	Limit price
size	Integer	Yes	Order size. Must be a positive number
timeInForce	String	No	GTC, IOC(default is GTC)
postOnly	boolean	No	Post only flag, invalid when timeInForce is IOC. When postOnly chose, 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.
hidden	boolean	No	Orders not displaying in order book. When hidden chose, not allowed choose postOnly.
iceberg	boolean	No	Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.
visibleSize	Integer	No	The maximum visible size of an iceberg order

Additional request parameters required by market orders

Param	Type	Mandatory	Description
size	Integer	No	amount of contract to buy or sell

RESPONSES

Param	Description
orderId	Order ID.

Terms

CLIENT ORDER ID

Generated by yourself, the optional clientOid field must be a unique id (e.g UUID). Only numbers, characters, underline(_) and separator(-) are allowed. The value will be returned in order detail. You can use this field to identify your orders via the public feed. The client_oid is different from the server-assigned order id. Please do not send a repeated client_oid. The length of the client_oid cannot exceed 40 characters.

You should record the server-assigned order_id as it will be used for future query order status.

TYPE

The order type you specify may decide whether other optional parameters are required, as well as how your order will be executed by the matching engine. If order type is not specified, the order will be a limit order by default.

Price and size are required to be specified for a limit order. The order will be filled at the price specified or better, depending on the market condition. If a limit order cannot be filled immediately, it will be outstanding in the open order book until matched by another order, or canceled by the user.

A market order differs from a limit order in that the execution price is not guaranteed. Market order, however, provides a way to buy or sell specific size of contract without having to specify the price. Market orders will be executed immediately, and no orders will enter the open order book afterwards. Market orders are always considered takers and incur taker fees.

STOP ORDERS

A stop order is an order to buy or sell at the market or pre-specified limit price once the contact has traded at or through a pre-specified stopPrice. There are two types of stop orders, down and up.

Stop Order Types

down: Triggers when the price reaches or goes below the stopPrice.

up: Triggers when the price reaches or goes above the stopPrice.

stopPriceType: There are three types of stop prices for contract, including:

1. TP for trade price, The last trade price is the last price at which an order was filled. This price can be found in the latest match message.
2. MP for mark price, The mark price can be obtained through relevant OPEN API for index services.
3. IP for index price, The index price can be obtained through relevant OPEN API for index services.

Note that when triggered, stop orders will be executed as either market or limit orders, depending on the pre-specified type. When placing a stop order, the system will not pre-freeze the funds in your account. Do note that when triggered, a stop order may be canceled if the available balance is not enough.

PRICE

The price specified must be a multiple number of the contract tickSize, otherwise the system will report an error when you place the order. The tick size is the smallest price increment in which the prices are quoted. A valid price shall not be higher than the maxPrice in the contract specification. KuCoin Futures implements IEPR(Immediately Executable Price Range) rule, in which the price of a buy order cannot be higher than 1.05 * mark price, and the price of a sell order cannot be lower than 0.95 * mark price.

Price field is not required for market orders.

Trade Amount

The trade amount indicates the amount of contract to buy or sell, and contract uses the base currency or lot as the trading unit. The trade amount must be no less than 1 lot for the contract and no larger than the maxOrderQty. It should be a multiple number of the lot, or the system will report an error when you place the order. E.g. 1 lot of XBTUSDTM is 0.001 Bitcoin, while 1 lot of XBTUSDM is 1 USD.

TIME IN FORCE

time in force is a special strategy used in trading, which is used to set the effective time of the order before it is matched or cancelled. There are two types:

GTC Good Till Canceled: order remains open on the order book until canceled. This is the default type if the field is left empty.

IOC Immediate Or Cancel: being matched or not, the remaining size of the order will be instantly canceled instead of entering the order book.

Note that self trades belong to match as well.

HIDDEN AND ICEBERG

The Hidden and iceberg Orders are two options in advanced settings (note: the iceberg order is a special form of the hidden order). You may select “Hidden” or “Iceberg” when placing a limit or stop limit order.

A hidden order will enter but not display on the orderbook.

Different from the hidden order, an iceberg order is divided into visible portion and invisible portion. When placing an iceberg order, you need to set the visible size. The minimum visible size is 1/20 of the order size. The minimum visible size shall be greater than the minimum order size, or an error will occur.

In a matching event, the visible portion of an iceberg order will be executed first, and another visible portion will pop up until the order is fully filled.

Note:

1. The system will charge taker fees for Hidden and iceberg Orders.
2. If both "Iceberg" and "Hidden" are selected, your order will be filled as an iceberg Order by default.

HOLDS

When placing an order, the system will freeze certain amount of funds in your account for position margin and transaction fees based on the order price and quantity. If not, the order can only be one to reduce the position. If the total amount of these orders exceeds the position size, the system will cancel the extra no-fund-frozen orders to ensure they won’t be executed.

Actual fees are determined when the order is executed. If you cancel a partially filled or unfilled order, any remaining funds will be released from hold and become available.

Different from when an order reduces the position size, certain amount of funds need to be frozen when an order increases the position size. No funds need to be frozen when closeOrder is set to TRUE, or when reduceOnly is set to TRUE.

The execution of the order will incur transaction fees. If a partially filled or unfilled order is canceled, the system will unfreeze the remained frozen funds in your account.

Order Lifecycle (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 cancelled) 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.

RESPONSE

A successful order will be assigned an order id. A successful order is defined as one that has been accepted by the matching engine.

Open orders will remain open until they are either filled or canceled.