Get Trade History (Implementation) — get_trade_history

Retrieves the most recent 100 trade records for a specified trading symbol from the KuCoin API asynchronously.

Retrieves a list of the latest spot transaction details (fills) for a specified symbol or orderId from the KuCoin Spot trading system asynchronously. This function returns a data.table with detailed information about each fill, sorted by the latest update time in descending order.

Usage

get_trade_history_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  symbol = NULL,
  orderId = NULL,
  side = NULL,
  type = NULL,
  lastId = NULL,
  limit = 20,
  startAt = NULL,
  endAt = NULL,
  .__coro_env_parent__ = <environment>
)

get_trade_history_impl(
  keys = get_api_keys(),
  base_url = get_base_url(),
  symbol = NULL,
  orderId = NULL,
  side = NULL,
  type = NULL,
  lastId = NULL,
  limit = 20,
  startAt = NULL,
  endAt = NULL,
  .__coro_env_parent__ = <environment>
)

Arguments

keys: List; API configuration parameters from get_api_keys(). Defaults to get_api_keys().
base_url: Character string; base URL for the KuCoin API. Defaults to get_base_url().
symbol: Character string; the trading pair symbol (e.g., "BTC-USDT"). Required if orderId is not provided.
orderId: Character string; the unique order ID. If provided, other parameters are ignored except for pagination and time filters.
side: Character string; optional filter for order side: "buy" or "sell".
type: Character string; optional filter for order type: "limit" or "market".
lastId: Integer; optional ID of the last fill for pagination.
limit: Integer; number of fills to return per request (1–100, default 20).
startAt: Integer; optional start time in milliseconds.
endAt: Integer; optional end time in milliseconds.

Value

Promise resolving to a data.table containing:

sequence (character): Trade sequence number.
price (character): Filled price.
size (character): Filled amount.
side (character): Trade side ("buy" or "sell").
time (integer): Trade timestamp in nanoseconds.
timestamp (POSIXct): Converted trade timestamp in UTC.

Promise resolving to a data.table with columns corresponding to the fill fields, including:

id (integer): Fill ID.
orderId (character): Order ID.
counterOrderId (character): Counterparty order ID.
tradeId (integer): Trade ID.
symbol (character): Trading pair.
side (character): "buy" or "sell".
liquidity (character): "taker" or "maker".
type (character): "limit" or "market".
forceTaker (logical): Whether forced to take liquidity.
price (character): Fill price.
size (character): Fill size.
funds (character): Funds involved.
fee (character): Handling fees.
feeRate (character): Fee rate.
feeCurrency (character): Fee currency.
stop (character): Stop type.
tradeType (character): Trade type.
taxRate (character): Tax rate.
tax (character): Tax amount.
createdAt (integer): Fill timestamp (milliseconds).
createdAtDatetime (POSIXct): Fill time in UTC.

Details

Workflow Overview

Query Construction: Builds a query string with the symbol parameter using build_query().
URL Assembly: Combines base_url, /api/v1/market/histories, and the query string.
HTTP Request: Sends a GET request with a 10-second timeout via httr::GET().
Response Processing: Validates the response with process_kucoin_response() and extracts the "data" field.
Data Conversion: Converts "data" to a data.table, adding a timestamp column via time_convert_from_kucoin().

API Endpoint

GET https://api.kucoin.com/api/v1/market/histories

Usage

Utilised to fetch recent trade history for a trading symbol, useful for tracking market activity.

Official Documentation

KuCoin Get Trade History

Description

This endpoint fetches the latest transaction details (fills) for a given trading pair or specific order. The data is sorted in descending order based on the update time of the order. If orderId is provided, it overrides other query parameters except for lastId, limit, startAt, and endAt.

Workflow

Parameter Validation: Ensures symbol is a valid trading pair if orderId is not provided. Validates optional parameters.
Request Construction: Builds the endpoint URL with query parameters.
Authentication: Generates private API headers using build_headers() with the GET method and endpoint.
API Request: Sends a GET request to the KuCoin API with a 3-second timeout.
Response Processing: Parses the response, converts the items array to a data.table, and adds a createdAtDatetime column.

