sim

Original：🇺🇸 English
Translated

Dune Sim API for real-time blockchain wallet and token lookups across EVM and SVM chains. Use when user asks about wallet balances, token prices, NFT holdings, DeFi positions, transaction history, wallet activity, token holders, stablecoins, or any real-time on-chain data for a specific address. Triggers: 'check wallet', 'token balance', 'NFT holdings', 'DeFi positions', 'transaction history', 'token holders', 'token price', 'stablecoin balance', 'wallet activity', or any request involving a blockchain address (0x... or Solana base58).

3installs
Sourceduneanalytics/skills
Added on

NPX Install

npx skill4agent add duneanalytics/skills sim

Tags

Translated version includes tags in frontmatter
dune-sim-apiblockchain-data-queryevm-chain-toolssvm-chain-toolswallet-analytics

SKILL.md Content

View Translation Comparison →

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 CaseToolWhy
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):
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. 
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:
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

CommandDescriptionAuth
dune sim auth
Save Sim API key to config fileNo
dune sim evm supported-chains
List supported EVM chains and endpoint availabilityNo
dune sim evm balances <addr>
Native + ERC20 token balances with USD valuesYes
dune sim evm balance <addr>
Single-token balance on one chainYes
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 decodingYes
dune sim evm collectibles <addr>
ERC721/ERC1155 NFT holdings with spam filteringYes
dune sim evm token-info <addr>
Token metadata, price, supply, market capYes
dune sim evm token-holders <addr>
Top holders of an ERC20 token ranked by balanceYes
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:
TaskReference
CLI install, Sim auth recovery, version checksinstall-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 decodingevm-transactions.md
NFT collectibles and spam filteringevm-collectibles.md
Token metadata, pricing, and holder leaderboardsevm-tokens.md
DeFi positions (lending, AMM, vaults)evm-defi.md
SVM (Solana, Eclipse) balances and transactionssvm-commands.md