duneanalytics/sim

Prerequisites

Assume the Dune CLI is already installed and authenticated. Do not run upfront install or auth checks. Just execute the requested dune sim command directly.

If a dune sim command fails, inspect the error to determine the cause and follow the recovery steps in install-and-recovery.md:

• "command not found" → CLI not installed. See CLI Not Found Recovery.
• "missing Sim API key" → No key in flag, env, or config. See Sim Authentication Failure Recovery.
• "authentication failed" → Key is invalid, expired, or revoked. See Sim Authentication Failure Recovery.
• Unknown subcommand or flag / unexpected output → Possible version mismatch. See Version Compatibility.

Dune Sim API

A CLI interface for the Dune Sim API -- real-time, pre-indexed blockchain data. Use it to instantly look up wallet balances, token prices, transaction history, activity feeds, NFT holdings, DeFi positions, and token holder distributions across EVM and SVM chains.

When to Use Sim API vs DuneSQL

Choose the right tool based on the task:

| Use Case | Tool | Why | |----------|------|-----| | Wallet token balances | dune sim evm balances | Instant, multi-chain, includes USD prices | | Recent wallet activity | dune sim evm activity | Pre-decoded, classified (sends, swaps, etc.) | | Token price / metadata | dune sim evm token-info | Real-time pricing from DEX pools | | NFT holdings | dune sim evm collectibles | Includes spam filtering and metadata | | Token holder leaderboard | dune sim evm token-holders | Pre-ranked by balance | | DeFi positions | dune sim evm defi-positions | Cross-protocol aggregation | | Solana wallet balances | dune sim svm balances | SPL token balances with USD values | | Custom SQL analytics | dune query run-sql | Full DuneSQL power, historical data, aggregations | | Cross-table joins | dune query run-sql | Sim API returns single-entity data | | Historical time-series | dune query run-sql | Sim API returns current state, not historical | | Data not covered by Sim | dune query run-sql | Sim has fixed endpoints; DuneSQL is open-ended |

Rule of thumb: If the user wants current data about a specific wallet or token address, use dune sim. If they need custom analytics, historical trends, aggregations across many addresses, or data not available through Sim endpoints, use dune query run-sql (see the dune skill).

Authentication

Sim API commands require a Sim API key (separate from the Dune API key used by dune query commands). The key is resolved in this priority order:

1. --sim-api-key flag (highest priority)
2. DUNE_SIM_API_KEY environment variable
3. Saved config file at ~/.config/dune/config.yaml (set via dune sim auth)

To save the key interactively (prompted from stdin):

dune sim auth

Exception: dune sim evm supported-chains is a public endpoint and does not require a Sim API key.

Do not attempt to handle the API key yourself -- the user must authenticate outside of this session. Never pass --sim-api-key on the command line. Prefer dune sim auth or the DUNE_SIM_API_KEY environment variable.

Verifying Authentication

To test whether the CLI is authenticated, run a lightweight authenticated command:

dune sim evm token-info native --chain-ids 1 -o json

If this returns token metadata for ETH, authentication is working. If it returns a 401 or "missing Sim API key" error, direct the user to set up their key (see Sim Authentication Failure Recovery).

Output Format (per-command flag)

Most commands support -o, --output <FORMAT> with values text (default, human-readable tables) or json (machine-readable).

Always use -o json on every command that supports it. JSON output contains the full API response (all fields, nested objects, pagination cursors) while text mode shows a summarized table that drops many fields.

Key Concepts

Chain IDs and Tags

EVM chains are identified by numeric chain IDs (e.g. 1 for Ethereum, 8453 for Base, 42161 for Arbitrum). Many commands accept --chain-ids with:

• Numeric IDs: --chain-ids 1,8453
• Tag names: --chain-ids default (queries all default chains)

Run dune sim evm supported-chains -o json to discover all available chain IDs, their names, tags, and which endpoints each chain supports.

Pagination

Most commands return paginated results. The response includes a next_offset field when more pages are available. Pass this value as --offset to fetch the next page:

# First page
dune sim evm balances 0xd8da... -o json
# Response includes "next_offset": "abc123..."

# Next page
dune sim evm balances 0xd8da... --offset abc123... -o json

Compute Units

Each Sim API request consumes compute units based on the complexity and number of chains queried. The response may include an X-Compute-Units-Cost header indicating units consumed.

EVM vs SVM

• EVM (Ethereum Virtual Machine): Ethereum, Base, Arbitrum, Polygon, Optimism, and other compatible chains. Addresses are 0x-prefixed hex (42 characters).
• SVM (Solana Virtual Machine): Solana, Eclipse. Addresses are base58-encoded (32-44 characters). SVM endpoints are currently in beta.

Command Overview

