sim

What this skill does

## 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](references/install-and-recovery.md):

- **"command not found"** → CLI not installed. See [CLI Not Found Recovery](references/install-and-recovery.md#cli-not-found-recovery).
- **"missing Sim API key"** → No key in flag, env, or config. See [Sim Authentication Failure Recovery](references/install-and-recovery.md#sim-authentication-failure-recovery).
- **"authentication failed"** → Key is invalid, expired, or revoked. See [Sim Authentication Failure Recovery](references/install-and-recovery.md#sim-authentication-failure-recovery).
- **Unknown subcommand or flag / unexpected output** → Possible version mismatch. See [Version Compatibility](references/install-and-recovery.md#version-compatibility).

# Dune Sim API

A CLI interface for the [Dune Sim API](https://sim.dune.com) -- 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](../dune/SKILL.md)).

## 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](references/install-and-recovery.md#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

| 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 | Yes |
| `dune sim evm supported-protocols` | DeFi protocol families and chains supported by `defi-positions` | 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 0x833589fCD6eDb6E08f4c7C32D4f7