{"id":13741032,"url":"https://github.com/tardis-dev/tardis-python","last_synced_at":"2026-03-27T04:12:53.510Z","repository":{"id":37910240,"uuid":"202313096","full_name":"tardis-dev/tardis-python","owner":"tardis-dev","description":"Python client for tardis.dev - historical tick-level cryptocurrency market data replay API.","archived":false,"fork":false,"pushed_at":"2024-12-05T08:41:35.000Z","size":201,"stargazers_count":127,"open_issues_count":2,"forks_count":17,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-14T09:29:17.982Z","etag":null,"topics":["cryptocurrency-api","cryptocurrency-prices","historical-data","orderbook","orderbook-tick-data"],"latest_commit_sha":null,"homepage":"https://tardis.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tardis-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-14T08:58:16.000Z","updated_at":"2025-05-07T07:51:58.000Z","dependencies_parsed_at":"2024-11-17T20:01:40.761Z","dependency_job_id":"1ba0cc61-b10b-4840-9a42-53d27cc58332","html_url":"https://github.com/tardis-dev/tardis-python","commit_stats":{"total_commits":57,"total_committers":3,"mean_commits":19.0,"dds":0.03508771929824561,"last_synced_commit":"aae0a4563a28a882004daae5b57b4ce1ddfa86cd"},"previous_names":["tardis-dev/python-client"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tardis-dev%2Ftardis-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tardis-dev%2Ftardis-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tardis-dev%2Ftardis-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tardis-dev%2Ftardis-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tardis-dev","download_url":"https://codeload.github.com/tardis-dev/tardis-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478160,"owners_count":22077675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptocurrency-api","cryptocurrency-prices","historical-data","orderbook","orderbook-tick-data"],"created_at":"2024-08-03T04:00:54.677Z","updated_at":"2025-12-13T19:24:19.637Z","avatar_url":"https://github.com/tardis-dev.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":["Data Sources"],"readme":"# tardis-client\r\n\r\n[![PyPi](https://img.shields.io/pypi/v/tardis-client.svg)](https://pypi.org/project/tardis-client/)\r\n[![Python](https://img.shields.io/pypi/pyversions/tardis-client.svg)](https://pypi.org/project/tardis-client/)\r\n\u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\u003e\u003c/a\u003e\r\n\r\nPython client for [tardis.dev](https://tardis.dev) - historical tick-level cryptocurrency market data replay API.\r\nProvides fast, high level and developer friendly wrapper for more low level [HTTP API](https://docs.tardis.dev/api#http-api) with local file based caching build in.\r\n\r\n## Installation\r\n\r\nRequires Python 3.7.0+ installed.\r\n\r\n```sh\r\npip install tardis-client\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom tardis_client import TardisClient, Channel\r\n\r\nasync def replay():\r\n    tardis_client = TardisClient()\r\n\r\n    # replay method returns Async Generator\r\n    # https://rickyhan.com/jekyll/update/2018/01/27/python36.html\r\n    messages = tardis_client.replay(\r\n        exchange=\"bitmex\",\r\n        from_date=\"2019-06-01\",\r\n        to_date=\"2019-06-02\",\r\n        filters=[Channel(name=\"trade\", symbols=[\"XBTUSD\",\"ETHUSD\"]), Channel(\"orderBookL2\", [\"XBTUSD\"])],\r\n    )\r\n\r\n    # this will print all trades and orderBookL2 messages for XBTUSD\r\n    # and all trades for ETHUSD for bitmex exchange\r\n    # between 2019-06-01T00:00:00.000Z and 2019-06-02T00:00:00.000Z (whole first day of June 2019)\r\n    async for local_timestamp, message in messages:\r\n        # local timestamp is a Python datetime that marks timestamp when given message has been received\r\n        # message is a message object as provided by exchange real-time stream\r\n        print(message)\r\n\r\nasyncio.run(replay())\r\n```\r\n\r\n[![Try on repl.it](https://repl-badge.jajoosam.repl.co/try.png)](https://repl.it/@TardisThad/tardis-python-client-example)\r\n\r\n## API\r\n\r\n`tardis-client` package provides `TardisClient` and `Channel` classes.\r\n\r\n```python\r\nfrom tardis_client import TardisClient, Channel\r\n```\r\n\r\n### TardisClient\r\n\r\nOptional client constructor parameters.\r\n\r\n| name                   | type     | default value               | description                                                                                                                                                     |\r\n| ---------------------- | -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| `api_key` (optional)   | `string` | `\"\"`                        | optional `string` containing API key for [tardis.dev](https://tardis.dev) API. If not provided only first day of each month of data is accessible (free access) |\r\n| `cache_dir` (optional) | `string` | `\u003cos.tmpdir\u003e/.tardis-cache` | optional `string` with path to local dir that will be used as cache location. If not provided default `temp` dir for given OS will be used.                     |\r\n\r\nExample:\r\n\r\n```python\r\n# creates new client instance with access only to sample data (first day of each month)\r\ntardis_client = TardisClient()\r\n\r\n# creates new client with access to all data for given API key\r\ntardis_client = TardisClient(api_key=\"YOUR_API_KEY\")\r\n\r\n# creates new client with custom cache dir\r\ntardis_client = TardisClient(cache_dir=\"./cache\")\r\n```\r\n\r\n- ### `tardis_client.clear_cache()`\r\n\r\n  Removes local file cache dir and it's contents.\r\n\r\n  Example:\r\n\r\n  ```python\r\n  tardis_client = TardisClient()\r\n\r\n  tardis_client.clear_cache()\r\n  ```\r\n\r\n- ### `tardis_client.replay(exchange, from_date, to_date, filters=[])`\r\n\r\n  Replays historical market data messages for given replay arguments.\r\n\r\n  Returns [Async Generator](https://rickyhan.com/jekyll/update/2018/01/27/python36.html) with named tuples (`namedtuple(\"Response\", [\"local_timestamp\", \"message\"])`).\r\n\r\n  - `local_timestamp` is a Python datetime object specyfying when message has been received from the exchange real-time data feed.\r\n\r\n  - `message` is Python dict with parsed JSON that has exactly the same format as message provided by particular exchange's real-time data feed.\r\n\r\n    #### `replay` method parameters:\r\n\r\n    | name                 | type                              | default value | description                                                                                                                                                                                       |\r\n    | -------------------- | --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n    | `exchange`           | `string`                          | -             | requested exchange name - Use [/exchanges](https://docs.tardis.dev/api/http#exchanges) API call to get allowed exchanges ids                                                                      |\r\n    | `from_date`          | `string`                          | -             | requested UTC start date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00`           |\r\n    | `to_date`            | `string`                          | -             | requested UTC end date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00`             |\r\n    | `filters` (optional) | [`List[Channel]`](#channel-class) | []            | optional filters of requested data feed. Use [/exchanges/:exchange](https://docs.tardis.dev/api/http#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\r\n\r\n    ##### `Channel` class\r\n\r\n    `Channel` class constructor parameters.\r\n\r\n    | name      | type           | description                                                                                                                                         |\r\n    | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n    | `name`    | `string`       | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\r\n    | `symbols` | `List[string]` | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\r\n\r\n    ```python\r\n    Channel(name=\"trade\", symbols=[\"XBTUSD\",\"ETHUSD\"])\r\n    Channel(\"orderBookL2\", [\"XBTUSD\"])\r\n    ```\r\n\r\n## FAQ\r\n\r\n#### How to debug it if something went wrong?\r\n\r\n`tardis-client` uses Python logging on `DEBUG` level for that purpose. In doubt please create issue in this repository with steps how to reproduce the issue.\r\n\r\n#### Where can I find more details about tardis.dev API?\r\n\r\nCheck out [API docs](https://docs.tardis.dev/api).\r\n\r\n## License\r\n\r\nMPL-2.0\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftardis-dev%2Ftardis-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftardis-dev%2Ftardis-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftardis-dev%2Ftardis-python/lists"}