[]

Tardis.dev Documentation

On this page

Copy

On this page

Python Client

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

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

[Logo]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.

Historical Replay

See Replaying Historical Data for replay arguments, Channel filters, disconnect events and cache behavior.

Replaying Historical Data

CSV Dataset Downloads

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

`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

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.

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.

The optional selector keyword defaults to id. Pass selector="datasetId" only when you need symbols for direct CSV dataset file downloads:

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

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.

PreviousData Types

NextReplaying Historical Data

Last updated 1 month ago

Was this helpful?

Quickstart

Features

Installation

Historical Replay

CSV Dataset Downloads

download_datasets(...)

download_datasets_async(...)

Historical Market Data Helpers

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

get_instrument_info(...) and get_instrument_info_async(...)

find_instrument_symbols(...) and find_instrument_symbols_async(...)

Other Public Exports

`download_datasets(...)`

`download_datasets_async(...)`

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

`get_instrument_info(...)` and `get_instrument_info_async(...)`

`find_instrument_symbols(...)` and `find_instrument_symbols_async(...)`