Dune Analytics API

Dune Analytics API skill for querying, analyzing, and uploading blockchain data. Use this skill whenever the user mentions Dune, on-chain data, blockchain an...

Security Scan

The skill's files, runtime instructions, and required credential (DUNE_API_KEY) are consistent with a Dune API client for querying, uploading, and managing queries/tables — nothing requested appears unrelated to the stated purpose.

Purpose & Capability

Name/description match the requested resources: python3 and DUNE_API_KEY are appropriate for a Python-based Dune API client. The scripts and references all relate to discovering tables, executing/updating queries, and uploading data to Dune.

Instruction Scope

SKILL.md and the scripts restrict themselves to Dune API operations and documentation fetches. They read DUNE_API_KEY (declared) and repository reference files. The skill includes operations that modify the user's Dune account (create/update/delete queries/tables, upload/overwrite data); SKILL.md notes best practices (confirm before updating, prefer private queries), but these destructive actions are functionally part of the stated purpose and require user Dune API credentials.

Install Mechanism

There is no automated install spec; SKILL.md instructs the user to pip install dune-client. Pulling a PyPI package is expected for a Python client but users should be aware that an external package is required and will be installed into the environment.

Credentials

Only one credential is required: DUNE_API_KEY (declared as primary). No other secrets, config paths, or unrelated credentials are requested.

Persistence & Privilege

always:false and no special system-wide privileges are requested. However, with the supplied DUNE_API_KEY the skill can perform destructive operations (upload/overwrite/delete tables, update queries) in the user's Dune account. Autonomous invocation is the platform default; consider requiring explicit user confirmation for write/delete actions.

Assessment

This skill appears to do what it claims: it uses your DUNE_API_KEY to query, create/update queries, and upload tables to your Dune account. Before installing or granting the API key: 1) Treat DUNE_API_KEY as sensitive — use a restricted/test Dune account or a key with least-privilege if possible. 2) Be aware the skill can overwrite or delete your Dune tables/queries — only allow it to run write operations after reviewing the SQL and confirming actions. 3) The skill requires pip installing the dune-client package; review that package if you have supply-chain concerns. 4) If you plan to allow autonomous agent actions, restrict or require confirmations for destructive commands (update_sql, upload_csv, delete_table, clear_table). If you want a safer setup, use a read-only or limited API key or a dedicated sandbox Dune account for automation.

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.

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.

Script	Command	What it does
dune_query.py	execute --query-id ID	Execute a saved query (supports --params, --performance, --format)
dune_query.py	get_latest --query-id ID	Get cached result without re-execution
dune_query.py	get_sql --query-id ID	Print query SQL
dune_query.py	update_sql --query-id ID --sql "..."	Update query SQL
dune_discover.py	search --keyword "uniswap"	Search tables by keyword
dune_discover.py	schema --table "dex.trades"	Show table columns and types
dune_discover.py	list_schemas --namespace "uniswap_v3"	List tables in a namespace
dune_discover.py	contract --address "0x..."	Find decoded tables by contract address
dune_discover.py	docs --keyword "dex"	Search Dune documentation
dune_upload.py	upload_csv --file data.csv --table-name tbl	Quick CSV upload (overwrites)
dune_upload.py	create_table --table-name tbl --namespace ns --schema '[...]'	Create table with explicit schema
dune_upload.py	insert --file data.csv --table-name tbl --namespace ns	Append data to existing table

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:

Task involves...	Read this reference
Finding tables / inspecting schema / discovering protocols	table-discovery.md
Finding decoded tables by contract address	table-discovery.md
Searching Dune documentation / guides / examples	table-discovery.md
Wallet / address tracking / router identification	wallet-analysis.md
Table selection / common table names	common-tables.md
SQL performance / complex joins / array ops	sql-optimization.md
API calls / execution / caching / parameters	query-execution.md
Uploading CSV/NDJSON data to Dune	data-upload.md

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

Method	Description	Plan
run_query	Execute saved query (supports {{param}})	Free
run_sql	Execute SQL directly (no params)	Plus

Key Concepts

dex.trades vs dex_aggregator.trades

Table	Use Case	Volume
dex.trades	Per-pool analysis	⚠️ Inflated ~30% (multi-hop counted multiple times)
dex_aggregator.trades	User/wallet analysis	Accurate

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

Layer	Delay	Example
Raw	< 1 min	ethereum.transactions, solana.transactions
Decoded	15-60 sec	uniswap_v3_ethereum.evt_Swap
Curated	~1 hour+	dex.trades, dex_solana.trades

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

References

Detailed documentation is organized in the references/ directory:

File	Description
table-discovery.md	Table discovery: search tables by name, inspect schema/columns, list schemas and uploads
query-execution.md	API patterns: execute, update, cache, multi-day fetch, credits tracking, subqueries
common-tables.md	Quick reference of commonly used tables: raw, decoded, curated, community data
sql-optimization.md	SQL optimization: CTE, JOIN strategies, array ops, partition pruning
wallet-analysis.md	Wallet tracking: Solana/EVM queries, multi-chain aggregation, fee analysis
data-upload.md	Data upload: CSV/NDJSON upload, create table, insert data, manage tables, credits