Metadata-Version: 2.5
Name: binance-vision
Version: 0.1.0
Summary: Download historical spot, futures and options market data from Binance Vision as pandas DataFrames.
Project-URL: Homepage, https://github.com/Njenjo/binance-vision
Project-URL: Repository, https://github.com/Njenjo/binance-vision
Project-URL: Issues, https://github.com/Njenjo/binance-vision/issues
Project-URL: Changelog, https://github.com/Njenjo/binance-vision/blob/main/CHANGELOG.md
Author-email: householddude <115847042+Njenjo@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 householddude
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: backtesting,binance,binance-vision,candlesticks,cryptocurrency,futures,klines,market-data,ohlcv,options,pandas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# binance-vision

Download historical cryptocurrency market data from
[Binance Vision](https://data.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.

```python
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

```bash
pip install binance-vision
```

Requires Python 3.9+.

## Why not just download the files yourself

| Problem | What this package does |
| --- | --- |
| Data is split into monthly *and* daily archives | Plans the range automatically — whole calendar months use the monthly archive, the partial edges fall back to daily files |
| Some CSVs have a header row, some don't | Sniffs each file individually and applies the correct column names |
| Epoch columns switched from ms to µs mid-2025 for some feeds | Infers the unit per file from the magnitude and converts to UTC datetimes |
| Every archive has a `.CHECKSUM` sidecar | Verifies SHA-256 on every download, failing loudly on corruption |
| Hundreds of files for a long range | Downloads concurrently with a configurable worker pool |
| Some periods were never published | Reported in `result.missing` — a partial range never raises |

## Usage

### The result object

`fetch_data()` returns a `FetchResult`:

| Attribute | Description |
| --- | --- |
| `data` | The concatenated `pandas.DataFrame`, sorted by its primary time column |
| `output_path` | Path written to, or `None` if `output_path` was not given |
| `files_used` | Period labels successfully downloaded and parsed (`"2024-01"`, `"2024-01-15"`) |
| `missing` | Period labels with no file published upstream — **not** an error |
| `failed` | `(label, error)` pairs for real failures: network, checksum or parse errors |

### Writing to disk

```python
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

```python
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:

```python
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

```python
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
```

| Parameter | Description |
| --- | --- |
| `ticker` | Symbol as published by Binance, e.g. `"BTCUSDT"`, `"BTCUSD_PERP"`. Case-insensitive |
| `start_date`, `end_date` | Inclusive UTC date range. `"YYYY-MM-DD"` string, `date` or `datetime` |
| `market` | `"spot"`, `"usdm"`, `"coinm"` or `"options"` (aliases: `um`, `cm`, `usd-m`, `coin-m`, `option`) |
| `data_type` | See the table below. Invalid combinations raise `ValueError` listing the valid types |
| `interval` | Required for the klines family, e.g. `"1m"`, `"1h"`, `"1d"` |
| `output_format` | `"parquet"` (default) or `"csv"`. Only used when `output_path` is set |
| `output_path` | If given, the DataFrame is also written here |
| `max_workers` | Concurrent downloads (default 8) |

## Supported data types

| Market | Data type | Granularity | Needs `interval` |
| --- | --- | --- | --- |
| spot | `klines` | monthly + daily | yes |
| spot | `trades`, `aggTrades` | monthly + daily | no |
| usdm / coinm | `klines`, `indexPriceKlines`, `markPriceKlines`, `premiumIndexKlines` | monthly + daily | yes |
| usdm / coinm | `trades`, `aggTrades`, `bookTicker` | monthly + daily | no |
| usdm / coinm | `bookDepth`, `metrics`, `liquidationSnapshot` | daily only | no |
| options | `BVOLIndex`, `EOHSummary`, `trades` | daily only | no |

> **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

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

Run the offline unit tests:

```bash
pytest -m "not network"
```

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

```bash
pytest
```

## License

MIT — see [LICENSE](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.
