Skip to main content

CryptoHFTData Python SDK

PyPI version Python versions License: MIT

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):

Helper Main columns
get_candles() symbol, interval, open_time, close_time, open, high, low, close, base_volume, quote_volume
get_orderbook() received_time, event_time, event_type, side, price, quantity, sequence IDs
get_trades() received_time, event_time, trade_id, price, quantity, trade_time, is_buyer_maker, order_type
get_ticker() received_time, event_time, last_price, open_price, high_price, low_price, price_change_percent, base_asset_volume, quote_asset_volume
get_mark_price() received_time, event_time, mark_price, index_price, funding_rate, next_funding_time
get_open_interest() received_time, timestamp, sum_open_interest, sum_open_interest_value
get_liquidations() received_time, event_time, side, price, average_price, quantity, filled_quantity, trade_time

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

Metadata

Release files for cryptohftdata 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cryptohftdata 0.8.1
File Size Uploaded Provenance Actions
cryptohftdata-0.8.1.tar.gz 121.7 kB With provenance Details for cryptohftdata-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cryptohftdata 0.8.1
File Interpreter ABI Platform Actions
cryptohftdata-0.8.1-py3-none-any.whl Python 3 none any Details for cryptohftdata-0.8.1-py3-none-any.whl

Total release size: 190.3 kB

Release files / cryptohftdata-0.8.1.tar.gz

Download URL cryptohftdata-0.8.1.tar.gz
Size 121.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0c65b49f538843e980c059b7dc43c9706278c1ccb560343c7c0eeee400466566
BLAKE2b-256 checksum
How to use checksums
27ff097c66241466f0838f084c64fbccc24d261b6f4dd14c477e20a77d2b6bb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / cryptohftdata-0.8.1-py3-none-any.whl

Download URL cryptohftdata-0.8.1-py3-none-any.whl
Size 68.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b01a9225c9d1de2e0186d547aee14423c9b9d7ca53f0470b26fe946ea3f4e6b9
BLAKE2b-256 checksum
How to use checksums
127cf69363eebeeef245cdcdeea283a79ca0a7b2901f238decb7f55667affff7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for cryptohftdata 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cryptohftdata-0.8.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page