| Command | Description | Auth | |---------|-------------|------| | dune sim auth | Save Sim API key to config file | No | | dune sim evm supported-chains | List supported EVM chains and endpoint availability | No | | dune sim evm balances <addr> | Native + ERC20 token balances with USD values | Yes | | dune sim evm balance <addr> | Single-token balance on one chain | Yes | | dune sim evm stablecoins <addr> | Stablecoin-only balances (USDC, USDT, DAI, etc.) | Yes | | dune sim evm activity <addr> | Decoded activity feed (transfers, swaps, approvals, calls) | Yes | | dune sim evm transactions <addr> | Raw transaction history with optional ABI decoding | Yes | | dune sim evm collectibles <addr> | ERC721/ERC1155 NFT holdings with spam filtering | Yes | | dune sim evm token-info <addr> | Token metadata, price, supply, market cap | Yes | | dune sim evm token-holders <addr> | Top holders of an ERC20 token ranked by balance | Yes | | dune sim evm defi-positions <addr> | DeFi positions across lending, AMM, vault protocols | Yes | | dune sim evm supported-protocols | DeFi protocol families and chains supported by defi-positions | Yes | | dune sim svm balances <addr> | SPL token balances on Solana/Eclipse (beta) | Yes | | dune sim svm transactions <addr> | Solana transaction history (beta) | Yes |

Common Workflows

Discover Supported Chains

Always start here when unsure which chains are available or which endpoints a chain supports:

dune sim evm supported-chains -o json

Check a Wallet's Full Portfolio

# All token balances across default EVM chains
dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

# Restrict to Ethereum and Base only
dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --chain-ids 1,8453 -o json

# Exclude spam tokens
dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --exclude-spam -o json

Check Stablecoin Holdings

dune sim evm stablecoins 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Look Up a Single Token Balance

# Native ETH on Ethereum
dune sim evm balance 0xd8da... --token native --chain-ids 1 -o json

# USDC on Base
dune sim evm balance 0xd8da... --token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 -o json

Track Recent Wallet Activity

# All activity types
dune sim evm activity 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

# Only sends and receives on Ethereum
dune sim evm activity 0xd8da... --activity-type send,receive --chain-ids 1 -o json

# Only ERC20 token activity
dune sim evm activity 0xd8da... --asset-type erc20 -o json

Get Raw Transaction History

# Basic transaction history
dune sim evm transactions 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

# With ABI-decoded function calls and event logs
dune sim evm transactions 0xd8da... --chain-ids 1 --decode -o json

Look Up Token Metadata and Price

# ETH price and metadata
dune sim evm token-info native --chain-ids 1 -o json

# USDC on Base with historical prices (30d, 7d, 1d ago)
dune sim evm token-info 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 --historical-prices 720,168,24 -o json

Analyze Token Holder Distribution

# Top 500 holders of a token on Base
dune sim evm token-holders 0x63706e401c06ac8513145b7687A14804d17f814b --chain-id 8453 -o json

# Top 50 holders of USDC on Ethereum
dune sim evm token-holders 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain-id 1 --limit 50 -o json

Check NFT Holdings

# All NFTs (spam filtered by default)
dune sim evm collectibles 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

# Include spam NFTs with scoring details
dune sim evm collectibles 0xd8da... --filter-spam=false --show-spam-scores -o json

Check DeFi Positions

# All DeFi positions across default chains
dune sim evm defi-positions 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

# Restrict to Ethereum and Base
dune sim evm defi-positions 0xd8da... --chain-ids 1,8453 -o json

Discover DeFi Protocol Coverage

Check which protocol families, sub-protocols, and chains are supported by defi-positions before querying a wallet:

# Stable protocols/chains only
dune sim evm supported-protocols -o json

# Include chains still in preview
dune sim evm supported-protocols --include-preview-chains -o json

Solana Wallet Lookup

# SPL token balances
dune sim svm balances 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY -o json

# Transaction history
dune sim svm transactions 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY -o json

Limitations

The Sim API provides pre-indexed, real-time data for specific endpoints. It does not support:

• Custom SQL queries -- Use dune query run-sql for arbitrary DuneSQL
• Historical time-series -- Sim returns current state; use DuneSQL for historical analysis
• Cross-address aggregations -- Sim queries one address at a time; use DuneSQL for multi-address analysis
• Write operations -- Sim is read-only; it does not submit transactions
• Webhook subscriptions -- Available via the Sim API REST endpoints but not through the CLI

Security

• Never output API keys or tokens in responses. Before presenting CLI output to the user, scan for strings prefixed with sim_ or long alphanumeric tokens. Redact them with [REDACTED].
• Never pass --sim-api-key on the command line when other users might see the terminal history. Prefer dune sim auth or the DUNE_SIM_API_KEY environment variable.
• Do not attempt to handle the API key yourself -- the user must authenticate outside of this session.
• Always use -o json on every command -- JSON output is more detailed and reliably parseable.
• Always confirm with the user before making multiple paginated requests that could consume significant compute units.

Reference Documents

Load the relevant reference when you need detailed command syntax, flags, and response schemas:

| Task | Reference | |------|-----------| | CLI install, Sim auth recovery, version checks | install-and-recovery.md | | Token balances (multi-token, single-token, stablecoins) | evm-balances.md | | Wallet activity feed (transfers, swaps, approvals, calls) | evm-activity.md | | Raw transaction history and ABI decoding | evm-transactions.md | | NFT collectibles and spam filtering | evm-collectibles.md | | Token metadata, pricing, and holder leaderboards | evm-tokens.md | | DeFi positions (lending, AMM, vaults) | evm-defi.md | | SVM (Solana, Eclipse) balances and transactions | svm-commands.md |