data.sources.binance

data.sources.binance

Binance futures market data source.

Downloads daily tick-level trade dumps from data.binance.vision and caches them locally as parquet. OHLC bars are aggregated from trades.

ohlc = q.data.sources.binance.read("BTCUSDT", "2025-01-01", "2025-01-07", "1h")

Functions

Name Description
fetch_trades Fetch trades for a date range (inclusive), concatenated.
fetch_trades_day Fetch all trades for symbol on a single day (cached as parquet).
read Fetch OHLCV bars aggregated from tick trades.

fetch_trades

data.sources.binance.fetch_trades(
    symbol,
    start_date,
    end_date,
    download_dir='data',
    cache_dir=DEFAULT_CACHE_DIR,
)

Fetch trades for a date range (inclusive), concatenated.

Days that fail to download are skipped with a warning.

fetch_trades_day

data.sources.binance.fetch_trades_day(
    symbol,
    date,
    download_dir='data',
    cache_dir=DEFAULT_CACHE_DIR,
)

Fetch all trades for symbol on a single day (cached as parquet).

Parameters

Name Type Description Default
symbol str Binance symbol, e.g. "BTCUSDT". required
date str | datetime Day to fetch, YYYY-MM-DD or datetime. required
download_dir str | Path Directory for temporary zip/csv downloads. 'data'
cache_dir str | Path Directory for parquet trade caches. DEFAULT_CACHE_DIR

Returns

Name Type Description
pd.DataFrame DataFrame with columns id, price, qty, quote_qty, time, | | | pd.DataFrame | is_buyer_maker, datetime.

read

data.sources.binance.read(
    symbols,
    start_date,
    end_date,
    time_interval='1h',
    download_dir='data',
    cache_dir=DEFAULT_CACHE_DIR,
)

Fetch OHLCV bars aggregated from tick trades.

Bars are aggregated per day and concatenated, so intervals should divide evenly into one day.

Parameters

Name Type Description Default
symbols str | list[str] A single symbol, or a list of symbols. required
start_date str | datetime Start date (inclusive), YYYY-MM-DD or datetime. required
end_date str | datetime End date (inclusive), YYYY-MM-DD or datetime. required
time_interval str Pandas offset alias (e.g. "1h", "5min"). '1h'
download_dir str | Path Directory for temporary zip/csv downloads. 'data'
cache_dir str | Path Directory for parquet trade caches. DEFAULT_CACHE_DIR

Returns

Name Type Description
pd.DataFrame | dict[str, pd.DataFrame] A single DataFrame if symbols is a string, otherwise a dict of
pd.DataFrame | dict[str, pd.DataFrame] DataFrames keyed by symbol (failed symbols are skipped with a
pd.DataFrame | dict[str, pd.DataFrame] warning, with a progress bar shown).
Back to top