{"id":8698,"library":"tardis-dev","title":"Tardis.dev Python Client","description":"The `tardis-dev` Python client (version 4.0.0) provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: replaying historical market data and downloading historical market data as CSV files. The library is actively maintained with regular updates.","status":"active","version":"4.0.0","language":"en","source_language":"en","source_url":"https://github.com/tardis-dev/tardis-python","tags":["cryptocurrency","market data","historical data","API client","async"],"install":[{"cmd":"pip install tardis-dev","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for execution.","package":"python","optional":false}],"imports":[{"note":"`tardis-client` is deprecated; `replay` is now a top-level function in `tardis_dev`.","wrong":"from tardis_client import replay","symbol":"replay","correct":"from tardis_dev import replay"},{"symbol":"Channel","correct":"from tardis_dev import Channel"},{"note":"`download_datasets` is now a top-level function in `tardis_dev` as of v3 API.","wrong":"from tardis_dev.datasets import download_datasets","symbol":"download_datasets","correct":"from tardis_dev import download_datasets"}],"quickstart":{"code":"import asyncio\nimport os\nfrom tardis_dev import Channel, replay\n\nasync def main():\n    api_key = os.environ.get('TARDIS_API_KEY', '') # Optional for some free tiers\n    if not api_key:\n        print(\"Warning: TARDIS_API_KEY not set. Data may be limited to free samples.\")\n    \n    print(\"Replaying historical trade and depth data...\")\n    async for local_timestamp, message in replay(\n        exchange=\"binance\",\n        from_date=\"2024-03-01\",\n        to_date=\"2024-03-02\",\n        filters=[Channel(\"trade\", [\"btcusdt\"]), Channel(\"depth\", [\"btcusdt\"])],\n        api_key=api_key,\n    ):\n        print(f\"{local_timestamp}: {message['type']} for {message.get('symbol', 'N/A')}\")\n        # Process first 5 messages and break for brevity\n        if main.counter < 5:\n            main.counter += 1\n        else:\n            break\n\n    print(\"\\nDownloading historical CSV datasets...\")\n    from tardis_dev import download_datasets\n    try:\n        download_datasets(\n            exchange=\"binance\",\n            data_types=[\"trades\"],\n            symbols=[\"BTCUSDT\"], # Note: Symbols here are typically uppercase for datasets API\n            from_date=\"2024-03-01\",\n            to_date=\"2024-03-02\",\n            api_key=api_key,\n            download_dir=\"./tardis_datasets_quickstart\",\n            skip_if_exists=True\n        )\n        print(\"Download initiated. Check ./tardis_datasets_quickstart directory.\")\n    except Exception as e:\n        print(f\"Could not initiate download (API key issue or no data?): {e}\")\n\nmain.counter = 0\nasyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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(...)`.","message":"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.","severity":"breaking","affected_versions":"<4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"If calling from an `async` context, use the asynchronous version `download_datasets_async()` instead.","message":"The synchronous `download_datasets()` function cannot be called from within an existing asynchronous event loop. Attempting to do so will raise a `RuntimeError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `from tardis_dev import download_datasets_async` and call `await download_datasets_async(...)` when operating inside an `async` function.","cause":"Attempting to call the synchronous `download_datasets` function from within an `asyncio` event loop.","error":"RuntimeError: download_datasets() cannot be called from a running event loop"},{"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.","cause":"The `tardis_client` package is an older, deprecated version of the client library. New development has moved to `tardis-dev`.","error":"ModuleNotFoundError: No module named 'tardis_client'"},{"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.","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.","error":"Entitlement error (or similar message indicating no access/data)"},{"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.","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.","error":"No data returned for specified symbol/channel"}]}