FromBinance

Defined in dccd.histo_dl.binance

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

static format_pair(crypto, fiat)[source]

Return the Binance pair symbol for crypto and fiat.

Parameters:
crypto, fiatstr

Asset symbols (e.g. 'BTC', 'USDT').

Returns:
str

Concatenated pair (e.g. 'BTCUSDT').

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.