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(), andget_exchange_info()query API metadata and can be used without an API key.- Dataset download helpers such as
get_trades()andget_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, anduse_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_SPOTchd.exchanges.BINANCE_FUTURESchd.exchanges.BYBIT_SPOTchd.exchanges.BYBIT_FUTURESchd.exchanges.KRAKEN_FUTURES
Error Handling
The most common exceptions are:
ValidationErrorfor invalid symbols, exchange identifiers, or date rangesConfigurationErrorwhen a dataset download is attempted without an API keyAuthenticationErrorwhen credentials are rejectedAPIErrorfor 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)andhelp(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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.