A non-official Python toolkit for managing historical market data from data.binance.vision — designed from the ground up for AI agents and quantitative workflows.
binance-datatool is designed to make every command equally easy to call for AI agents and humans.:
- Composable CLI — stdin/stdout pipelines let agents chain commands without glue code
- Atomic operations — each command does one thing well; agents can inspect, decide, and act step by step
- Deterministic output — structured, parseable results that agents can reason about
- Zero interaction — no prompts, no confirmations; dry-run mode for safe previews
A packaged Agent Skill is included in this repository.
It teaches agents how to use binance-datatool to discover, download, and
verify Binance historical market data — no manual command lookup required.
- Multi-market coverage — Spot, USD-M Futures, and COIN-M Futures
- Smart symbol filtering — filter by quote asset, exclude stablecoins and leveraged tokens, select contract types
- Resumable batch downloads — diff-based sync via aria2 that only fetches new or updated files
- Data integrity verification — SHA256 checksum validation with timestamped marker caching
- Composable pipelines — Unix-friendly design; commands read from stdin and write to stdout
- Async I/O — concurrent S3 listing and parallel checksum verification
# install the CLI
pipx install binance-datatool
# run `pipx ensurepath` if the command isn't found immediately
# system dependency for download command
# macOS
brew install aria2
# Ubuntu/Debian
sudo apt install aria2
export BINANCE_DATATOOL_ARCHIVE_HOME="$HOME/crypto_data/binance_archive"
binance-datatool --help# List USDT-quoted spot symbols, excluding stablecoins
binance-datatool list-symbols spot --quote USDT --exclude-stables
# Download daily 1m klines
binance-datatool list-symbols spot --quote USDT --exclude-stables \
| binance-datatool download spot --type klines --interval 1m
# Verify integrity
binance-datatool verify spot --type klines --interval 1m BTCUSDT| Category | Types |
|---|---|
| Trade data | klines, aggTrades, trades |
| Derivatives | fundingRate, liquidationSnapshot, metrics |
| Order book | bookDepth, bookTicker |
| Index data | indexPriceKlines, markPriceKlines, premiumIndexKlines |
Each type is available in daily or monthly partitions. Kline types
support all standard intervals (1m 3m 5m 15m 30m 1h 2h 4h
6h 8h 12h 1d 3d 1w 1mo).
The entry point is binance-datatool. All data commands are available
directly on the root app:
| Command | Description |
|---|---|
list-symbols |
List available symbols on the remote archive |
list-files |
List archive files for given symbols |
download |
Download new or updated archive files |
verify |
Verify files against SHA256 checksums |
Tip
Every command accepts symbols from stdin or as positional args, making it trivial to compose pipelines:
binance-datatool list-symbols um --quote USDT \
| binance-datatool download um --type klines --interval 1mRun binance-datatool --help for the full option reference.
CLI Layer Thin Typer commands (argument parsing, output formatting)
│
Workflow Layer Business logic (diff computation, verification protocol)
│
Archive Layer S3 communication (HTTP listing, aria2 downloading, checksums)
│
Common Layer Shared types, enums, constants, and utilities
See docs/architecture.md for a detailed design overview.
| Document | Description |
|---|---|
| Architecture | Layered design, data flow, and key decisions |
| Module Reference | Per-subpackage API reference |
| Extending | How to add commands, enums, workflows, and tests |
| Testing Guide | Test organization and conventions |
| Agent Skill | Packaged skill for agents |
