Tardis.dev Python Client

Common errors

• RuntimeError: download_datasets() cannot be called from a running event loop

  cause Attempting to call the synchronous `download_datasets` function from within an `asyncio` event loop.
  fix Use `from tardis_dev import download_datasets_async` and call `await download_datasets_async(...)` when operating inside an `async` function.

• ModuleNotFoundError: No module named 'tardis_client'

  cause The `tardis_client` package is an older, deprecated version of the client library. New development has moved to `tardis-dev`.
  fix Uninstall `tardis-client` (`pip uninstall tardis-client`) and install the new client `tardis-dev` (`pip install tardis-dev`). Update your import statements and function calls according to the migration guide.

• Entitlement error (or similar message indicating no access/data)

  cause This usually indicates an issue with the provided API key, or trying to access data for which the API key does not have a subscription. It can also occur if symbols are omitted for limited-scope plans.
  fix Verify your `TARDIS_API_KEY` is correct and has the necessary permissions for the requested data. Ensure explicit symbols are provided if your subscription has scope limitations.

• No data returned for specified symbol/channel

  cause This can happen due to incorrect symbol casing for the exchange (e.g., `BTCUSDT` vs `btcusdt`), specifying an unsupported channel, or requesting data for a period where no data was collected.
  fix Double-check the exact symbol casing required by the specific exchange as detailed in Tardis.dev documentation. Verify the channel name is correct. Note that empty responses are normal for periods without recorded data.

Warnings

• breaking The `tardis-client` library is deprecated. New development continues in `tardis-dev`, and users must migrate to the new top-level functions and import paths.
  Fix: Uninstall `tardis-client` and install `tardis-dev`. Update code: `TardisClient().replay(...)` becomes `replay(...)` and `from tardis_dev.datasets import download_datasets; datasets.download(...)` becomes `from tardis_dev import download_datasets; download_datasets(...)`.
• gotcha API key usage varies. The first day of each month for historical data feeds and CSV datasets might be available without an API key. For all other data, an API key is required.
  Fix: Ensure `api_key` is provided to `replay` and `download_datasets` functions, preferably via an environment variable `TARDIS_API_KEY`, unless intentionally accessing free sample data.
• gotcha Symbol casing for the `datasets` API (for CSV downloads) versus the `replay` function (for streaming) can differ significantly by exchange. `datasets` typically requires uppercase and URL-safe symbols (e.g., BTCUSDT, replacing '/' with '-'), while `replay` requires exchange-native casing (e.g., Binance uses `btcusdt`).
  Fix: Always consult the Tardis.dev documentation for the specific exchange and API endpoint to determine correct symbol casing and formatting. For `datasets`, ensure symbols are uppercase and URL-safe. For `replay`, use the exact casing provided by the exchange's API.
• gotcha The synchronous `download_datasets()` function cannot be called from within an existing asynchronous event loop. Attempting to do so will raise a `RuntimeError`.
  Fix: If calling from an `async` context, use the asynchronous version `download_datasets_async()` instead.

Install

• pip install tardis-dev Install stable version

Imports

• replay
  wrong:

  from tardis_client import replay

  correct:

  from tardis_dev import replay

  `tardis-client` is deprecated; `replay` is now a top-level function in `tardis_dev`.
• Channel

  from tardis_dev import Channel

• download_datasets
  wrong:

  from tardis_dev.datasets import download_datasets

  correct:

  from tardis_dev import download_datasets

  `download_datasets` is now a top-level function in `tardis_dev` as of v3 API.

Quickstart

This quickstart demonstrates both replaying historical market data and downloading CSV datasets. An API key is typically required for full access, though free samples may be available without one. Replay data is streamed asynchronously, while CSV datasets are downloaded to a specified directory.

import asyncio
import os
from tardis_dev import Channel, replay

async def main():
    api_key = os.environ.get('TARDIS_API_KEY', '') # Optional for some free tiers
    if not api_key:
        print("Warning: TARDIS_API_KEY not set. Data may be limited to free samples.")
    
    print("Replaying historical trade and depth data...")
    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=api_key,
    ):
        print(f"{local_timestamp}: {message['type']} for {message.get('symbol', 'N/A')}")
        # Process first 5 messages and break for brevity
        if main.counter < 5:
            main.counter += 1
        else:
            break

    print("\nDownloading historical CSV datasets...")
    from tardis_dev import download_datasets
    try:
        download_datasets(
            exchange="binance",
            data_types=["trades"],
            symbols=["BTCUSDT"], # Note: Symbols here are typically uppercase for datasets API
            from_date="2024-03-01",
            to_date="2024-03-02",
            api_key=api_key,
            download_dir="./tardis_datasets_quickstart",
            skip_if_exists=True
        )
        print("Download initiated. Check ./tardis_datasets_quickstart directory.")
    except Exception as e:
        print(f"Could not initiate download (API key issue or no data?): {e}")

main.counter = 0
asyncio.run(main())