sim

前提条件

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

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 スキルを参照）。

認証

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 で設定）

標準入力からプロンプトで入力して、キーを対話的に保存するには、次を実行します。

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 認証失敗時の復旧を参照）。

出力形式（コマンドごとのフラグ）

ほとんどのコマンドでは、-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 Virtual Machine）：Ethereum、Base、Arbitrum、Polygon、Optimism、およびその他の互換チェーンです。アドレスは 0x で始まる 16 進数（42 文字）です。
• SVM（Solana Virtual Machine）：Solana、Eclipse です。アドレスは base58 でエンコードされます（32～44 文字）。SVM エンドポイントは現在ベータ版です。

コマンド一覧

コマンド	説明	認証
dune sim auth	Sim API キーを設定ファイルに保存します	不要
dune sim evm supported-chains	対応している EVM チェーンとエンドポイントの利用可否を一覧表示します	不要
dune sim evm balances <addr>	ネイティブトークンと ERC20 トークンの残高を米ドル換算額とともに表示します	必要
dune sim evm balance <addr>	1 つのチェーン上にある単一トークンの残高を表示します	必要
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 トークン残高を表示します（ベータ版）	必要
dune sim svm transactions <addr>	Solana のトランザクション履歴を表示します（ベータ版）	必要

よくあるワークフロー

対応チェーンを確認する

利用可能なチェーンや、各チェーンが対応しているエンドポイントが不明な場合は、必ず最初に実行してください。

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 クエリ -- 任意の DuneSQL には dune query run-sql を使用してください
• 履歴時系列データ -- Sim は現在の状態を返します。履歴分析には DuneSQL を使用してください
• アドレスをまたぐ集計 -- Sim は一度に 1 つのアドレスをクエリします。複数アドレスの分析には 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