Retrieve Historical Klines Data (Implementation)

Retrieves historical candlestick (klines) data for a single trading pair from the KuCoin API asynchronously, segmenting requests to handle the 1500-candle limit per request.

Usage

get_klines_impl(
  base_url = get_base_url(),
  symbol = "BTC-USDT",
  freq = "15min",
  from = lubridate::now() - 24 * 3600,
  to = lubridate::now(),
  concurrent = TRUE,
  delay_ms = 0,
  retries = 3,
  verbose = FALSE,
  .__coro_env_parent__ = <environment>
)

Arguments

base_url

Character string; base URL for the KuCoin API. Defaults to get_base_url().

symbol

Character string; trading pair (e.g., "BTC-USDT"). Defaults to "BTC-USDT".

freq

Character string; candlestick interval (e.g., "15min"). Allowed values: "1min", "3min", "5min", "15min", "30min", "1hour", "2hour", "4hour", "6hour", "8hour", "12hour", "1day", "1week", "1month". Defaults to "15min".

from

POSIXct object; start time for data retrieval. Defaults to 24 hours before now.

to

POSIXct object; end time for data retrieval. Defaults to now.

concurrent

Logical; whether to fetch segments concurrently (default TRUE). Caution: May trigger rate limits.

delay_ms

Numeric; delay in milliseconds before each request (default 0).

retries

Integer; number of retry attempts per segment request (default 3).

verbose

Logical; whether to print progress messages (default FALSE).

Value

Promise resolving to a data.table containing:

• datetime (POSIXct): Converted timestamp.

• timestamp (numeric): Raw timestamp in seconds.

• open (numeric): Opening price.

• close (numeric): Closing price.

• high (numeric): Highest price in the interval.

• low (numeric): Lowest price in the interval.

• volume (numeric): Trading volume.

• turnover (numeric): Trading turnover.

Details

Workflow Overview

1. Input Validation: Converts from and to to POSIXct and ensures from is earlier than to.

2. Frequency Conversion: Translates freq to seconds using frequency_to_seconds().

3. Segmentation: Splits the time range into segments with split_time_range_by_candles(), each up to 1500 candles.

4. Segment Fetching: Creates promises for each segment via fetch_klines_segment().

5. Execution Mode: Fetches segments concurrently with promises::promise_all() if concurrent = TRUE, or sequentially otherwise.

6. Aggregation: Combines segment results with data.table::rbindlist(), removes duplicates by timestamp, and orders by datetime.

API Endpoint

GET https://api.kucoin.com/api/v1/market/candles (via fetch_klines_segment())

Usage

Utilised to fetch and aggregate historical klines data for analysis, supporting both concurrent and sequential retrieval.

Official Documentation

KuCoin Get Klines

Examples

if (FALSE) { # \dontrun{
main_async <- coro::async(function() {
  dt <- await(get_klines_impl(symbol = "BTC-USDT", freq = "15min"))
  print(dt)
  dt_seq <- await(get_klines_impl(
    symbol = "BTC-USDT",
    freq = "15min",
    concurrent = FALSE,
    delay_ms = 200
  ))
  print(dt_seq)
})
main_async()
while (!later::loop_empty()) later::run_now()
} # }