Binance K-line Data Downloader

A Python script for downloading historical K-line (candlestick) data from Binance exchange, supporting both futures and spot markets with resume functionality.

Features

• ✅ Dual Market Support: Download data from both Binance Futures (U-margined) and Spot markets
• ✅ Resume Capability: Automatically resume from the last downloaded timestamp if the file exists
• ✅ Auto Filename Parsing: Automatically extracts symbol and interval from existing filenames
• ✅ Auto Filename Generation: Generates filenames automatically based on market type, symbol, interval, and time range
• ✅ Time Range Support: Download data for specific time periods
• ✅ Error Handling: Automatic retry mechanism with exponential backoff
• ✅ Progress Tracking: Real-time progress display with batch information

Requirements

pip install requests pandas

Usage

Basic Syntax

python download_binance_klines.py --market {futures|spot} [OPTIONS]

Required Arguments

• --market: Market type (futures or spot)

Optional Arguments

• filename: Output CSV filename (optional, required for resume). If not provided, filename will be auto-generated.
• --symbol: Trading pair symbol (e.g., BTCUSDT, ETHUSDT). Required if filename is not provided or cannot be parsed.
• --interval: K-line interval (e.g., 1m, 5m, 15m, 1h, 4h, 1d). Required if filename is not provided or cannot be parsed.
• --start-time: Start time in UTC format: "YYYY-MM-DD HH:MM:SS". Defaults to earliest available data if not specified.
• --end-time: End time in UTC format: "YYYY-MM-DD HH:MM:SS". Downloads to latest if not specified.
• --max-limit: Maximum number of K-lines per request (default: 1500 for futures, 1000 for spot)
• --max-retries: Maximum retry attempts per request (default: 5)
• --sleep: Sleep time between batches in seconds (default: 0.05 for futures, 0.2 for spot)
• --no-resume: Disable resume functionality, start fresh even if file exists

Examples

1. Download Futures Data (Auto-generate filename)

python download_binance_klines.py --market futures --symbol BTCUSDT --interval 1m

Output: data_BTCUSDT_1m.csv

2. Download Spot Data (Auto-generate filename)

python download_binance_klines.py --market spot --symbol BTCUSDT --interval 1m

Output: spot_BTCUSDT_1m.csv

3. Download with Time Range (Auto-add time suffix)

python download_binance_klines.py --market futures --symbol BTCUSDT --interval 1m \
  --start-time "2021-09-01 00:00:00" --end-time "2021-12-01 00:00:00"

Output: data_BTCUSDT_1m_20210901_20211201.csv

4. Resume Download (Parse from filename)

python download_binance_klines.py spot_BTCUSDT_1m.csv --market spot

The script will:

• Parse BTCUSDT and 1m from the filename
• Read the last timestamp from the existing file
• Continue downloading from that point

5. Resume Download (Explicit parameters)

python download_binance_klines.py data_BTCUSDT_1m.csv --market futures

6. Disable Resume (Start Fresh)

python download_binance_klines.py data_BTCUSDT_1m.csv --market futures --no-resume

7. Custom Time Range with Resume

python download_binance_klines.py --market spot --symbol ETHUSDT --interval 5m \
  --start-time "2023-01-01 00:00:00" --end-time "2023-12-31 23:59:59"

Filename Conventions

The script follows these filename patterns:

Futures Market

• Format: data_{SYMBOL}_{INTERVAL}.csv
• Example: data_BTCUSDT_1m.csv
• Alternative: futures_{SYMBOL}_{INTERVAL}.csv

Spot Market

• Format: spot_{SYMBOL}_{INTERVAL}.csv
• Example: spot_BTCUSDT_1m.csv

With Time Range

• Format: {BASE_FILENAME}_YYYYMMDD_YYYYMMDD.csv
• Example: data_BTCUSDT_1m_20210901_20211201.csv
• If only start time: data_BTCUSDT_1m_20210901.csv
• If only end time: data_BTCUSDT_1m_20211201.csv

Supported Intervals

• Minutes: 1m, 3m, 5m, 15m, 30m
• Hours: 1h, 2h, 4h, 6h, 8h, 12h
• Days: 1d, 3d
• Weeks: 1w
• Months: 1M

Default Values

Futures Market

• Default Start Time: 2019-01-01 00:00:00 UTC
• Default Max Limit: 1500 K-lines per request
• Default Sleep: 0.05 seconds between batches

Spot Market

• Default Start Time: 2017-01-01 00:00:00 UTC
• Default Max Limit: 1000 K-lines per request
• Default Sleep: 0.2 seconds between batches

Output Format

Futures CSV Format

time,open,high,low,close,volume,taker_base
2021-09-01 00:00:00,47000.0,47050.0,46950.0,47020.0,1234.56,567.89

Spot CSV Format

time,open,high,low,close,volume,taker_base
1630454400000,47000.0,47050.0,46950.0,47020.0,1234.56,567.89

Note:

• Futures uses datetime string format for time column
• Spot uses millisecond timestamp for time column

Resume Functionality

The script automatically detects existing CSV files and resumes downloading from the last timestamp:

1. If file exists and --no-resume is NOT set:

   • Reads the last timestamp from the file
   • Continues downloading from that point
   • Appends new data to the file (futures: merges and deduplicates, spot: appends)

2. If file does not exist or --no-resume is set:

   • Starts from the specified --start-time or default start time
   • Creates a new file

Error Handling

• Automatic Retry: Each request retries up to 5 times (configurable via --max-retries)
• Exponential Backoff: Wait time increases with each retry attempt
• Graceful Failure: If all retries fail, the script exits but can be resumed later
• Duplicate Prevention: Automatically filters duplicate K-lines

Performance Tips

1. For Large Downloads: Use appropriate --max-limit values (higher = fewer requests but more data per request)
2. For Rate Limiting: Adjust --sleep to avoid hitting API rate limits
3. For Interrupted Downloads: Simply re-run the same command to resume

Notes

• All times are in UTC
• The script respects Binance API rate limits
• Futures and spot markets use different API endpoints
• Data is saved incrementally, so you can stop and resume anytime
• For futures, existing data is merged and deduplicated
• For spot, new data is appended to the file

Troubleshooting

Issue: "无法从文件名解析币种和间隔" (Cannot parse symbol and interval from filename)

Solution: Provide --symbol and --interval parameters explicitly, or use a filename that follows the convention: {prefix}_{SYMBOL}_{INTERVAL}.csv

Issue: "HTTP 429" (Rate limit exceeded)

Solution: Increase --sleep value to slow down requests

Issue: "多次重试后仍失败" (Multiple retries failed)

Solution: Check your internet connection and Binance API status. The script can be resumed later from the same point.

License

This script is provided as-is for educational and research purposes. Please ensure compliance with Binance's Terms of Service and API usage policies.