# 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](/python-client/replaying-historical-data.md) * [CSV dataset downloads](/downloadable-csv-files/overview.md) {% 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](/python-client/migration-notice.md). {% endhint %} {% embed url="" %} 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](/python-client/replaying-historical-data.md) for replay arguments, `Channel` filters, disconnect events and cache behavior. {% content-ref url="/pages/6dztE6gHE7Lm6xalHDjP" %} [Replaying Historical Data](/python-client/replaying-historical-data.md) {% 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](/downloadable-csv-files/overview.md). ### `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, find_instrument_symbols, get_exchange_details details = get_exchange_details("binance") print(details["availableSymbols"][0]["id"]) symbols_by_exchange = find_instrument_symbols( ["bitmex", "binance-futures", "okex-swap", "bybit"], { "baseCurrency": "BTC", "quoteCurrency": "USDT", "contractType": "linear_perpetual", "active": True, }, api_key="YOUR_API_KEY", ) print(symbols_by_exchange) 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` | ### `get_instrument_info(...)` and `get_instrument_info_async(...)` Use `get_instrument_info()` when you need full instrument metadata such as tick sizes, contract multipliers, base/quote currencies, `id`, and `datasetId`. It can query a single symbol, a single exchange with a filter, or multiple exchanges with the same filter. ```python from tardis_dev import get_instrument_info info = get_instrument_info("binance", symbol="btcusdt", api_key="YOUR_API_KEY") print(info["priceIncrement"]) ``` Use `get_instrument_info_async()` inside an existing `asyncio` event loop. ### `find_instrument_symbols(...)` and `find_instrument_symbols_async(...)` Use this helper when you know the market you want but not each exchange's symbol format. It queries the [Instruments Metadata API](/api/instruments-metadata-api.md) with normalized criteria and returns the correct exchange-specific `id` for each requested exchange, ready to pass to replay or raw data feeds. ```python from tardis_dev import find_instrument_symbols symbols_by_exchange = find_instrument_symbols( ["bitmex", "binance-futures", "okex-swap", "bybit"], { "baseCurrency": "BTC", "quoteCurrency": "USDT", "contractType": "linear_perpetual", "active": True, }, api_key="YOUR_API_KEY", ) print(symbols_by_exchange) # [ # {"exchange": "bitmex", "symbols": ["XBTUSDT"]}, # {"exchange": "binance-futures", "symbols": ["btcusdt"]}, # {"exchange": "okex-swap", "symbols": ["BTC-USDT-SWAP"]}, # {"exchange": "bybit", "symbols": ["BTCUSDT"]}, # ] ``` The optional `selector` keyword defaults to `id`. Pass `selector="datasetId"` only when you need symbols for direct CSV dataset file downloads: ```python csv_symbols_by_exchange = find_instrument_symbols( ["bitmex", "binance-futures", "okex-swap", "bybit"], { "baseCurrency": "BTC", "quoteCurrency": "USDT", "contractType": "linear_perpetual", "active": True, }, selector="datasetId", api_key="YOUR_API_KEY", ) ``` Returned symbols are exchange-provided IDs and are not normalized by the client. Use `find_instrument_symbols_async()` inside an existing `asyncio` event loop. ## Other Public Exports ```python from tardis_dev import Response, default_file_name ``` * `Response` is the public `NamedTuple` returned by `replay()`. See [Replaying Historical Data](/python-client/replaying-historical-data.md#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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tardis.dev/python-client/quickstart.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.