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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dune_client-1.12.0.tar.gz (145.8 kB view details)

Uploaded Sep 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

dune_client-1.12.0-py3-none-any.whl (44.6 kB view details)

Uploaded Sep 10, 2026 Python 3

File details

Details for the file dune_client-1.12.0.tar.gz.

File metadata

Download URL: dune_client-1.12.0.tar.gz
Upload date: Sep 10, 2026
Size: 145.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for dune_client-1.12.0.tar.gz
Algorithm	Hash digest
SHA256	`36af3c842ec5086cd5dfe1871f31c2990e5b66c71089efe560a18c2b74dd688e`
MD5	`a40e21bcb90bff02dcf91321ee8c20c9`
BLAKE2b-256	`2328c32a140c15f0a334c7051e1d614e355ca24ed4940807422b472a825b38d0`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dune_client-1.12.0.tar.gz:

Publisher: py-publish.yaml on duneanalytics/dune-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dune_client-1.12.0.tar.gz
- Subject digest: 36af3c842ec5086cd5dfe1871f31c2990e5b66c71089efe560a18c2b74dd688e
- Sigstore transparency entry: 2785701601
- Sigstore integration time: Sep 10, 2026
Source repository:
- Permalink: duneanalytics/dune-client@b4f2b22e8ecd2eb77a5e492ee1f3fd5f8e6d95cb
- Branch / Tag: refs/tags/v1.12.0
- Owner: https://github.com/duneanalytics
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: py-publish.yaml@b4f2b22e8ecd2eb77a5e492ee1f3fd5f8e6d95cb
- Trigger Event: release