CryptoHFTData Python SDK

cryptohftdata is a Python SDK for downloading high-frequency cryptocurrency market data as pandas DataFrames.

It is designed for research scripts, notebooks, and production ingestion jobs that need a simple interface over the CryptoHFTData parquet dataset.

Installation

pip install cryptohftdata

Command-line tool

The PyPI package installs the official cryptohftdata CLI:

cryptohftdata status
cryptohftdata symbols --exchange binance_spot --data-type trades
cryptohftdata download --file binance_spot/2026-09-02/12/BTCUSDT_trades.parquet

bulk downloads a whole date range to disk in one command, and needs no install when run through uvx:

uvx cryptohftdata bulk --exchange binance_futures --data-type trades \
  --symbols BTCUSDT ETHUSDT --start 2026-09-01 --end 2026-09-07

It wraps download_bulk(): files land in ./chd_data (--dest) in a hive layout, re-running resumes an interrupted download, --dry-run lists the plan first, and omitting --symbols downloads every symbol. Run cryptohftdata bulk --help for every option.

Discovery and rate-limited downloads work without a key. For authenticated use, set CRYPTOHFTDATA_API_KEY; avoid putting credentials in shell history. The CLI honors API error codes and reports Retry-After on rate limits.

Quick Start

No API key is needed to get started: without one, downloads use the free tier, which is rate limited to 60 requests per minute per IP, and the SDK logs a warning on each download call. For unlimited rate limits, create a free account at https://www.cryptohftdata.com/signup, then export CRYPTOHFTDATA_API_KEY or pass api_key= explicitly.

import cryptohftdata as chd

# Optional: unlimited rate limits with a free API key.
# chd.configure_client(api_key=os.environ["CRYPTOHFTDATA_API_KEY"])

exchange = chd.exchanges.BINANCE_FUTURES
symbols = chd.list_symbols(exchange, data_type="trades")

if "BTCUSDT" not in symbols:
    raise RuntimeError("BTCUSDT is not currently listed for Binance futures trades")

trades = chd.get_trades(
    symbol="BTCUSDT",
    exchange=exchange,
    start_date="2025-08-01",
    end_date="2025-08-01",
    max_workers=4,
)

print(trades.head())
print(f"rows={len(trades)} columns={list(trades.columns)}")

Authentication Model

• list_symbols(), list_exchanges(), and get_exchange_info() query API metadata and can be used without an API key.
• Dataset download helpers such as get_trades() and get_mark_price() download parquet files. Without an API key they use the free tier, which is rate limited to 60 requests per minute per IP and logs a warning on each call. With an API key, rate limits are unlimited.
• The convenience helpers also accept client configuration kwargs such as api_key, base_url, timeout, max_retries, rate_limit, and use_jwt.

Native S3 Access

If you want raw flat-file access instead of DataFrame helpers, exchange your existing CryptoHFTData API key for short-lived R2 S3 credentials:

import os
import requests

