Get HF Filled List

This endpoint can be used to obtain a list of the latest HF transaction details. The returned results are paginated. The data is sorted in descending order according to time.

HTTP REQUEST

GET /api/v1/hf/fills

Example

GET /api/v1/hf/fills?symbol=BTC-USDT

// response
{
  "code": "200000",
  "data": {
    "items": [
      {
        "id": 2678765568,
        "symbol": "BTC-ETC",
        "tradeId": 616179312641,
        "orderId": "6306cf6e27ecbe0001e1e03a",
        "counterOrderId": "6306cf4027ecbe0001e1df4d",
        "side": "buy",
        "liquidity": "taker",
        "forceTaker": false,
        "price": "1",
        "size": "1",
        "funds": "1",
        "fee": "0.00021",
        "feeRate": "0.00021",
        "feeCurrency": "USDT",
        "stop": "",
        "tradeType": "TRADE",
        "type": "limit",
        "createdAt": 1661390702919
      }
    ],
    "lastId": 2678765568
  }
}

API KEY PERMISSIONS

This endpoint requires the General permission.

REQUEST URL

This endpoint support Spot URL

REQUEST RATE LIMIT

Spot weight：2

PARAMETERS

Param	Type	Mandatory	Description
orderId	String	No	Look up the transaction details pertaining to the order id（IforderId is specified，please ignore the other query parameters）
symbol	String	Yes	Only returns order information for the specified trading pair
side	String	No	buy（Buy） or sell（Sell）
type	String	No	Order type: limit（limit order）, market(market order)
startAt	long	No	Start time（ms），puts a restriction on the transaction(creation) time for the transaction records
endAt	long	No	End time（ms），puts a restriction on the transaction(creation) time of the transaction records
lastId	long	No	The id of the last data item from the previous batch, defaults to obtaining the latest data
limit	int	No	Default100，maximum 100

TIP

lastIdis used to filter data and paginate. If lastIdis not entered, the default is a maximum of 100 returned data items. The return results includelastId，which can be used as a query parameter to look up new data from the next page.

RESPONSES

Param	Description
id	Id of transaction detail
symbol	Trading pair
tradeId	Trade Id (numeric type, symbol latitude increment)
orderId	Order Id
counterOrderId	Counterparty order Id
side	Buy or sell
liquidity	Liquidity type: taker or maker
forceTaker	Whether or not to forcefully process as taker
price	Order price
size	Order size
funds	Turnover
fee	Service fee
feeRate	Fee rate
feeCurrency	currency used to calculate fees
type	Order type: limit or market
stop	Take Profit and Stop Loss type, currently HFT does not support the Take Profit and Stop Loss type, so it is empty
createdAt	Transaction(Creation) time
tradeType	Trade type: TRADE(Spot Trading)

Show time range

You can only obtain data from within a 3 * 24 hour time range（i.e., from now up to 3 * 24 hours ago）. If the time range limit is exceeded, the system will default to looking up data from within the 3 * 24 hour time range.

Settlement

Settlement is divided into two parts: transaction settlement and fee settlement. When matching is complete, the data is immediately updated into our data storage and the system initiates the settlement to deduct funds from the funds that are on hold.

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. On the contrary, 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 for paying 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 cancelled 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 cancelled.

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 cancelled. 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 to 1BTC at market price，the handling fee would 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