OKX Historical Downloader (`dccd.histo_dl.okx`)¶

Objects to download historical data from OKX exchange.

class FromOKX(path, crypto, span, fiat='USDT', form='xlsx', tz='local')[source]¶

Bases: ImportDataCryptoCurrencies

Class to import crypto-currencies data from the OKX exchange.

Parameters:

pathstr: Root directory for data files.
cryptostr: Crypto-currency symbol, e.g. 'BTC'.
spanint or str: Candle interval in seconds (minimum 60) or a label such as 'hourly' or '1h'.
fiatstr, optional: Quote currency. Default is 'USDT'. The pair is formatted with a hyphen separator (e.g. 'BTC' + 'USDT' → 'BTC-USDT').
formstr, optional: Legacy parameter — ignored. Storage is always Parquet via DataStore.
tzstr, optional: Timezone for date parsing: 'local' (default), 'UTC', or any IANA timezone name.

Attributes:

pairstr: Instrument ID (e.g. ‘BTC-USDT’).
start, endint: Timestamps bounding the download.
spanint: Seconds between observations.
full_pathstr: Directory managed by DataStore — {path}/okx/ohlc/{pair}/{span}/.

Methods

`import_data`([start, end])	Download data from OKX for a specific time interval.
`save`([form, by_period])	Save `df` to disk via `DataStore`.
`get_data`([format])	Return the downloaded data.
`import_trades`([start, end])	Fetch individual trades for a time window.
`save_trades`([form, by_period])	Save `trades_df` via `DataStore`.
`import_orderbook`([depth])	Fetch the current order book snapshot at a given depth.
`save_orderbook`([form])	Save `orderbook_df` via `DataStore`.

See also

FromBinance, FromCoinbase, FromKraken, FromBybit

Notes

Uses the OKX v5 REST API [1].

References

[1]

https://www.okx.com/docs-v5/en/#rest-api-market-data-get-candlesticks

get_data(format='polars')¶

Return the downloaded data.

Parameters:

format{‘polars’, ‘pandas’}, optional: Output format. Default is ‘polars’.

Returns:

pl.DataFrame: Current data in the requested format.

import_data(start='last', end='now')[source]¶

Download data from OKX for a specific time interval.

Parameters:

startint or str: Timestamp of the first observation or date ‘yyyy-mm-dd hh:mm:ss’.
endint or str: Timestamp of the last observation or date ‘yyyy-mm-dd hh:mm:ss’.

Returns:

datapl.DataFrame: OHLCV data sorted and cleaned.

import_orderbook(depth=50)¶

Fetch the current order book snapshot at a given depth.

Downloads the bid/ask ladder from the exchange REST API, validates each level, and stores the result in orderbook_df. Use save_orderbook to persist to disk.

Parameters:

depthint, optional: Number of price levels to fetch per side (bids + asks), default 50. Maximum varies by exchange.

Returns:

ImportDataCryptoCurrencies: Returns self for method chaining.

Notes

Order book REST endpoints return a current snapshot only. Historical order book data is not available via public APIs.

import_trades(start=0, end='now')¶

Fetch individual trades for a time window.

Downloads executed trades from the exchange REST API, validates each record, and stores the result in trades_df. Use save_trades to persist to disk.

Parameters:

startint or str, optional: Start of the time window. Accepts a Unix timestamp (int), a date string 'yyyy-mm-dd hh:mm:ss', or 0 (default, meaning “as far back as the API allows”).
endint or str, optional: End of the time window. 'now' (default) resolves to the current UTC time. Accepts a Unix timestamp or date string.

Returns:

ImportDataCryptoCurrencies: Returns self for method chaining.

Notes

Exchanges vary in how much history they expose:

Binance and Kraken provide full paginated history.
OKX exposes several months of history via cursor pagination.
Bybit returns the ~1 000 most recent trades regardless of start/end.
Coinbase returns up to 100 recent trades (cursor-based, no deep history).

save(form='parquet', by_period='Y')¶

Save df to disk via DataStore.

Data is always written as Parquet, grouped annually. The form and by_period parameters are accepted for backward compatibility but ignored — storage format and period granularity are managed by DataStore.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.
by_periodstr, optional: Ignored. Kept for backward-compatibility.

save_orderbook(form='parquet')¶

Save orderbook_df via DataStore.

The snapshot is timestamped with the current UTC time and written into the daily orderbook file. The form parameter is accepted for backward compatibility but ignored.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.

Returns:

ImportDataCryptoCurrencies: Returns self to allow method chaining.

save_trades(form='parquet', by_period='D')¶

Save trades_df via DataStore.

Trades are grouped by calendar day and written as Parquet. The form and by_period parameters are accepted for backward compatibility but ignored.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.
by_periodstr, optional: Ignored. Kept for backward-compatibility.

Returns:

ImportDataCryptoCurrencies: Returns self to allow method chaining.

FromOKX downloads OHLCV candles, trade history, and order book snapshots from the OKX public REST API. No authentication is required.

Exchange specifics¶

Pair format	Hyphen separator with instrument ID format: `'BTC'` + `'USDT'` → `'BTC-USDT'`.
OHLCV endpoint	Uses `GET /api/v5/market/history-candles` — not `/market/candles` which only returns the last ~24 h of 1-minute bars.
Candles per request
Minimum span	60 seconds (1 minute).
Trade history	Full historical depth via `GET /api/v5/market/trades`.
Order book depth	Snapshot at 1, 5, 400, or 4 000 levels per side.
Authentication	Not required for public data.

Quick example¶

from dccd.histo_dl import FromOKX

obj = FromOKX('/data/crypto/', 'BTC', span=3600, fiat='USDT')

# Full OHLCV history
obj.import_data(start='2024-01-01 00:00:00', end='2024-12-31 00:00:00')
obj.save(form='parquet')

# Trade history (full pagination)
obj.import_trades(start='2024-01-01 00:00:00', end='2024-06-30 00:00:00')
obj.save_trades(form='parquet')

OKX Historical Downloader (dccd.histo_dl.okx)¶

Exchange specifics¶

Quick example¶

OKX Historical Downloader (`dccd.histo_dl.okx`)¶