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.9.

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

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.