sim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 CLI已安装并完成认证。请勿预先运行安装或认证检查，直接执行用户请求的

dune sim

命令即可。

若

dune sim

命令执行失败，请检查错误原因并按照install-and-recovery.md中的恢复步骤操作：

"command not found" → CLI未安装，请查看CLI未找到恢复方案。
"missing Sim API key" → 未通过参数、环境变量或配置文件提供密钥，请查看Sim认证失败恢复方案。
"authentication failed" → 密钥无效、过期或已被撤销，请查看Sim认证失败恢复方案。
未知子命令或参数/输出异常 → 可能存在版本不兼容问题，请查看版本兼容性。

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.

这是Dune Sim API的CLI接口，可提供实时的预索引区块链数据。通过它可跨EVM和SVM链快速查询钱包余额、代币价格、交易历史、活动记录、NFT持有量、DeFi仓位以及代币持有者分布情况。

When to Use Sim API vs DuneSQL

何时使用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).

根据任务选择合适的工具：

使用场景	工具	原因
钱包代币余额	`dune sim evm balances`	实时响应、支持多链、包含USD计价
近期钱包活动	`dune sim evm activity`	已预解码、分类（转账、兑换等）
代币价格/元数据	`dune sim evm token-info`	来自DEX池的实时定价
NFT持有量	`dune sim evm collectibles`	包含垃圾NFT过滤和元数据
代币持有者排行榜	`dune sim evm token-holders`	按余额预排序
DeFi仓位	`dune sim evm defi-positions`	跨协议聚合数据
Solana钱包余额	`dune sim svm balances`	SPL代币余额及USD计价
自定义SQL分析	`dune query run-sql`	完整DuneSQL功能、历史数据、聚合分析
跨表关联查询	`dune query run-sql`	Sim API仅返回单实体数据
历史时间序列分析	`dune query run-sql`	Sim API仅返回当前状态，无历史数据
Sim未覆盖的数据查询	`dune query run-sql`	Sim有固定端点，DuneSQL支持开放式查询

经验法则：若用户需要特定钱包或代币地址的当前数据，使用

dune sim

；若用户需要自定义分析、历史趋势、多地址聚合分析，或Sim端点未覆盖的数据，使用

dune query run-sql

（详见dune技能）。

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.

Sim API命令需要Sim API密钥（与

dune query

命令使用的Dune API密钥不同），密钥的优先级顺序如下：

```
--sim-api-key
```
参数（最高优先级）
```
DUNE_SIM_API_KEY
```
环境变量
存储在
```
~/.config/dune/config.yaml
```
的配置文件（通过
```
dune sim auth
```
设置）

若要交互式保存密钥（从标准输入获取），执行：

bash

dune sim auth

例外情况：

dune sim evm supported-chains

是公开端点，无需Sim API密钥。

请勿自行处理API密钥，用户必须在本次会话外完成认证。绝对不要在命令行中传递

--sim-api-key

参数，优先使用

dune sim auth

或

DUNE_SIM_API_KEY

环境变量。

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

若要测试CLI是否已认证，执行轻量级的认证命令：

bash

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

若返回ETH的代币元数据，说明认证成功；若返回401错误或"missing Sim API key"错误，请引导用户设置密钥（详见Sim认证失败恢复方案）。

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.

大多数命令支持

-o, --output <FORMAT>

参数，可选值为

text

（默认，人类可读表格）或

json

（机器可读）。

所有支持该参数的命令，请始终使用
-o json
。JSON输出包含完整的API响应（所有字段、嵌套对象、分页游标），而
text
模式仅显示汇总表格，会丢弃大量字段。

Key Concepts

核心概念

Chain IDs and Tags

链ID与标签

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.

EVM链通过数字链ID标识（例如：以太坊为

，Base为

，Arbitrum为

）。许多命令支持

--chain-ids

参数，可传入：

数字ID：
```
--chain-ids 1,8453
```
标签名称：
```
--chain-ids default
```
（查询所有默认链）

执行

dune sim evm supported-chains -o json

可查看所有可用链ID、名称、标签，以及各链支持的端点。

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

undefined

大多数命令返回分页结果。当存在更多数据时，响应会包含

next_offset

字段，将该值作为

--offset

参数传入即可获取下一页数据：

bash

undefined

First page

第一页

dune sim evm balances 0xd8da... -o json

Response includes "next_offset": "abc123..."

响应包含"next_offset": "abc123..."

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

undefined

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

undefined

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.

每个Sim API请求会根据查询复杂度和涉及链的数量消耗计算单元。响应可能包含

X-Compute-Units-Cost

头，显示消耗的计算单元数量。

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.

