sim

前置条件

假设 Dune CLI 已安装并完成身份验证。不要预先运行安装或身份验证检查。直接执行所请求的 dune sim 命令即可。

如果 dune sim 命令失败，请检查错误以确定原因，并按照 install-and-recovery.md 中的恢复步骤操作：

• “command not found” → CLI 未安装。请参阅 CLI Not Found Recovery。
• “missing Sim API key” → 命令行标志、环境变量或配置中均未提供密钥。请参阅 Sim Authentication Failure Recovery。
• “authentication failed” → 密钥无效、已过期或已撤销。请参阅 Sim Authentication Failure Recovery。
• 未知子命令或标志 / 输出异常 → 可能是版本不兼容。请参阅 Version Compatibility。

Dune Sim API

用于 Dune Sim API 的 CLI 接口，可提供实时、预先索引的区块链数据。可用于即时查询 EVM 和 SVM 链上的钱包余额、代币价格、交易历史、活动动态、NFT 持仓、DeFi 仓位和代币持有者分布。

何时使用 Sim API，何时使用 DuneSQL

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

用例	工具	原因
钱包代币余额	dune sim evm balances	即时查询，支持多条链，包含 USD 价格
钱包近期活动	dune sim evm activity	已预先解码并分类（转账、兑换等）
代币价格 / 元数据	dune sim evm token-info	来自 DEX 池的实时报价
NFT 持仓	dune sim evm collectibles	包含垃圾内容过滤和元数据
代币持有者排行榜	dune sim evm token-holders	已按余额预先排名
DeFi 仓位	dune sim evm defi-positions	跨协议聚合
Solana 钱包余额	dune sim svm balances	包含 USD 价值的 SPL 代币余额
自定义 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 skill）。

身份验证

Sim API 命令需要 Sim API 密钥（与 dune query 命令使用的 Dune API 密钥相互独立）。密钥按以下优先级解析：

1. --sim-api-key 标志（优先级最高）
2. DUNE_SIM_API_KEY 环境变量
3. ~/.config/dune/config.yaml 中保存的配置文件（通过 dune sim auth 设置）

如需交互式保存密钥（从 stdin 提示输入）：

dune sim auth

例外： dune sim evm supported-chains 是公共端点，无需 Sim API 密钥。

不要尝试自行处理 API 密钥——用户必须在本会话之外完成身份验证。切勿在命令行中传递 --sim-api-key。优先使用 dune sim auth 或 DUNE_SIM_API_KEY 环境变量。

验证身份验证

如需测试 CLI 是否已通过身份验证，请运行一个轻量级的身份验证命令：

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

如果该命令返回 ETH 的代币元数据，说明身份验证正常。如果返回 401 或“missing Sim API key”错误，请引导用户设置密钥（参阅 Sim Authentication Failure Recovery）。

输出格式（每条命令的标志）

大多数命令支持 -o, --output <FORMAT>，可选值为 text（默认，以人类可读的表格形式输出）或 json（机器可读）。

对于每条支持该选项的命令，始终使用 -o json。 JSON 输出包含完整的 API 响应（所有字段、嵌套对象和分页游标），而 text 模式会输出摘要表格，省略许多字段。

核心概念

链 ID 和标签

EVM 链通过数字链 ID 标识（例如，Ethereum 为 1，Base 为 8453，Arbitrum 为 42161）。许多命令接受 --chain-ids，可使用：

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

运行 dune sim evm supported-chains -o json，可查看所有可用链 ID、链名称、标签，以及各链支持的端点。

分页

大多数命令会返回分页结果。当有更多页面可用时，响应中会包含 next_offset 字段。将此值作为 --offset 传入，以获取下一页：

# 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

计算单元

每次 Sim API 请求消耗的计算单元取决于请求的复杂度和查询的链数量。响应可能包含 X-Compute-Units-Cost 标头，指示消耗的计算单元。

EVM 与 SVM

• EVM（Ethereum 虚拟机）：Ethereum、Base、Arbitrum、Polygon、Optimism 及其他兼容链。地址为带 0x 前缀的十六进制字符串（42 个字符）。
• SVM（Solana 虚拟机）：Solana、Eclipse。地址采用 base58 编码（32–44 个字符）。SVM 端点目前处于 beta 阶段。

命令概览

命令	说明	认证
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 持仓，并过滤垃圾内容	是
dune sim evm token-info <addr>	代币元数据、价格、供应量、市值	是
dune sim evm token-holders <addr>	按余额排名的 ERC20 代币主要持有者	是
dune sim evm defi-positions <addr>	涵盖借贷、AMM、金库协议的 DeFi 仓位	是
dune sim evm supported-protocols	defi-positions 支持的 DeFi 协议类别和链	是
dune sim svm balances <addr>	Solana/Eclipse 上的 SPL 代币余额（beta）	是
dune sim svm transactions <addr>	Solana 交易历史（beta）	是

常见工作流

查看支持的链

如果不确定有哪些可用链，或某条链支持哪些端点，请始终从这里开始：

dune sim evm supported-chains -o json

查看钱包的完整资产组合

# 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

查看稳定币持仓

dune sim evm stablecoins 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 -o json

查询单个代币余额

# 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

跟踪近期钱包活动

# 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

获取原始交易历史

# 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

查询代币元数据和价格

# 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

分析代币持有者分布

# 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

查看 NFT 持仓

# 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

查看 DeFi 仓位

# 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

查看 DeFi 协议覆盖范围

查询钱包前，先查看 defi-positions 支持的协议类别、子协议和链：

# 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 钱包

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

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

限制

Sim API 为特定端点提供预索引的实时数据。它不支持：

• 自定义 SQL 查询——使用 dune query run-sql 执行任意 DuneSQL 查询
• 历史时间序列——Sim 返回当前状态；历史分析请使用 DuneSQL
• 跨地址聚合——Sim 一次只查询一个地址；多地址分析请使用 DuneSQL
• 写入操作——Sim 为只读服务；不会提交交易
• Webhook 订阅——可通过 Sim API REST 端点使用，但不能通过 CLI 使用

安全

• 绝不在响应中输出 API 密钥或令牌。向用户展示 CLI 输出前，请检查是否包含以 sim_ 开头的字符串或较长的字母数字令牌，并将其替换为 [REDACTED]。
• 当其他用户可能看到终端历史记录时，绝不在命令行中传递 --sim-api-key。请优先使用 dune sim auth 或 DUNE_SIM_API_KEY 环境变量。
• 不要尝试自行处理 API 密钥——用户必须在本会话之外完成身份验证。
• 始终在每条命令中使用 -o json——JSON 输出更详细且易于可靠解析。
• 在发起可能消耗大量计算单元的多次分页请求前，始终先征得用户同意。

参考文档

需要详细的命令语法、标志和响应架构时，请加载相关参考文档：

任务	参考文档
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