[](https://www.python.org/downloads/release/python-3102/)
[](https://github.com/psf/black)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/duneanalytics/dune-client/actions/workflows/pull-request.yaml)
# Dune Client
A python framework for interacting with Dune Analytics' [officially supported API
service](https://docs.dune.com/api-reference/overview/introduction).
## Installation
Import as a project dependency
```shell
pip install dune-client
```
# Example Usage
## Quickstart: run_query
Export your `DUNE_API_KEY` (or place it in a `.env` file - as in
here [.env.sample](./.env.sample) and `source .env`).
```python
from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase
query = QueryBase(
name="Sample Query",
query_id=1215383,
params=[
QueryParameter.text_type(name="TextField", value="Word"),
QueryParameter.number_type(name="NumberField", value=3.1415926535),
QueryParameter.date_type(name="DateField", value="2022-05-04 00:00:00"),
QueryParameter.enum_type(name="ListField", value="Option 1"),
],
)
print("Results available at", query.url())
dune = DuneClient.from_env()
results = dune.run_query(query)
# or as CSV
# results_csv = dune.run_query_csv(query)
# or as Pandas Dataframe
# results_df = dune.run_query_dataframe(query)
```
## Further Examples
### Get Latest Results
Use `get_latest_results` to get the most recent query results without using execution credits.
You can specify a `max_age_hours` to re-run the query if the data is too outdated.
```python
from dune_client.client import DuneClient
dune = DuneClient.from_env()
results = dune.get_latest_result(1215383, max_age_hours=8)
```
## Paid Subscription Features
### CRUD Operations
If you're writing scripts that rely on Dune query results and want to ensure that your local,
peer-reviewed, queries are being used at runtime, you can call `update_query` before `run_query`!
Here is a fictitious example making use of this functionality;
```python
from dune_client.types import QueryParameter
from dune_client.client import DuneClient
sql = """
SELECT block_time, hash,
FROM ethereum.transactions
ORDER BY CAST(gas_used as uint256) * CAST(gas_price AS uint256) DESC
LIMIT {{N}}
"""
dune = DuneClient.from_env()
query = dune.create_query(
name="Top {N} Most Expensive Transactions on Ethereum",
query_sql=sql,
# Optional fields
params=[QueryParameter.number_type(name="N", value=10)],
is_private=False # default
)
query_id = query.base.query_id
print(f"Created query with id {query.base.query_id}")
# Could retrieve using
# dune.get_query(query_id)
dune.update_query(
query_id,
# All parameters below are optional
name="Top {N} Most Expensive Transactions on {Blockchain}",
query_sql=sql.replace("ethereum", "{{Blockchain}}"),
params=query.base.parameters() + [QueryParameter.text_type("Blockchain", "ethereum")],
description="Shows time and hash of the most expensive transactions",
tags=["XP€N$IV $H1T"]
)
dune.archive_query(query_id)
dune.unarchive_query(query_id)
dune.make_private(query_id)
dune.make_public(query_id)
```
# Developer Usage & Deployment
## Makefile
This project's makefile comes equipped with sufficient commands for local development.
### Installation
```shell
make install
````
### Format, Lint & Types
```shell
make check
```
can also be run individually with `fmt`, `lint` and `types` respectively.
### Testing
```shell
make test-unit # Unit tests
make test-e2e # Requires valid `DUNE_API_KEY`
```
can also run both with `make test-all`
## Deployment
Publishing releases to PyPi is configured automatically via github actions
(cf. [./.github/workflows/py-publish.yaml](./.github/workflows/py-publish.yaml)).
Any time a branch is tagged for release this workflow is triggered and published with the same version name.
Raw data
{
"_id": null,
"home_page": "https://github.com/duneanalytics/dune-client",
"name": "dune-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Benjamin H. Smith & Dune Analytics",
"author_email": "ben@cow.fi",
"download_url": "https://files.pythonhosted.org/packages/8d/f9/63ccb0fe75e4c5e261f4ccff46908bdd11fd11036ddbabb0a2a4d34582e2/dune_client-1.7.10.tar.gz",
"platform": null,
"description": "[](https://www.python.org/downloads/release/python-3102/)\n[](https://github.com/psf/black)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/duneanalytics/dune-client/actions/workflows/pull-request.yaml)\n\n# Dune Client\n\nA python framework for interacting with Dune Analytics' [officially supported API\nservice](https://docs.dune.com/api-reference/overview/introduction).\n\n## Installation\n\nImport as a project dependency\n\n```shell\npip install dune-client\n```\n\n# Example Usage\n\n## Quickstart: run_query\n\nExport your `DUNE_API_KEY` (or place it in a `.env` file - as in\nhere [.env.sample](./.env.sample) and `source .env`).\n\n```python\nfrom dune_client.types import QueryParameter\nfrom dune_client.client import DuneClient\nfrom dune_client.query import QueryBase\n\nquery = QueryBase(\n name=\"Sample Query\",\n query_id=1215383,\n params=[\n QueryParameter.text_type(name=\"TextField\", value=\"Word\"),\n QueryParameter.number_type(name=\"NumberField\", value=3.1415926535),\n QueryParameter.date_type(name=\"DateField\", value=\"2022-05-04 00:00:00\"),\n QueryParameter.enum_type(name=\"ListField\", value=\"Option 1\"),\n ],\n)\nprint(\"Results available at\", query.url())\n\ndune = DuneClient.from_env()\nresults = dune.run_query(query)\n\n# or as CSV\n# results_csv = dune.run_query_csv(query)\n\n# or as Pandas Dataframe\n# results_df = dune.run_query_dataframe(query)\n```\n\n## Further Examples\n\n### Get Latest Results\nUse `get_latest_results` to get the most recent query results without using execution credits. \nYou can specify a `max_age_hours` to re-run the query if the data is too outdated.\n\n```python\nfrom dune_client.client import DuneClient\n\ndune = DuneClient.from_env()\nresults = dune.get_latest_result(1215383, max_age_hours=8)\n```\n\n## Paid Subscription Features\n\n### CRUD Operations\n\nIf you're writing scripts that rely on Dune query results and want to ensure that your local, \npeer-reviewed, queries are being used at runtime, you can call `update_query` before `run_query`!\n\nHere is a fictitious example making use of this functionality;\n\n```python\nfrom dune_client.types import QueryParameter\nfrom dune_client.client import DuneClient\n\nsql = \"\"\"\n SELECT block_time, hash,\n FROM ethereum.transactions\n ORDER BY CAST(gas_used as uint256) * CAST(gas_price AS uint256) DESC\n LIMIT {{N}}\n \"\"\"\n\ndune = DuneClient.from_env()\nquery = dune.create_query(\n name=\"Top {N} Most Expensive Transactions on Ethereum\",\n query_sql=sql,\n # Optional fields\n params=[QueryParameter.number_type(name=\"N\", value=10)],\n is_private=False # default\n)\nquery_id = query.base.query_id\nprint(f\"Created query with id {query.base.query_id}\")\n# Could retrieve using \n# dune.get_query(query_id)\n\ndune.update_query(\n query_id, \n # All parameters below are optional\n name=\"Top {N} Most Expensive Transactions on {Blockchain}\",\n query_sql=sql.replace(\"ethereum\", \"{{Blockchain}}\"),\n params=query.base.parameters() + [QueryParameter.text_type(\"Blockchain\", \"ethereum\")],\n description=\"Shows time and hash of the most expensive transactions\",\n tags=[\"XP\u20acN$IV $H1T\"]\n)\n\ndune.archive_query(query_id)\ndune.unarchive_query(query_id)\n\ndune.make_private(query_id)\ndune.make_public(query_id)\n```\n\n# Developer Usage & Deployment\n\n## Makefile\nThis project's makefile comes equipped with sufficient commands for local development.\n\n### Installation\n\n```shell\nmake install\n````\n\n### Format, Lint & Types\n```shell\nmake check\n```\ncan also be run individually with `fmt`, `lint` and `types` respectively. \n\n### Testing\n```shell\nmake test-unit # Unit tests \nmake test-e2e # Requires valid `DUNE_API_KEY`\n```\ncan also run both with `make test-all`\n\n## Deployment\n\nPublishing releases to PyPi is configured automatically via github actions \n(cf. [./.github/workflows/py-publish.yaml](./.github/workflows/py-publish.yaml)).\nAny time a branch is tagged for release this workflow is triggered and published with the same version name.\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0",
"summary": "A simple framework for interacting with Dune Analytics official API service.",
"version": "1.7.10",
"project_urls": {
"Homepage": "https://github.com/duneanalytics/dune-client",
"Tracker": "https://github.com/duneanalytics/dune-client/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc1dac85be00ba1808e3031f85d192633648581fe7569ee016e03634cc0a5313",
"md5": "1c99cfcd881d530cbaba870f7b3dff53",
"sha256": "f0754cc73e59cd4c406505c3a3d0b6b2f9cfedf72ee643af6ded846a7cd00345"
},
"downloads": -1,
"filename": "dune_client-1.7.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c99cfcd881d530cbaba870f7b3dff53",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37843,
"upload_time": "2025-07-10T08:26:47",
"upload_time_iso_8601": "2025-07-10T08:26:47.726262Z",
"url": "https://files.pythonhosted.org/packages/dc/1d/ac85be00ba1808e3031f85d192633648581fe7569ee016e03634cc0a5313/dune_client-1.7.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8df963ccb0fe75e4c5e261f4ccff46908bdd11fd11036ddbabb0a2a4d34582e2",
"md5": "69dec1fa30cd5975f5a058fb91cedd24",
"sha256": "88a9315eae68dc7c0fd89e42b77e28e99a5317e477f014f8291280b04adeba1e"
},
"downloads": -1,
"filename": "dune_client-1.7.10.tar.gz",
"has_sig": false,
"md5_digest": "69dec1fa30cd5975f5a058fb91cedd24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 43531,
"upload_time": "2025-07-10T08:26:49",
"upload_time_iso_8601": "2025-07-10T08:26:49.316770Z",
"url": "https://files.pythonhosted.org/packages/8d/f9/63ccb0fe75e4c5e261f4ccff46908bdd11fd11036ddbabb0a2a4d34582e2/dune_client-1.7.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 08:26:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duneanalytics",
"github_project": "dune-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dune-client"
}
JSON