EVM（以太坊虚拟机）：以太坊、Base、Arbitrum、Polygon、Optimism及其他兼容链，地址为
```
0x
```
前缀的十六进制格式（42个字符）。
SVM（Solana虚拟机）：Solana、Eclipse，地址为base58编码格式（32-44个字符）。SVM端点目前处于测试阶段。

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

命令	描述	是否需要认证
`dune sim auth`	将Sim API密钥保存到配置文件	否
`dune sim evm supported-chains`	列出支持的EVM链及端点可用性	否
`dune sim evm balances <addr>`	原生代币+ERC20代币余额及USD计价	是
`dune sim evm balance <addr>`	单条链上的单一代币余额	是
`dune sim evm stablecoins <addr>`	仅显示稳定币余额（USDC、USDT、DAI等）	是
`dune sim evm activity <addr>`	已解码的活动记录（转账、兑换、授权、调用）	是
`dune sim evm transactions <addr>`	原始交易历史，可选ABI解码	是
`dune sim evm collectibles <addr>`	ERC721/ERC1155 NFT持有量，包含垃圾NFT过滤	是
`dune sim evm token-info <addr>`	代币元数据、价格、供应量、市值	是
`dune sim evm token-holders <addr>`	ERC20代币的顶级持有者（按余额排序）	是
`dune sim evm defi-positions <addr>`	跨借贷、AMM、金库协议的DeFi仓位（测试阶段）	是
`dune sim svm balances <addr>`	Solana/Eclipse上的SPL代币余额（测试阶段）	是
`dune sim svm transactions <addr>`	Solana交易历史（测试阶段）	是

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

当不确定可用链或链支持的端点时，请先执行：

bash

dune sim evm supported-chains -o json

Check a Wallet's Full Portfolio

查询钱包完整资产组合

bash

undefined

bash

undefined

All token balances across default EVM chains

查询所有默认EVM链上的代币余额

dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Restrict to Ethereum and Base only

仅查询以太坊和Base链

dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --chain-ids 1,8453 -o json

Exclude spam tokens

排除垃圾代币

dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --exclude-spam -o json

undefined

dune sim evm balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --exclude-spam -o json

undefined

Check Stablecoin Holdings

查询稳定币持有量

bash

dune sim evm stablecoins 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

bash

dune sim evm stablecoins 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Look Up a Single Token Balance

查询单一代币余额

bash

undefined

bash

undefined

Native ETH on Ethereum

以太坊上的原生ETH

dune sim evm balance 0xd8da... --token native --chain-ids 1 -o json

USDC on Base

Base链上的USDC

dune sim evm balance 0xd8da... --token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 -o json

undefined

dune sim evm balance 0xd8da... --token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 -o json

undefined

Track Recent Wallet Activity

追踪近期钱包活动

bash

undefined

bash

undefined

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

仅查询ERC20代币活动

dune sim evm activity 0xd8da... --asset-type erc20 -o json

undefined

dune sim evm activity 0xd8da... --asset-type erc20 -o json

undefined

Get Raw Transaction History

获取原始交易历史

bash

undefined

bash

undefined

Basic transaction history

基础交易历史

dune sim evm transactions 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

With ABI-decoded function calls and event logs

包含ABI解码的函数调用和事件日志

dune sim evm transactions 0xd8da... --chain-ids 1 --decode -o json

undefined

dune sim evm transactions 0xd8da... --chain-ids 1 --decode -o json

undefined

Look Up Token Metadata and Price

查询代币元数据与价格

bash

undefined

bash

undefined

ETH price and metadata

ETH价格与元数据

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

USDC on Base with historical prices (30d, 7d, 1d ago)

Base链上的USDC及历史价格（30天前、7天前、1天前）

dune sim evm token-info 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 --historical-prices 720,168,24 -o json

undefined

dune sim evm token-info 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --chain-ids 8453 --historical-prices 720,168,24 -o json

undefined

Analyze Token Holder Distribution

分析代币持有者分布

bash

undefined

bash

undefined

Top 500 holders of a token on Base

Base链上某代币的前500名持有者

dune sim evm token-holders 0x63706e401c06ac8513145b7687A14804d17f814b --chain-id 8453 -o json

Top 50 holders of USDC on Ethereum

以太坊上USDC的前50名持有者

dune sim evm token-holders 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain-id 1 --limit 50 -o json

undefined

dune sim evm token-holders 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain-id 1 --limit 50 -o json

undefined

Check NFT Holdings

查询NFT持有量

bash

undefined

bash

undefined

All NFTs (spam filtered by default)

查询所有NFT（默认过滤垃圾NFT）

dune sim evm collectibles 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Include spam NFTs with scoring details

包含垃圾NFT及评分详情

dune sim evm collectibles 0xd8da... --filter-spam=false --show-spam-scores -o json

undefined

