Tardis.dev Python Client

Common errors

• ConnectionResetError: [Errno 54] Connection reset by peer OR EOFError: Read up to 0 bytes from peer

  cause These errors often occur when the Python `asyncio` event loop is blocked by synchronous (blocking) I/O operations, such as writing to files, preventing the network connection from being properly maintained.
  fix Replace blocking file operations with their asynchronous equivalents (e.g., using `aiofiles`) or ensure I/O is offloaded to a separate thread/process to keep the `asyncio` event loop responsive. Clear the `.tardis-cache` directory.

• HTTP status 401 Unauthorized

  cause The API key provided is either missing, invalid, or does not have sufficient permissions for the requested data. For full historical data, an API key is always required.
  fix Ensure you have a valid Tardis.dev API key. Pass it correctly to the `TardisClient` constructor using the `api_key` argument, or set it as the `TARDIS_API_KEY` environment variable. Verify the API key's permissions on the Tardis.dev website.

Warnings

• breaking The `tardis-client` package is deprecated and frozen. No new features will be added, and future Python development continues under the `tardis-dev` package. Existing users should migrate.
  Fix: Uninstall `tardis-client` (`pip uninstall tardis-client`) and install the new client (`pip install tardis-dev`). Update your import statements and usage patterns according to the migration guide: `https://docs.tardis.dev/python-client/migration-notice`.
• gotcha Access to full historical data requires a Tardis.dev API key. Without one, only the first day of each month is accessible.
  Fix: Obtain an API key from Tardis.dev and pass it to the `TardisClient` constructor (or set the `TARDIS_API_KEY` environment variable). For `tardis-dev`, pass it directly to `replay()` or `download_datasets()`.
• gotcha Performing blocking I/O operations (e.g., synchronous file writes) within the `asyncio` event loop used by `tardis-client` can cause `ConnectionResetError` or `EOFError` due to the event loop being blocked, leading to network connection timeouts.
  Fix: Ensure all I/O operations (especially file writes during data processing) are non-blocking or use asynchronous libraries (e.g., `aiofiles`) to avoid blocking the event loop. Clear the local `.tardis-cache` if issues persist.
• gotcha The local file cache (`<os.tmpdir>/.tardis-cache` by default) can grow significantly, consuming disk space, especially during large historical data backfills.
  Fix: Regularly clear the cache using `tardis_client.clear_cache()` or configure a specific `cache_dir` that can be managed manually. The newer `tardis-machine` (Node.js component, not this Python client) offers `autoCleanup: true` for clearing cache after replay.

Install

• pip install tardis-client Install `tardis-client` (deprecated)
• pip install tardis-dev Install `tardis-dev` (recommended replacement)

Imports

• TardisClient
  wrong:

  from tardis_dev import TardisClient

  correct:

  from tardis_client import TardisClient

  TardisClient is specific to the deprecated 'tardis-client' package. The replacement 'tardis-dev' uses a top-level `replay` function instead.
• Channel
  wrong:

  from tardis_dev.client import Channel

  correct:

  from tardis_client import Channel

  While 'Channel' exists in both, its usage pattern and containing package for replay functions differ in the new 'tardis-dev' package. For 'tardis-dev', 'Channel' is imported directly from 'tardis_dev'.

Quickstart

This quickstart demonstrates how to use the deprecated `tardis-client` to replay historical market data for BitMEX. It fetches trades for 'XBTUSD' and 'ETHUSD', and Level 2 order book data for 'XBTUSD' for a specific date range. An API key is typically required for full access to historical data.

import asyncio
import os
from tardis_client import TardisClient, Channel

async def replay_data():
    api_key = os.environ.get('TARDIS_API_KEY', '')
    
    # Note: For full historical access, an API key is required.
    # Without an API key, only the first day of each month is accessible.
    # The cache_dir is optional; default is os.tmpdir/.tardis-cache.
    tardis_client = TardisClient(api_key=api_key, cache_dir="./tardis_cache")

    print("Replaying BitMEX trades and order book for 2019-06-01...")
    messages = tardis_client.replay(
        exchange="bitmex",
        from_date="2019-06-01",
        to_date="2019-06-02", # Non-inclusive end date
        filters=[
            Channel(name="trade", symbols=["XBTUSD", "ETHUSD"]),
            Channel("orderBookL2", ["XBTUSD"])
        ],
    )

    message_count = 0
    async for local_timestamp, message in messages:
        # local_timestamp is a Python datetime object
        # message is the raw message object from the exchange real-time stream
        if message_count < 5: # Print first 5 messages as an example
            print(f"[{local_timestamp}] {message['symbol']}: {message['data_type']}")
        message_count += 1
        
    print(f"\nFinished replaying. Total messages received: {message_count}")
    # Optionally clear the cache
    # tardis_client.clear_cache()

if __name__ == "__main__":
    # Set your API key as an environment variable or pass it directly
    # os.environ['TARDIS_API_KEY'] = 'YOUR_TARDIS_API_KEY'
    asyncio.run(replay_data())