Quickstart

Install, configure and get started with the tardis-dev Python package

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

• CSV dataset downloads

If you're migrating older Python code that used tardis-client, TardisClient or from tardis_dev import datasets, start with Migration Notice.

GitHub - tardis-dev/tardis-python: Python client for tardis.dev - historical tick-level cryptocurrency market data replay API.GitHub

Python tardis-dev GitHub repository

Installation

Requires Python >=3.10.

pip install tardis-dev

Historical Replay

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 for replay arguments, Channel filters, disconnect events and cache behavior.

Replaying Historical Data

CSV Dataset Downloads

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

If you're calling from an existing event loop, use download_datasets_async() instead of download_datasets().

See also Downloadable CSV files docs.

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

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(
    ["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 after the symbol appears in exported dataset metadata. It can query a single symbol, a single exchange with a filter, or multiple exchanges with the same filter.

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 with normalized criteria and returns the correct exchange-specific id for each requested exchange, ready to pass to replay or raw data feeds.

from tardis_dev import find_instrument_symbols

symbols_by_exchange = find_instrument_symbols(
    ["binance-futures", "okex-swap", "bybit"],
    {
        "baseCurrency": "BTC",
        "quoteCurrency": "USDT",
        "contractType": "linear_perpetual",
        "active": True,
    },
    api_key="YOUR_API_KEY",
)

print(symbols_by_exchange)
# [
#   {"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:

csv_symbols_by_exchange = find_instrument_symbols(
    ["binance-futures", "okex-swap", "bybit"],
    {
        "baseCurrency": "BTC",
        "quoteCurrency": "USDT",
        "contractType": "linear_perpetual",
        "active": True,
    },
    selector="datasetId",
    api_key="YOUR_API_KEY",
)

Returned id symbols are exchange-provided IDs and are not normalized by the client. Returned datasetId symbols are CSV dataset IDs for instruments whose symbols appear in exported dataset metadata; download_datasets() URL-encodes them when constructing dataset URLs. Use find_instrument_symbols_async() inside an existing asyncio event loop.

Other Public Exports

from tardis_dev import Response, default_file_name

• Response is the public NamedTuple returned by replay(). See Replaying Historical Data 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.