API Details

Endpoint: GET https://api.kucoin.com/api/v1/hf/fills
Domain: Spot
API Channel: Private
API Permission: General
Rate Limit Pool: Spot
Rate Limit Weight: 2
SDK Service: Spot
SDK Sub-Service: Order
SDK Method Name: getTradeHistory
Official Documentation: KuCoin Get Trade History

Request

Query Parameters

symbol: String (required if orderId is not provided) - The trading pair symbol (e.g., "BTC-USDT").
orderId: String (optional) - The unique order ID. If provided, other parameters (except lastId, limit, startAt, endAt) are ignored.
side: Enum (optional) - Order side: "buy" or "sell".
type: Enum (optional) - Order type: "limit" or "market".
lastId: Integer (optional) - The ID of the last fill from the previous batch for pagination.
limit: Integer (optional) - Number of fills per page (1 to 100, default 20).
startAt: Integer (optional) - Start time in milliseconds.
endAt: Integer (optional) - End time in milliseconds.

Example Request

curl --location --request GET 'https://api.kucoin.com/api/v1/hf/fills?symbol=BTC-USDT&limit=100&startAt=1728663338000&endAt=1728692138000'

Response

HTTP Code: 200

Content Type: application/json

Data Schema

code: String (required) - Response code ("200000" indicates success).
data: Object (required) - Contains:
- lastId: Integer (required) - The ID of the last fill in the current batch.
- items: Array of objects (required) - List of fill details, each with:
  - id: Integer - Fill ID.
  - orderId: String - Order ID.
  - counterOrderId: String - Counterparty order ID.
  - tradeId: Integer - Trade ID.
  - symbol: String - Trading pair.
  - side: Enum - "buy" or "sell".
  - liquidity: Enum - "taker" or "maker".
  - type: Enum - "limit" or "market".
  - forceTaker: Boolean - Whether the order was forced to take liquidity.
  - price: String - Fill price.
  - size: String - Fill size.
  - funds: String - Funds involved in the fill.
  - fee: String - Handling fees.
  - feeRate: String - Fee rate.
  - feeCurrency: String - Fee currency.
  - stop: String - Stop type (currently empty for HFT).
  - tradeType: String - Trade type.
  - taxRate: String - Tax rate.
  - tax: String - Tax amount.
  - createdAt: Integer - Fill timestamp in milliseconds.

JSON Response Example

{
  "code": "200000",
  "data": {
    "items": [
      {
        "id": 19814995255305,
        "orderId": "6717422bd51c29000775ea03",
        "counterOrderId": "67174228135f9e000709da8c",
        "tradeId": 11029373945659392,
        "symbol": "BTC-USDT",
        "side": "buy",
        "liquidity": "taker",
        "type": "limit",
        "forceTaker": false,
        "price": "67717.6",
        "size": "0.00001",
        "funds": "0.677176",
        "fee": "0.000677176",
        "feeRate": "0.001",
        "feeCurrency": "USDT",
        "stop": "",
        "tradeType": "TRADE",
        "taxRate": "0",
        "tax": "0",
        "createdAt": 1729577515473
      }
    ],
    "lastId": 19814995255305
  }
}

Examples

if (FALSE) { # \dontrun{
main_async <- coro::async(function() {
  trades <- await(get_trade_history_impl(symbol = "BTC-USDT"))
  print(trades)
})
main_async()
while (!later::loop_empty()) later::run_now()
} # }
if (FALSE) { # \dontrun{
library(coro)
library(data.table)

main_async <- coro::async(function() {
  # Retrieve trade history for BTC-USDT
  trade_history <- await(get_trade_history_impl(
    symbol = "BTC-USDT",
    limit = 50
  ))
  print(trade_history)
})

# Run the async function
main_async()
while (!later::loop_empty()) later::run_now()
} # }