Orders

Place Order

There are two types of orders: Limit order (limit): Specify the price and quantity to trade. Market order (market): Specify funds or quantity to trade.

Orders can only be placed if your Spot/Margin Account has sufficient funds. Once an order is placed, your account funds will be put on hold for the duration of the order. Holds are put on hold depends on the order type and parameters specified. See the Holds details below.

TIP

Placing an order will enable price protection. When the price of the limit order is outside the threshold range, the price protection mechanism will be triggered, causing the order to fail.

Please note that the system will frozen the fees from the orders that entered the order book in advance. Read List Fills to learn more.

Before placing an order, please read Get Symbol List to understand the requirements for the quantity parameters for each trading pair.

Do not include extra spaces in JSON strings.

Place Order Limit

For a single account, the maximum number of active orders is 2000, with a maximum of 200 active orders per trading pair (including stop orders).

HTTP REQUEST

POST /api/v1/orders

Example

POST /api/v1/orders

{
  "orderId": "5bd6e9286d99522a52e458de"
}

API KEY PERMISSIONS

This endpoint requires the Spot Trading or Margin Trading permission.

REQUEST URL

This endpoint support Spot URL

REQUEST RATE LIMIT

Spot weight：limit 2, market 2

PARAMETERS

Public order placement request parameters

Param	Type	Mandatory	Description
clientOid	String	Yes	clientOid, the unique identifier created by the client, use of UUID, with a maximum length of 128 bits.
side	String	Yes	buy or sell
symbol	String	Yes	symbol, e.g. ETH-BTC
type	String	No	limit or market (default is limit)
remark	String	No	remark, length cannot exceed 50 characters (ASCII)
stp	String	No	self trade prevention, CN, CO, CB or DC
tradeType	String	No	The type of trading : TRADE（Spot Trade）, MARGIN_TRADE (Margin Trade). Default is TRADE. Note: To improve the system performance and to accelerate order placing and processing, KuCoin has added a new interface for order placing of margin. For traders still using the current interface, please move to the new one as soon as possible. The current one will no longer accept margin orders by May 1st, 2021 (UTC). At the time, KuCoin will notify users via the announcement, please pay attention to it.

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)

• When placing a market order, the size or funds must be set.

RESPONSES

Param	Description
orderId	An order Id is returned once an order is successfully placed.

Terms

Trading pair (Symbol)

The symbol must match a valid trading symbol.

Client Order Id(clientOid)

The ClientOid field is a unique ID created by the user（we recommend using a UUID）, and can only contain numbers, letters, underscores （_）, and hyphens （-）. This field is returned when order information is obtained. You can use clientOid to tag your orders. ClientOid is different from the order ID created by the service provider. Please do not initiate requests using the same clientOid. The maximum length for the ClientOid is 40 characters.

Please remember the orderId created by the service provider, it used to check for updates in order status.

Order Type (type):

The type of order you specify when you place your order determines whether or not you need to request other parameters and also affects the execution of the matching engine.

When placing a limit order, you must specify a price and size. The system will try to match the order according to market price or a price better than market price. If the order cannot be immediately matched, it will stay in the order book until it is matched or the user cancels.

Unlike limit orders, the price for market orders fluctuates with market prices. When placing a market order, you do not need to specify a price, you only need to specify a quantity. Market orders are filled immediately and will not enter the order book. All market orders are takers and a taker fee will be charged.

Trade Type (tradeType)

The platform currently supports spot （TRADE） asset trading orders, the system will default to freezing funds in your trading account according to spot trading rules.

Price (Price)

When placing a limit order, the price must be based on priceIncrement for the trading pair. The price increment (priceIncrement) is the price precision for the trading pair. For example, for the BTC-USDT trading pair, the priceIncrement is 0.00001000. So the price for your orders cannot be less than 0.00001000 and must be a multiple of priceIncrement. Otherwise, the order will return an invalid priceIncrement error.

Size (Size)

When placing a limit order, size refers to the amount of trading targets (the asset name written in front) for the trading pair. Teh Size must be based on the baseIncrement of the trading pair. The baseIncrement represents the precision for the trading pair. The size of an order must be a positive-integer multiple of baseIncrement and must be between baseMinSize and baseMaxSize.

Funds (Funds)

When placing a market order, the funds field refers to the funds for the priced asset (the asset name written latter) of the trading pair. The funds must be based on the quoteIncrement of the trading pair. The quoteIncrement represents the precision of the trading pair. The funds value for an order must be a multiple of quoteIncrement and must be between quoteMinSize and quoteMaxSize.

Time In Force (TimeInForce)

Time in force is a special strategy used during trading. It is used to specify how long an order shall remain active before being executed or expiring. There are four types of TimeInForce:

Abbreviation	Full name	Description
GTC	Good Till Canceled	Expires only when cancelled
GTT	Good Till Time	Expires at a specified time
IOC	Immediate Or Cancel	Execute the portions that can be executed immediately and cancel the rest; this does not enter the order book.
FOK	Fill Or Kill	Cancel if the order cannot be completely filled.

• Note: order fills include self-fills. Market order does not support the TimeInForce strategy

Post Only (PostOnly)

PostOnly is just a label. If an order can be immediately filled, then it is cancelled.

• When the user places a postOnly order, if the order encounters an iceberg order or hidden order after entering the matching engine, the order can be filled immediately. The postOnly order will charge maker fees and the iceberg order and hidden order will charge taker fees.

Hidden Orders and Iceberg Orders (Hidden & Iceberg)

Hidden orders and iceberg orders can be set in advanced settings (iceberg orders are a special type of hidden orders). When placing limit orders or stop limit orders, you can choose to execute according to hidden orders or iceberg orders.

Hidden orders are not shown in order books.

Unlike hidden orders, iceberg orders are divided into visible and hidden portions. When engaging in iceberg orders, visible order sizes must be set. The minimum visible size for an iceberg order is 1/20 of the total order size.

When matching, the visible portions of iceberg orders are matched first. Once the visible portions are fully matched, hidden portions will emerge. This will continue until the order is fully filled.

Note:

• The system will charge taker fees for hidden orders and iceberg orders.
• If you simultaneously set iceberg orders and hidden orders, your order will default to an iceberg order for execution.

Hold (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 cancelled.

Self Trade Prevention (SelfTradePrevention)

Self trade prevention can be set in advanced settings, which will prevent self trades from occurring in your orders. If you do not set STP when placing an order, your order could be filled with another one of your orders. Market orders currently do not support DC strategies.

Market orders currently do not support DC. When timeInForce is FOK, stp will specify CN.

Abbreviation	Full name	Description
DC	Decrease and Cancel	Cancel the order with smaller size and change the order with larger size to the difference between old and new.
CO	Cancel old	Cancel the old order.
CN	Cancel new	Cancel the new order.
CB	Cancel both	Cancel both sides

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.

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 cancelled;
• 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.