Metadata-Version: 2.1
Name: tardis-dev
Version: 3.3.0
Summary: Python client for tardis.dev - historical tick-level cryptocurrency market data replay API.
Home-page: https://github.com/tardis-dev/tardis-python
License: MPL-2.0
Keywords: cryptocurrency data feed,market data,api client,orderbook,crypto markets data replay,historical data,historical cryptocurrency prices,cryptocurrency api
Author: Thad
Author-email: thad@tardis.dev
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: aiohttp (>=3.10.0)
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: zstandard (>=0.19.0)
Description-Content-Type: text/markdown

# tardis-dev

[![PyPi](https://img.shields.io/pypi/v/tardis-dev.svg)](https://pypi.org/project/tardis-dev/)
[![Python](https://img.shields.io/pypi/pyversions/tardis-dev.svg)](https://pypi.org/project/tardis-dev/)
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>

<br/>

Python `tardis-dev` package provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: replaying historical market data and downloading historical market data as CSV files. If you need normalized replay or real-time streaming, use the Node.js client or Tardis Machine.

`replay()` accepts ISO date strings or Python `datetime` values. Naive datetimes are treated as UTC.

<br/>

```python
import asyncio
from tardis_dev import Channel, replay


async def main():
    async for local_timestamp, message in replay(
        exchange="binance",
        from_date="2024-03-01",
        to_date="2024-03-02",
        filters=[Channel("trade", ["btcusdt"]), Channel("depth", ["btcusdt"])],
        api_key="YOUR_API_KEY",
    ):
        print(local_timestamp, message)


asyncio.run(main())
```

<br/>

## Features

- historical tick-level [market data replay](https://docs.tardis.dev/python-client/replaying-historical-data) backed by Tardis.dev [HTTP API](https://docs.tardis.dev/api/http-api-reference#data-feeds-exchange)

<br/>

- [historical market data downloads as CSV files](https://docs.tardis.dev/python-client/quickstart#csv-dataset-downloads)

<br/>

- support for many cryptocurrency exchanges — see [docs.tardis.dev](https://docs.tardis.dev/historical-data-details/overview) for the full list

<br/>
<br/>
<br/>

## Installation

Requires Python 3.9+ installed.

```bash
pip install tardis-dev
```

<br/>
<br/>

## Documentation

### [See official docs](https://docs.tardis.dev/python-client/quickstart)

- [Quickstart](https://docs.tardis.dev/python-client/quickstart)
- [Replaying Historical Data](https://docs.tardis.dev/python-client/replaying-historical-data)
- [CSV Dataset Downloads](https://docs.tardis.dev/python-client/quickstart#csv-dataset-downloads)
- [Migration Notice](https://docs.tardis.dev/python-client/migration-notice)

<br/>
<br/>

## Examples

### Replay historical market data

```python
import asyncio
from tardis_dev import Channel, replay


async def main():
    async for local_timestamp, message in replay(
        exchange="binance",
        from_date="2024-03-01",
        to_date="2024-03-02",
        filters=[Channel("trade", ["btcusdt"]), Channel("depth", ["btcusdt"])],
    ):
        print(local_timestamp, message)


asyncio.run(main())
```

<br/>

### Download CSV datasets

```python
from tardis_dev import download_datasets


download_datasets(
    exchange="binance",
    data_types=["trades", "incremental_book_L2"],
    symbols=["BTCUSDT"],
    from_date="2024-03-01",
    to_date="2024-03-02",
    api_key="YOUR_API_KEY",
)
```

<br/>

### Migration from `tardis-client`

This package is the v3 API. Existing `tardis-client` and `tardis_dev.datasets.download()` users should migrate to the new top-level functions:

- replay: `TardisClient().replay(...)` -> `replay(...)`
- datasets: `from tardis_dev import datasets; datasets.download(...)` -> `from tardis_dev import download_datasets`
- cache cleanup: `tardis_client.clear_cache()` -> `clear_cache()`

See [Migration Notice](https://docs.tardis.dev/python-client/migration-notice) for the full migration guide.

<br/>
<br/>

## See the [tardis-dev docs](https://docs.tardis.dev/python-client/quickstart) for more examples.

