Dune Client
A python framework for interacting with Dune Analytics' officially supported API service.
Installation
Using uv (recommended)
uv is a fast Python package and project manager written in Rust. It provides:
- ⚡ 10-100x faster dependency resolution
- 🔒 Reproducible builds with lockfiles
- 🐍 Automatic Python version management
- 📦 Zero-configuration virtual environments
Install uv first, then:
# Add to an existing project
uv add dune-client
# Or create a new project
uv init my-dune-project
cd my-dune-project
uv add dune-client
Using pip
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 and source .env).
💡 Tip: If using uv, you can run examples directly without activating a virtual environment:
uv run python your_script.py
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()
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.
from dune_client.client import DuneClient
dune = DuneClient()
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;
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()
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
This project uses uv for dependency management and development workflows.
Setup
# Clone the repository
git clone https://github.com/duneanalytics/dune-client.git
cd dune-client
# Install dependencies
uv sync --dev
Development Commands
# Format code
uv run ruff format
# Lint code
uv run ruff check
# Type checking
uv run mypy dune_client/ --strict
# Run tests
uv run python -m pytest tests/unit # Unit tests
uv run python -m pytest tests/e2e # E2E tests (requires DUNE_API_KEY)
Multi-Python Testing
This project supports Python 3.11, 3.12, and 3.13. You can test across all versions using tox with uv:
# Test all Python versions with tox
uv run tox
# or
make test-tox
# Test specific Python versions
uv run tox -e py311
uv run tox -e py312
uv run tox -e py313
Makefile Shortcuts
Installation
make install # Uses uv sync
# or
make install-dev # Uses uv sync --dev
Format, Lint & Types
make check
can also be run individually with fmt, lint and types respectively.
Testing
make test-unit # Unit tests
make test-e2e # Requires valid `DUNE_API_KEY`
make test-all # Both unit and e2e tests
make test-tox # Multi-Python testing (py311, py312, py313)
Deployment
Publishing releases to PyPi is configured automatically via github actions (cf. ./.github/workflows/py-publish.yaml). Any time a branch is tagged for release this workflow is triggered and published with the same version name.
Release files for dune-client 1.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dune_client-1.12.0.tar.gz | 145.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dune_client-1.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 190.4 kB
Release files / dune_client-1.12.0.tar.gz
| Download URL | dune_client-1.12.0.tar.gz |
|---|---|
| Size | 145.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36af3c842ec5086cd5dfe1871f31c2990e5b66c71089efe560a18c2b74dd688e
|
|
BLAKE2b-256 checksum How to use checksums |
2328c32a140c15f0a334c7051e1d614e355ca24ed4940807422b472a825b38d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logRelease files / dune_client-1.12.0-py3-none-any.whl
| Download URL | dune_client-1.12.0-py3-none-any.whl |
|---|---|
| Size | 44.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31f29ea92d753ccb94a8bfa882a15af37548ae533fa4ba907110903753b9f70c
|
|
BLAKE2b-256 checksum How to use checksums |
110b31b861cd3cec3616cd09db304337f56442382938a4e5f596ec3c1466f8ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency log
