Binance Historical Downloader (`dccd.histo_dl.binance`)¶

Objects to download historical data from Binance exchange.

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

Bases: ImportDataCryptoCurrencies

Class to import crypto-currencies data from the Binance 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 'USD', which is silently coerced to 'USDT' (Binance does not support fiat; only USDT is accepted as a USD-equivalent). 'EUR' is likewise coerced to 'USDT' with a warning.
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 (e.g. 'Europe/Paris').

Attributes:

pairstr: Pair symbol, crypto + fiat.
start, endint: Timestamp to starting and ending download data.
spanint: Number of seconds between observations.
full_pathstr: Directory managed by DataStore — {path}/binance/ohlc/{pair}/{span}/.

Methods

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

FromKraken, FromCoinbase, FromBybit, FromOKX

Notes

See Binance API documentation [1] for more details on parameters.

References

[1]

https://github.com/binance-exchange/binance-official-api-docs

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 Binance for specific time interval.

Parameters:

startint or str: Timestamp of the first observation of you want as int or date format ‘yyyy-mm-dd hh:mm:ss’ as string.
endint or str: Timestamp of the last observation of you want as int or date format ‘yyyy-mm-dd hh:mm:ss’ as string.

Returns:

datapl.DataFrame: Data sorted and cleaned in a data frame.

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.

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

Exchange specifics¶

Pair format	Concatenation without separator: `'BTC'` + `'USDT'` → `'BTCUSDT'`. If fiat is `'EUR'` or `'USD'` it is silently coerced to `'USDT'` (Binance does not support fiat; only USDT is accepted).
Candles per request	1 000 (endpoint: `GET /api/v3/klines`).
Minimum span	60 seconds (1 minute).
Trade history	Full historical depth via `GET /api/v3/aggTrades` (paginated by trade ID).
Order book depth	Snapshot at depth 5, 10, 20, 50, 100, 500, 1 000, or 5 000 price levels per side.
Authentication	Not required for public data.

Quick example¶

from dccd.histo_dl import FromBinance

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

# Download 2024 hourly candles
obj.import_data(start='2024-01-01 00:00:00', end='2024-12-31 00:00:00')
obj.save(form='parquet')

# Incremental update
obj.import_data(start='last', end='now').save(form='parquet')

# Trade history
obj.import_trades(start='2024-01-01 00:00:00', end='2024-03-31 00:00:00')
obj.save_trades(form='parquet')

# Order book snapshot (20 levels per side)
obj.import_orderbook(depth=20)
obj.save_orderbook(form='parquet')

Binance Historical Downloader (dccd.histo_dl.binance)¶

Exchange specifics¶

Quick example¶

Binance Historical Downloader (`dccd.histo_dl.binance`)¶