Bybit Historical Downloader (`dccd.histo_dl.bybit`)¶

Objects to download historical data from Bybit exchange.

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

Bases: ImportDataCryptoCurrencies

Class to import crypto-currencies data from the Bybit 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 formed by concatenation (e.g. 'BTC' + 'USDT' → 'BTCUSDT').
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: Pair symbol (e.g. ‘BTCUSDT’).
start, endint: Timestamps bounding the download.
spanint: Seconds between observations.
full_pathstr: Directory managed by DataStore — {path}/bybit/ohlc/{pair}/{span}/.

Methods

`import_data`([start, end])	Download data from Bybit 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, FromOKX

Notes

Uses the Bybit v5 REST API [1].

References

[1]

https://bybit-exchange.github.io/docs/v5/market/kline

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 Bybit 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.

FromBybit downloads OHLCV candles, recent trades, and order book snapshots from the Bybit v5 public REST API. No authentication is required.

Exchange specifics¶

Pair format	Concatenation without separator: `'BTC'` + `'USDT'` → `'BTCUSDT'`.
Candles per request	1 000 (endpoint: `GET /v5/market/kline`).
Minimum span	60 seconds (1 minute).
Trade history	Recent trades only — up to the last 1 000 trades. The Bybit public API does not support deep historical pagination.
Order book depth	Snapshot at 1–200 levels per side (spot category).
Authentication	Not required for public data.

Quick example¶

from dccd.histo_dl import FromBybit

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

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

# Only recent trades are available (≤ 1 000)
obj.import_trades(start='last', end='now')
obj.save_trades(form='parquet')

Bybit Historical Downloader (dccd.histo_dl.bybit)¶

Exchange specifics¶

Quick example¶

Bybit Historical Downloader (`dccd.histo_dl.bybit`)¶