Dune Analytics API

Dune Analytics API

A skill for querying and analyzing blockchain data via the Dune Analytics API.

Setup

pip install dune-client

Set DUNE_API_KEY via environment variable, .env file, or agent config.

⚠️ Usage Rules

1. Read before writing SQL — Select and read the relevant reference files (see Reference Selection) before writing any query. Do not skip this step.
2. Prefer Private Queries — Try is_private=True first. Fall back to public if it fails (free plan), and notify the user.
3. Don't create duplicates — Reuse/update existing queries unless explicitly asked to create new ones.
4. Confirm before updating — Ask the user before modifying an existing query.
5. Track credits — Report credits consumed after each execution. See query-execution.md.

Reference Selection

Before writing any SQL, route to the correct reference file(s) based on your task:

If your task spans multiple categories, read all relevant files. Do not guess table names or query patterns — the references contain critical details (e.g., specialized tables, anti-patterns) that are not covered in this overview.

Quick Start

from dune_client.client import DuneClient
from dune_client.query import QueryBase
import os

client = DuneClient(api_key=os.environ['DUNE_API_KEY'])

# Execute a query
result = client.run_query(query=QueryBase(query_id=123456), performance='medium', ping_frequency=5)
print(f"Rows: {len(result.result.rows)}")

# Get cached result (no re-execution)
result = client.get_latest_result(query_id=123456)

# Get/update SQL
sql = client.get_query(123456).sql
client.update_query(query_id=123456, query_sql="SELECT ...")

# Upload CSV data (quick, overwrites existing)
client.upload_csv(
    data="col1,col2\nval1,val2",
    description="My data",
    table_name="my_table",
    is_private=True
)

# Create table + insert (supports append)
client.create_table(
    namespace="my_user",
    table_name="my_table",
    schema=[{"name": "col1", "type": "varchar"}, {"name": "col2", "type": "double"}],
    is_private=True
)
import io
client.insert_data(
    namespace="my_user",
    table_name="my_table",
    data=io.BytesIO(b"col1,col2\nabc,1.5"),
    content_type="text/csv"
)

Subscription Tiers

Key Concepts

dex.trades vs dex_aggregator.trades

⚠️ For wallet/address analysis, use dex_aggregator.trades with tx_to matching router addresses from dune.lz_web3.dataset_crypto_wallet_router. Do not use labels.all for wallet router lookups. See wallet-analysis.md for full patterns.

Solana has no dex_aggregator_solana.trades. Dedupe by tx_id:

SELECT tx_id, MAX(amount_usd) as amount_usd
FROM dex_solana.trades
GROUP BY tx_id

Data Freshness

Query previous day's data after UTC 12:00 for completeness.

References

Detailed documentation is organized in the references/ directory: