binance-vision

Download historical cryptocurrency market data from Binance Vision — spot, USD-M futures, COIN-M futures and options — straight into a pandas DataFrame.

Binance publishes its historical data as thousands of individual zipped CSVs, split by market, data type, symbol, interval and calendar period, with inconsistent headers and timestamp units. This package hides all of that behind a single function.

from binance_vision import fetch_data

result = fetch_data(
    ticker="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-03-15",
    market="spot",
    data_type="klines",
    interval="1h",
)

print(result)
# FetchResult(rows=1800, files_used=17, missing=0, failed=0, output_path=None)

print(result.data.head())

Install

pip install binance-vision

Requires Python 3.9+.

Why not just download the files yourself

Usage

The result object

fetch_data() returns a FetchResult:

Writing to disk

result = fetch_data(
    "ETHUSDT", "2024-01-01", "2024-01-31",
    market="usdm", data_type="klines", interval="5m",
    output_format="parquet",          # or "csv"
    output_path="data/eth_5m",        # extension added automatically
)
print(result.output_path)  # data/eth_5m.parquet

Discovering what's available

from binance_vision import supported_markets, supported_data_types

supported_markets()
# ('spot', 'usdm', 'coinm', 'options')

supported_data_types("usdm")
# ('aggTrades', 'bookDepth', 'bookTicker', 'indexPriceKlines', 'klines',
#  'liquidationSnapshot', 'markPriceKlines', 'metrics', 'premiumIndexKlines', 'trades')

Checking for gaps

A range that is only partly published still returns everything it could get:

result = fetch_data("BTCUSDT", "2025-05-25", "2025-06-05",
                    market="usdm", data_type="bookTicker")

if result.missing:
    print(f"No data published for: {result.missing}")
if result.failed:
    raise RuntimeError(f"Downloads failed: {result.failed}")

API

fetch_data(
    ticker: str,
    start_date: str | date | datetime,
    end_date: str | date | datetime,
    market: str,
    data_type: str,
    interval: str | None = None,
    output_format: str = "parquet",
    output_path: str | None = None,
    max_workers: int = 8,
) -> FetchResult

Supported data types

Retired feeds. Binance has stopped publishing futures liquidationSnapshot (the bucket prefix is now empty for every symbol) and option EOHSummary (last file 2023-10-23). They remain in the registry so existing scripts keep working; requesting them returns the periods in result.missing.

Notes

• All timestamp columns are converted to timezone-aware UTC datetimes.
• Trade-level data types are large — a single day of spot/trades for a major pair is well over a million rows. Prefer parquet output and narrow ranges.
• Binance Vision is a free, unauthenticated static file host. No API key is needed, but please be considerate with max_workers.

Development

git clone https://github.com/Njenjo/binance-vision
cd binance-vision
pip install -e ".[dev]"

Run the offline unit tests:

pytest -m "not network"

Run the full suite, including live requests against data.binance.vision:

pytest

License

MIT — see LICENSE.

Disclaimer

This project is not affiliated with, endorsed by, or connected to Binance. It is an independent client for their public historical data archive. Market data is provided as-is; verify it before relying on it for trading decisions.