response = requests.post(
    "https://api.cryptohftdata.com/s3-credentials",
    headers={"X-API-Key": os.environ["CRYPTOHFTDATA_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

payload = response.json()
creds = payload["credentials"]

print(payload["bucket"])
print(payload["endpoint"])
print(payload["expires_at"])

You can then pass the returned credentials into boto3:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url=payload["endpoint"],
    region_name=payload["region"],
    aws_access_key_id=creds["access_key_id"],
    aws_secret_access_key=creds["secret_access_key"],
    aws_session_token=creds["session_token"],
)

objects = s3.list_objects_v2(Bucket=payload["bucket"])
for item in objects.get("Contents", []):
    print(item["Key"])

Public API

Convenience helpers

Use the top-level helpers when you want the shortest path from notebook code to DataFrame output:

import cryptohftdata as chd

chd.configure_client(api_key="your-api-key")

trades = chd.get_trades("BTCUSDT", chd.exchanges.BINANCE_FUTURES, "2025-08-01", "2025-08-01")
mark_price = chd.get_mark_price("BTCUSDT", chd.exchanges.BINANCE_FUTURES, "2025-08-01", "2025-08-01")

For finalized higher-time-frame data, get_candles() accepts any of 1m, 3m, 5m, 15m, 1h, 4h, 6h, or 1d:

candles = chd.get_candles(
    exchange=chd.exchanges.BINANCE_FUTURES,
    symbol="BTCUSDT",
    interval="4h",
    start="2025-01-01T00:00:00Z",
    end="2025-12-31T20:00:00Z",
    max_workers=8,
)

The start and end values are inclusive candle-open-time boundaries. The SDK uses the symbol manifest to fetch only overlapping monthly Parquet objects in parallel, verifies every object size and SHA-256, and fails closed if continuous coverage is incomplete, the collector watermark is stale, or the requested leading boundary was never source-attested. Set allow_partial=True only when partial history is acceptable.

Explicit client usage

Use CryptoHFTDataClient when you want explicit configuration, context-manager usage, or cache inspection:

from cryptohftdata import CryptoHFTDataClient, exchanges

with CryptoHFTDataClient(api_key="your-api-key", timeout=60, rate_limit=10) as client:
    info = client.get_exchange_info(exchanges.BYBIT_FUTURES)
    trades = client.get_trades(
        "ETHUSDT",
        exchanges.BYBIT_FUTURES,
        "2025-08-01",
        "2025-08-01",
        max_workers=2,
    )
    print(info["supported_data_types"])
    print(client.get_cache_info())

Data Sets

All dataset download helpers return pandas DataFrames. These are the main columns (some are null on venues that do not publish them):

Columns are the normalized Parquet columns; all price and size columns are decimal strings, received_time is nanoseconds, and exchange timestamps are milliseconds. Units and semantics still differ by venue, for example:

• OKX derivative sizes are contracts (multiply by the instrument's ctVal: base coin for linear swaps, USD for inverse swaps), and BitMEX quantities are raw per-instrument units.
• Binance and Aster publish at most one liquidation per symbol per second, so their liquidations are a sample; Bybit and OKX liquidation prices are the bankruptcy price.
• OKX trades before the 2026-09 data-integrity release are one row per taker order per price level (aggregated fills), not one row per fill.
• BitMEX has closed; its files end on 2026-09-22 and remain downloadable.

Venue notes, known missing hours, and planned corrections to published history are listed at https://www.cryptohftdata.com/docs/data-gaps-and-corrections.

You can inspect the in-package schema reference if you want a structured summary at runtime:

from cryptohftdata import get_dataset_schema

schema = get_dataset_schema("trades")
print(schema.typical_columns)

Supported Exchanges

Use the SDK itself to discover supported exchanges and dataset coverage instead of hard-coding assumptions:

import cryptohftdata as chd

for exchange in chd.list_exchanges():
    info = chd.get_exchange_info(exchange)
    print(exchange, info["type"], info["supported_data_types"])

The package also exposes constants through chd.exchanges, for example:

• chd.exchanges.BINANCE_SPOT
• chd.exchanges.BINANCE_FUTURES
• chd.exchanges.BYBIT_SPOT
• chd.exchanges.BYBIT_FUTURES
• chd.exchanges.KRAKEN_FUTURES

Error Handling

The most common exceptions are:

• ValidationError for invalid symbols, exchange identifiers, or date ranges
• ConfigurationError when a dataset download is attempted without an API key
• AuthenticationError when credentials are rejected
• APIError for API-side failures or malformed responses

Example:

import cryptohftdata as chd

try:
    chd.get_trades("BTCUSDT", chd.exchanges.BINANCE_FUTURES, "2025-08-02", "2025-08-01")
except chd.ValidationError as exc:
    print(f"invalid request: {exc}")

Examples and Docs

• Example scripts live in sdk/python/examples/
• Documentation source files live in sdk/python/docs/
• Package docstrings are available through help(cryptohftdata) and help(cryptohftdata.CryptoHFTDataClient)

Development

From a source checkout:

cd sdk/python
pip install -e ".[dev,docs,test]"
pytest
sphinx-build -b html docs docs/_build/html

Support

• Documentation: https://cryptohftdata.com/docs
• Support: https://cryptohftdata.com/support
• Homepage: https://cryptohftdata.com