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:

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

To save the key interactively (prompted from stdin):

bash

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:

bash

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.

for Ethereum,

for Base,

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:

bash

# 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 (beta)	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:

bash

dune sim evm supported-chains -o json

Check a Wallet's Full Portfolio

bash

# 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

bash

dune sim evm stablecoins 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Look Up a Single Token Balance

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

Solana Wallet Lookup

bash

# 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

sim

NPX Install

Tags

SKILL.md Content

Prerequisites

Dune Sim API

When to Use Sim API vs DuneSQL

Authentication

Verifying Authentication

Output Format (per-command flag)

Key Concepts

Chain IDs and Tags

Pagination

Compute Units

EVM vs SVM

Command Overview

Common Workflows

Discover Supported Chains

Check a Wallet's Full Portfolio

Check Stablecoin Holdings

Look Up a Single Token Balance

Track Recent Wallet Activity

Get Raw Transaction History

Look Up Token Metadata and Price

Analyze Token Holder Distribution

Check NFT Holdings

Check DeFi Positions

Solana Wallet Lookup

Limitations

Security

Reference Documents