# Quickstart

Python `tardis-dev` package provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: historical replay and CSV dataset downloads.

## Features

* [historical market data replay](https://docs.tardis.dev/python-client/replaying-historical-data)
* [CSV dataset downloads](https://docs.tardis.dev/downloadable-csv-files/overview)

{% hint style="warning" %}
If you're migrating older Python code that used `tardis-client`, `TardisClient` or `from tardis_dev import datasets`, start with [Migration Notice](https://docs.tardis.dev/python-client/migration-notice).
{% endhint %}

{% embed url="<https://github.com/tardis-dev/tardis-python>" %}
Python tardis-dev GitHub repository
{% endembed %}

## Installation

Requires Python >=3.9.

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

## Historical Replay

```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())
```

See [Replaying Historical Data](https://docs.tardis.dev/python-client/replaying-historical-data) for replay arguments, `Channel` filters, disconnect events and cache behavior.

{% content-ref url="replaying-historical-data" %}
[replaying-historical-data](https://docs.tardis.dev/python-client/replaying-historical-data)
{% endcontent-ref %}

## CSV Dataset Downloads

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

{% hint style="info" %}
If you're calling from an existing event loop, use `download_datasets_async()` instead of `download_datasets()`.
{% endhint %}

See also [Downloadable CSV files docs](https://docs.tardis.dev/downloadable-csv-files/overview).

### `download_datasets(...)`

`download_datasets()` is the synchronous wrapper around `download_datasets_async()`. It raises `RuntimeError` if called inside a running event loop.

| name             | type                | default                          | description                                                                                                                                                                           |
| ---------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange`       | string              | -                                | exchange id with `supportsDatasets=true`; use [`get_exchange_details()`](#historical-market-data-helpers) to inspect available dataset symbols and data types                         |
| `data_types`     | sequence of strings | -                                | dataset types to download, e.g. `trades`, `incremental_book_L2`, `quotes`, `book_snapshot_25`, `book_snapshot_5`, `book_ticker`, `derivative_ticker`, `options_chain`, `liquidations` |
| `symbols`        | sequence of strings | -                                | dataset symbols to download, e.g. `BTCUSDT` or grouped symbols such as `OPTIONS`                                                                                                      |
| `from_date`      | string              | -                                | start date in ISO format, e.g. `2024-03-01`                                                                                                                                           |
| `to_date`        | string              | -                                | end date in ISO format (non-inclusive)                                                                                                                                                |
| `api_key`        | string (optional)   | `""`                             | API key for premium historical datasets                                                                                                                                               |
| `download_dir`   | string (optional)   | `"./datasets"`                   | local directory where downloaded files will be stored                                                                                                                                 |
| `endpoint`       | string (optional)   | `https://datasets.tardis.dev/v1` | override datasets API endpoint                                                                                                                                                        |
| `timeout`        | integer (optional)  | `1800`                           | HTTP timeout in seconds                                                                                                                                                               |
| `http_proxy`     | string (optional)   | `None`                           | HTTP proxy URL passed to `aiohttp`                                                                                                                                                    |
| `format`         | literal `"csv"`     | `"csv"`                          | dataset file format                                                                                                                                                                   |
| `concurrency`    | integer (optional)  | `20`                             | number of parallel download tasks; must be greater than `0`                                                                                                                           |
| `get_filename`   | callable (optional) | `default_file_name`              | function that returns the relative output path for each downloaded file                                                                                                               |
| `skip_if_exists` | boolean (optional)  | `True`                           | when `True`, skips files that already exist locally                                                                                                                                   |

### `download_datasets_async(...)`

Use `download_datasets_async()` inside an existing `asyncio` event loop. It accepts the same arguments as `download_datasets()`.

## Historical Market Data Helpers

```python
from tardis_dev import clear_cache, get_exchange_details

details = get_exchange_details("binance")
print(details["availableSymbols"][0]["id"])

clear_cache()
```

`get_exchange_details()` is the synchronous wrapper around `get_exchange_details_async()`.

### `get_exchange_details_async(exchange, *, endpoint=..., timeout=60, http_proxy=None)`

Use `get_exchange_details_async()` inside an existing `asyncio` event loop when you need exchange metadata without blocking on the synchronous wrapper.

| name         | type               | default                     | description                          |
| ------------ | ------------------ | --------------------------- | ------------------------------------ |
| `exchange`   | string             | -                           | exchange id to query, e.g. `binance` |
| `endpoint`   | string (optional)  | `https://api.tardis.dev/v1` | override HTTP API endpoint           |
| `timeout`    | integer (optional) | `60`                        | HTTP timeout in seconds              |
| `http_proxy` | string (optional)  | `None`                      | HTTP proxy URL passed to `aiohttp`   |

## Other Public Exports

```python
from tardis_dev import Response, default_file_name
```

* `Response` is the public `NamedTuple` returned by `replay()`. See [Replaying Historical Data](https://docs.tardis.dev/replaying-historical-data#type-of-messages-returned-by-replay) for details.
* `default_file_name(exchange, data_type, date, symbol, format)` is the default helper used by `download_datasets()` and `download_datasets_async()` to build output file names.