dune sim evm collectibles 0xd8da... --filter-spam=false --show-spam-scores -o json

undefined

Check DeFi Positions

查询DeFi仓位

bash

undefined

bash

undefined

All DeFi positions across default chains

查询所有默认链上的DeFi仓位

dune sim evm defi-positions 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

Restrict to Ethereum and Base

仅查询以太坊和Base链

dune sim evm defi-positions 0xd8da... --chain-ids 1,8453 -o json

undefined

dune sim evm defi-positions 0xd8da... --chain-ids 1,8453 -o json

undefined

Solana Wallet Lookup

Solana钱包查询

bash

undefined

bash

undefined

SPL token balances

SPL代币余额

dune sim svm balances 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY -o json

Transaction history

交易历史

dune sim svm transactions 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY -o json

undefined

dune sim svm transactions 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY -o json

undefined

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

Sim API提供预索引的实时数据，但不支持：

自定义SQL查询 —— 如需任意DuneSQL查询，请使用
```
dune query run-sql
```
历史时间序列分析 —— Sim仅返回当前状态，如需历史分析请使用DuneSQL
跨地址聚合分析 —— Sim每次仅查询一个地址，如需多地址分析请使用DuneSQL
写入操作 —— Sim为只读工具，不支持提交交易
Webhook订阅 —— 该功能可通过Sim API REST端点实现，但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.

绝对不要在响应中输出API密钥或令牌。在向用户展示CLI输出前，请扫描以
```
sim_
```
开头的字符串或长字母数字令牌，并用
```
[REDACTED]
```
替换。
绝对不要在命令行中传递
```
--sim-api-key
```
参数，避免其他用户查看终端历史记录。优先使用
```
dune sim auth
```
或
```
DUNE_SIM_API_KEY
```
环境变量。
请勿自行处理API密钥，用户必须在本次会话外完成认证。
所有支持的命令，请始终使用
-o json
—— JSON输出更详细且更易解析。
在执行可能消耗大量计算单元的多页查询前，请务必先征得用户同意。

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

如需详细的命令语法、参数及响应架构，请查看相关参考文档：

任务	参考文档
CLI安装、Sim认证恢复、版本检查	install-and-recovery.md
代币余额（多代币、单代币、稳定币）	evm-balances.md
钱包活动记录（转账、兑换、授权、调用）	evm-activity.md
原始交易历史与ABI解码	evm-transactions.md
NFT持有量与垃圾过滤	evm-collectibles.md
代币元数据、定价与持有者排行榜	evm-tokens.md
DeFi仓位（借贷、AMM、金库）	evm-defi.md
SVM（Solana、Eclipse）余额与交易	svm-commands.md

sim

Original

Translation

Prerequisites

前提条件

Dune Sim API

Dune Sim API

When to Use Sim API vs DuneSQL

何时使用Sim API vs DuneSQL

Authentication

认证

Verifying Authentication

验证认证状态

Output Format (per-command flag)

输出格式（按命令参数设置）

Key Concepts

核心概念

Chain IDs and Tags

链ID与标签

Pagination

分页

First page

第一页

Response includes "next_offset": "abc123..."

响应包含"next_offset": "abc123..."

Next page

下一页

Compute Units

计算单元

EVM vs SVM

EVM vs SVM

Command Overview

命令概览

Common Workflows

常见工作流

Discover Supported Chains

查看支持的链

Check a Wallet's Full Portfolio

查询钱包完整资产组合

All token balances across default EVM chains

查询所有默认EVM链上的代币余额

Restrict to Ethereum and Base only

仅查询以太坊和Base链

Exclude spam tokens

排除垃圾代币

Check Stablecoin Holdings

查询稳定币持有量

Look Up a Single Token Balance

查询单一代币余额

Native ETH on Ethereum

以太坊上的原生ETH

USDC on Base

Base链上的USDC

Track Recent Wallet Activity

追踪近期钱包活动

All activity types

查询所有活动类型

Only sends and receives on Ethereum

仅查询以太坊上的转账和收款

Only ERC20 token activity

仅查询ERC20代币活动

Get Raw Transaction History

获取原始交易历史

Basic transaction history

基础交易历史

With ABI-decoded function calls and event logs

包含ABI解码的函数调用和事件日志

Look Up Token Metadata and Price

查询代币元数据与价格

ETH price and metadata

ETH价格与元数据

USDC on Base with historical prices (30d, 7d, 1d ago)

Base链上的USDC及历史价格（30天前、7天前、1天前）

Analyze Token Holder Distribution

分析代币持有者分布

Top 500 holders of a token on Base

Base链上某代币的前500名持有者

Top 50 holders of USDC on Ethereum

以太坊上USDC的前50名持有者

Check NFT Holdings