KUCOIN API
Terms Definitions
Order Lifecycle
Valid orders sent to the matching engine are confirmed immediately and are in the received state.
If an order executes against another order immediately, the order is considered done.
An order can execute in part or whole. Any part of the order not filled immediately will be considered open.
Orders will stay in the open state until canceled or subsequently filled by new orders. Orders that are no longer eligible for matching (filled or canceled) are in the done state.
Handling Fees
Orders on the KuCoin platform are divided into two types: Taker and Maker. Taker orders can be filled with existing orders in the order book. Conversely, Maker orders will stay in the order book and await matching. Taker orders decrease market liquidity and therefore charge a taker fee. Maker orders increase market liquidity and therefore only charge a lower handling fee or may even pay out rewards. Note: Market orders, iceberg orders, and hidden orders all charge taker fees.
When an order is placed, the system puts a hold on a portion of the funds in your account to pay the taker fee. Parameter values in the liquidity field determine whether taker fees or maker fees will be charged for the order.
If your order is a limit order, when the order is placed it will immediately be matched in the matching engine and we will charge a taker fee. If your order is not immediately matched or is only partially matched, the remaining portions will enter the order book. Maker fees will be charged for orders that have entered the order book before they are canceled or filled.
After entering the matching stage, matching will be conducted with counterparty orders. When the remaining amount for the order is 0, the transaction is complete. If the remaining funds are not enough to purchase the minimum amount (0.00000001), the order is canceled.
If your order is filled as a maker, we will refund the remaining amount of withheld taker fees.
Please note:
- When you create a hidden/iceberg order, even if it is not immediately matched by the matching engine and is filled as post only, a taker fee will still be charged.
- Maker fees will be charged for post only orders. If the order is immediately matched with existing orders (with the exception of iceberg/hidden orders) on the market after order placement, then the order will be canceled. If a post only order is immediately filled with iceberg/hidden orders, a maker fee will be charged for the post only order.
For example:
Using BTC/USDT as an example, if you want 1BTC at market price, the handling fee will be 0.1%, with the market order book data as follows:
| Price(USDT) | Size(BTC) | Side |
|---|---|---|
| 4200.00 | 0.18412309 | sell |
| 4015.60 | 0.56849308 | sell |
| 4011.32 | 0.24738383 | sell |
| 3995.64 | 0.84738383 | buy |
| 3988.60 | 0.20484000 | buy |
| 3983.85 | 1.37584908 | buy |
When you place a buy market order, it will be filled immediately, and the transaction detailed will show 3 transactions, as shown below:
| Price(USDT) | Size(BTC) | Fee(BTC) |
|---|---|---|
| 4011.32 | 0.24738383 | 0.00024738 |
| 4015.60 | 0.56849308 | 0.00056849 |
| 4200.00 | 0.18312409 | 0.00018312 |
Zero Freeze Cancel Order
A special type of order cancellation; the specific reasons are as follows, for example:
If the current long position is 10, the account has no additional funds and no short pending orders.
Add 5 short orders, and no additional freezing of margin will be made.
Add 10 short orders (close the position), and the margin will not be frozen.
Add 11 short orders (close the position and open the position in the opposite direction), and the system will detect that order.
If the current long position is 10, there are no additional funds in the account, and there is a short pending order, then this short order will also be considered as "closing" (that is, it occupies the amount frozen by 0), if all positions are to be closed at this time. If the system finds that part of the liquidation is "non-zero frozen", it will cancel the order. That is to say, the root cause comes from the previous pending order.
The solution to this problem is to check the position before placing an order. The details are as follows:
If the position is closed and there is no reverse pending order. Disregard; in general, you should not encounter any problems.
If it is a reversal to open a position: It is necessary to ensure that the account has sufficient margin to place an order.
If it is to close the position, there is a reverse pending order. It is necessary to ensure that the number of reverse pending orders < = available funds - the number of liquidated positions.
If the account has enough money (regardless of fund utilization): Set forceHold to true when placing an order, and the problem will not be encountered.
In addition, we will optimize the logic of the system in futures versions to make the number of frozen positions for reverse opening more reasonable.