Dune Analytics API

Dune Analytics API

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

Local Query Registry Integration (dq)

Some machines maintain a local Dune Query Registry — a git repo of query assets managed by the dq CLI, recognizable by a registry.yaml plus a queries/ directory (the root may also be pointed to by the DQ_ROOT env var).

If such a registry exists, query WRITE operations are hard-constrained to go through dq so local and online copies never drift:

dq push keeps a per-query sync fingerprint and refuses non-fast-forward pushes (remote edited on dune.com since the last sync) — run dq pull <id> to reconcile first. Audit drift anytime with dq sync --all. After running a query and drawing conclusions, record them: dq note <query_id> "...".

READ operations (execute, get_latest, get_sql, table discovery, data uploads) are unrestricted. If no dq registry exists on the machine, this section does not apply.

Setup

pip install dune-client

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

Best Practices

1. Read references first — The reference files contain critical table names, anti-patterns, and chain-specific gotchas that aren't obvious from table names alone. Reading the right reference before writing SQL prevents common mistakes like using dex.trades for wallet analysis (which inflates volume ~30%) or missing Solana's dedup requirement.

2. Prefer private queries — Creating queries with is_private=True keeps the user's workspace clean and avoids polluting the public Dune namespace. Fall back to public if it fails (free plan limitation), and let the user know.

3. Reuse before creating — Dune charges credits per execution. Reusing or updating an existing query avoids unnecessary duplicates and makes credit tracking easier. Only create new queries when the user explicitly asks.

4. Confirm before updating — Modifying an existing query's SQL is destructive (previous version isn't saved by default). A quick confirmation avoids overwriting work the user might want to keep.

5. Track credits — Each execution costs credits depending on the performance tier and data scanned. Reporting credits consumed helps the user manage their budget. See query-execution.md.

Scripts — Common Operations

For common operations, use the scripts in scripts/ to avoid writing boilerplate code every time. All scripts read DUNE_API_KEY from the environment automatically.

Example:

# Execute query with parameters
python scripts/dune_query.py execute --query-id 123456 --params '{"token":"ETH"}' --format table

# Upload a CSV privately
python scripts/dune_upload.py upload_csv --file wallets.csv --table-name my_wallets --private

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. The references contain critical details (e.g., specialized tables, anti-patterns) that aren't covered in this overview — guessing table names or query patterns leads to subtle bugs.

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

Why this matters: If you're analyzing a specific wallet's trading activity and use dex.trades, you'll see inflated volume because a single swap through an aggregator gets split into multiple pool-level trades. dex_aggregator.trades captures the user-level intent — one row per user swap. 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: