https://github.com/duneanalytics/dune-client
A framework for interacting with Dune Analytics' officially supported API service
https://github.com/duneanalytics/dune-client
api-client dune-analytics web3
Last synced: about 1 year ago
JSON representation
A framework for interacting with Dune Analytics' officially supported API service
- Host: GitHub
- URL: https://github.com/duneanalytics/dune-client
- Owner: duneanalytics
- License: apache-2.0
- Created: 2022-09-01T16:42:29.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-24T12:56:05.000Z (about 1 year ago)
- Last Synced: 2025-06-08T11:45:34.258Z (about 1 year ago)
- Topics: api-client, dune-analytics, web3
- Language: Python
- Homepage:
- Size: 222 KB
- Stars: 110
- Watchers: 16
- Forks: 29
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](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.