{"id":19145390,"url":"https://github.com/paradigmxyz/spice","last_synced_at":"2025-05-16T00:08:51.747Z","repository":{"id":248900135,"uuid":"829157468","full_name":"paradigmxyz/spice","owner":"paradigmxyz","description":"Simple client for extracting data from the Dune Analytics API","archived":false,"fork":false,"pushed_at":"2025-02-06T00:20:28.000Z","size":123,"stargazers_count":194,"open_issues_count":1,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-13T18:06:32.234Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paradigmxyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2024-07-15T21:57:06.000Z","updated_at":"2025-04-18T22:59:37.000Z","dependencies_parsed_at":"2024-11-09T07:40:07.737Z","dependency_job_id":"ce7aa69f-b9ec-4cb3-bd26-1d8daa2e7b42","html_url":"https://github.com/paradigmxyz/spice","commit_stats":{"total_commits":73,"total_committers":5,"mean_commits":14.6,"dds":0.0547945205479452,"last_synced_commit":"e962a9c435d2f990fe5684d6a876a8b13287f5ee"},"previous_names":["paradigmxyz/spice"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fspice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fspice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fspice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paradigmxyz%2Fspice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paradigmxyz","download_url":"https://codeload.github.com/paradigmxyz/spice/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442854,"owners_count":22071878,"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":[],"created_at":"2024-11-09T07:39:57.996Z","updated_at":"2025-05-16T00:08:46.708Z","avatar_url":"https://github.com/paradigmxyz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spice 🌶️\n\nSimple client for extracting data from the [Dune Analytics API](https://docs.dune.com/api-reference/overview/introduction)\n\nGoals of `spice`:\n- use as a python library or as a CLI tool\n- simple, no OOP, entire API is just one function\n- support both sync and async workflows\n- tight integration with [polars](https://github.com/pola-rs/polars)\n\nTo discuss `spice`, head to the [Paradigm Data Tools](https://t.me/paradigm_data) Telegram channel.\n\n## Table of Contents\n1. [Installation](#installation)\n2. [Examples](#examples)\n    1. [Sync Workflow](#sync-workflow)\n    2. [Async Workflow](#async-workflow)\n    3. [Command Line Workflow](#command-line-workflow)\n    4. [Quality of Life](#quality-of-life)\n3. [API Reference](#api-reference)\n    1. [Python Reference](#python-reference)\n    2. [Command Line Reference](#command-line-reference)\n4. [FAQ](#faq)\n\n## Installation\n\n`pip install dune_spice`\n\n## Examples\n\nCan either use the sync workflow or async workflow. Each workflow has only one function.\n\nSee [API Reference](#api-reference) below for the full list of query function arguments.\n\n### Sync Workflow\n\n```python\nimport spice\n\n# get most recent query results using query id\ndf = spice.query(21693)\n\n# get most recent query results using query url\ndf = spice.query('https://dune.com/queries/21693')\n\n# get most recent query results using raw sql\ndf = spice.query('SELECT * FROM ethereum.blocks LIMIT 5')\n\n# perform new query execution and get results\ndf = spice.query(query, refresh=True)\n\n# get query results for input parameters\ndf = spice.query(query, parameters={'network': 'ethereum'})\n\n# perform new query execution, but do not wait for result\nexecution = spice.query(query, poll=False)\n\n# get results of previous execution\ndf = spice.query(execution)\n```\n\n### Async Workflow\n\nThe async API is identical to the sync API as above, just add `async_` prefix.\n\n```python\ndf = await spice.async_query(21693)\ndf = await spice.async_query('https://dune.com/queries/21693')\ndf = await spice.async_query('SELECT * FROM ethereum.blocks LIMIT 5')\ndf = await spice.async_query(query, refresh=True)\ndf = await spice.async_query(query, parameters={'network': 'ethereum'})\nexecution = spice.query(query, poll=False)\ndf = await spice.async_query(execution)\n```\n\n### Command Line Workflow\n\nRunning the `spice` CLI will 1) extract the given query, 2) preview the contents, 3) and save it to a file. Each step of this process can be customized using the CLI options.\n\n```bash\nspice 21693\nspice https://dune.com/queries/21693\nspice \"SELECT * FROM ethereum.blocks LIMIT 5\"\nspice $QUERY --refresh\nspice $QUERY --parameters network=ethereum\n```\n\n### Quality of Life\n\n`spice` contains additional quality of life features such as:\n- automatically cache results locally to save time and credits for repeated queries\n- automatically handle pagination of multi-page results\n- automatically execute queries that have no existing executions, especially when using new parameter values\n- allow type overrides using the `types` parameter\n- support raw dynamic querying using parameter templates in order to 1) minimize roundtrips and 2) not require a paid API plan\n- auto-retry with exponential backoff when encountering HTTP429 ratelimit errors\n\n## API Reference\n\n#### Python Reference\n\nThese python functions are accessed as `spice.query()` and `spice.async_query()`.\n\n```python\ndef query(\n    query_or_execution: Query | Execution,\n    *,\n    verbose: bool = True,\n    refresh: bool = False,\n    max_age: int | float | None = None,\n    parameters: Mapping[str, Any] | None = None,\n    api_key: str | None = None,\n    performance: Performance = 'medium',\n    poll: bool = True,\n    poll_interval: float = 1.0,\n    limit: int | None = None,\n    offset: int | None = None,\n    sample_count: int | None = None,\n    sort_by: str | None = None,\n    columns: Sequence[str] | None = None,\n    extras: Mapping[str, Any] | None = None,\n    types: Sequence[pl.DataType] | None = None,\n    cache: bool = True,\n    cache_dir: str | None = None,\n    save_to_cache: bool = True,\n    load_from_cache: bool = True,\n) -\u003e pl.DataFrame | Execution:\n    \"\"\"get results of query as dataframe\n\n    # Parameters\n    - query_or_execution: query or execution to retrieve results of\n    - verbose: whether to print verbose info\n    - refresh: trigger a new execution, or just use most recent execution\n    - max_age: max age of last execution in seconds, or trigger a new execution\n    - parameters: dict of query parameters\n    - api_key: dune api key, otherwise use DUNE_API_KEY env var\n    - performance: performance level\n    - poll: wait for result as DataFrame, or just return Execution handle\n    - poll_interval: polling interval in seconds\n    - limit: number of rows to query in result\n    - offset: row number to start returning results from\n    - sample_count: number of random samples from query to return\n    - sort_by: an ORDER BY clause to sort data by\n    - columns: columns to retrieve, by default retrieve all columns\n    - extras: extra parameters used for fetching execution result\n        - examples: ignore_max_datapoints_per_request, allow_partial_results\n    - types: column types to use in output polars dataframe\n    - cache: whether to use cache for saving or loading\n    - cache_dir: directory to use for cached data (create tmp_dir if None)\n    - save_to_cache: whether to save to cache, set false to load only\n    - load_from_cache: whether to load from cache, set false to save only\n    - include_execution: return Execution metadata alongside query result\n    \"\"\"\n    ...\n\nasync def async_query(\n    # all the same parameters as query()\n    ...\n) -\u003e pl.DataFrame | Execution:\n    \"\"\"get results of query as dataframe, asynchronously\n\n    ## Parameters\n    [see query()]\n    \"\"\"\n    ...\n```\n\n#### Command Line Reference\n\n![image](https://github.com/user-attachments/assets/aca9c2a1-1487-461f-ab2f-8e7a4930b71a)\n\n\n## FAQ\n\n#### How do I set my Dune API key?\n\nSet your API key using one of these approaches:\n\n1. **specify key for all sessions:** set the `DUNE_API_KEY` environment variable (e.g. write export `DUNE_API_KEY=your-api-key` in your `~/.bash_profile`)\n2. **specify key for single session:** set the `DUNE_API_KEY` entry in python's `os.environ` (e.g. `os.environ['DUNE_API_KEY'] = your-api-key`)\n3. **specify key for query:** in python use the `api_key` argument (`df = query(api_key='your-api-key', ...)`) or for cli use the `--api-key` argument (`spice --api-key your-api-key ...`)\n\n#### How do I obtain a Dune API key?\n\n1. Create a Dune account\n2. Go to Settings --\u003e API\n3. Click \"Create new API key\"\n\n#### Does `spice` work with a Dune free account?\n\nYes. But to fetch the result of large queries, you may need to remove the \"250k datapoints per request\" limitation in your account settings on the Dune website.\n\n#### Which endpoints does this package support?\n\n`spice` interacts only with Dune's SQL-related API endpoints, documented [here](https://docs.dune.com/api-reference/executions/execution-object).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadigmxyz%2Fspice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparadigmxyz%2Fspice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparadigmxyz%2Fspice/lists"}