Metadata-Version: 2.4
Name: cryptohftdata
Version: 0.2.2
Summary: Python SDK for accessing cryptocurrency high-frequency trading data
Author-email: CryptoHFTData Team <support@cryptohftdata.com>
License: MIT
Project-URL: Homepage, https://cryptohftdata.com
Project-URL: Documentation, https://cryptohftdata.com/docs
Project-URL: Support, https://cryptohftdata.com/support
Keywords: cryptocurrency,trading,market-data,api,hft
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: zstandard>=0.21.0
Requires-Dist: tqdm>=4.64.0
Requires-Dist: pytest-cov>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "dev"
Requires-Dist: types-requests>=2.25.0; extra == "dev"
Requires-Dist: types-python-dateutil>=2.8.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: responses>=0.23.0; extra == "test"
Dynamic: license-file

# CryptoHFTData Python SDK

[![PyPI version](https://badge.fury.io/py/cryptohftdata.svg)](https://badge.fury.io/py/cryptohftdata)
[![Python versions](https://img.shields.io/pypi/pyversions/cryptohftdata.svg)](https://pypi.org/project/cryptohftdata/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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

```bash
pip install cryptohftdata
```

## Quick Start

Dataset downloads require an API key. Export `CRYPTOHFTDATA_API_KEY` or pass
`api_key=` explicitly.

```python
import os

import cryptohftdata as chd

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 and require an API key.
- The convenience helpers also accept client configuration kwargs such as
  `api_key`, `base_url`, `timeout`, `max_retries`, `rate_limit`, and
  `use_jwt`.

## Public API

### Convenience helpers

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

```python
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")
```

### Explicit client usage

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

```python
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. Column names can vary by
exchange, but these are the typical shapes:

| Helper | Typical columns |
| --- | --- |
| `get_klines()` | `open_time`, `open`, `high`, `low`, `close`, `volume` |
| `get_orderbook()` | `timestamp`, `side`, `level`, `price`, `size` |
| `get_trades()` | `timestamp`, `trade_id`, `price`, `quantity`, `side` |
| `get_ticker()` | `timestamp`, `open`, `high`, `low`, `close`, `volume` |
| `get_mark_price()` | `timestamp`, `mark_price`, `index_price`, `funding_rate`, `next_funding_time` |
| `get_open_interest()` | `timestamp`, `symbol`, `exchange`, `open_interest` |
| `get_liquidations()` | `timestamp`, `side`, `price`, `quantity`, `order_id` |

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

```python
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:

```python
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:

```python
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:

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

## Support

- Documentation: [https://cryptohftdata.com/docs](https://cryptohftdata.com/docs)
- Support: [https://cryptohftdata.com/support](https://cryptohftdata.com/support)
- Homepage: [https://cryptohftdata.com](https://cryptohftdata.com)
