Sim by Dune - Sei Docs

Overview

Sim by Dune is a real-time, multichain developer platform. It has scalable APIs and indexing infrastructure for building onchain applications. It gives you fast access to live blockchain data on 60+ chains, including Sei, with no DevOps overhead. This tutorial shows how to set up Sim, build your first data pipeline, and create onchain applications on Sei. For details on how Sim works, see the Sim by Dune documentation.

What this guide teaches you:

How to get your Sim API key, install the dependencies, and connect to Sei
How to use all 6 Sim APIs, with practical examples
How to run end-to-end code examples that:
- Fetch Sei token balances with USD values
- Monitor wallet transactions and activity
- Get token metadata and holder information
- Track NFT collections and metadata
How to make your code production ready with error handling, rate limiting, and monitoring

Some use cases:

DeFi analytics platforms: Real-time tracking of liquidity, volumes, and yields across Sei protocols
Portfolio trackers: Multichain portfolio management with Sei integration
Trading bots: Automated trading based on real-time onchain signals
Risk management: Monitor positions and liquidation risks across protocols
Governance tools: Track voting power and proposal activity
MEV analysis: Detect and analyze MEV opportunities on Sei

Supported APIs

Sim by Dune gives access to EVM blockchain data through these core APIs:

Balances API

Features: All EVM token balances for a wallet or address, ordered by USD value
Use cases: Portfolio trackers, wallet applications, asset management dashboards

Transactions API

Features: Quick and accurate lookup of the EVM transactions for any address
Use cases: Transaction monitoring, compliance tools, activity tracking

Token Info API

Features: Metadata, including symbol, name, decimals, supply information, logo URLs, and real-time prices
Use cases: Token discovery, price tracking, market analysis

Token Holders API

Features: Holders of an ERC-20 token, sorted by balance
Use cases: Governance analysis, token distribution studies, whale tracking

Activity API

Features: Derived activities, such as swaps, transfers, and approvals, in the transactions of any address
Use cases: DeFi analytics, trading analysis, user behavior tracking

Collectibles API

Features: All NFT balances (ERC-721 and ERC-1155), including IDs and metadata
Use cases: NFT marketplaces, collection analytics, digital asset management

Quick start

1. Getting your API key

To use the Sim APIs, you need an API key from the Sim dashboard:

Go to sim.dune.com.
Create an account, or log in with your existing Dune account.
In the left sidebar, click Keys.
To generate a new API key, click New.
Choose Sim API as the purpose of the key.
Copy the generated API key, and save it securely.

Security notes:

Never share your API key in public repositories
Keep your API keys secure and rotate them regularly
Use environment variables to store your keys

2. Project setup

mkdir sei-sim-tutorial
cd sei-sim-tutorial
npm init -y
npm install axios dotenv

Create a .env file:

SIM_API_KEY=your_sim_api_key_here
SEI_RPC_URL=https://evm-rpc.sei-apis.com
TEST_WALLET_ADDRESS=0x...your_test_address

3. Your first API call

Create index.js:

require('dotenv').config();
const axios = require('axios');

const SIM_API_BASE = 'https://api.sim.dune.com/v1';

const headers = {
  'X-Sim-Api-Key': process.env.SIM_API_KEY,
  'Content-Type': 'application/json'
};

async function getSeiBalances() {
  try {
    console.log('🔍 Fetching Sei balances...');
    console.log(`Using wallet address: ${process.env.TEST_WALLET_ADDRESS}`);

    const response = await axios.get(`${SIM_API_BASE}/evm/balances/${process.env.TEST_WALLET_ADDRESS}?chain_ids=1329`, { headers });

    const seiBalances = response.data.balances.filter((balance) => balance.chain === 'sei');

    console.log('💰 Sei Balances:');
    seiBalances.forEach((balance) => {
      console.log(`  ${balance.symbol}: ${balance.amount} (${balance.value_usd} USD)`);
    });
  } catch (error) {
    console.error('❌ Error fetching balances:', error.response?.data || error.message);
  }
}

// Run the function
getSeiBalances();

Run your first query:

node index.js

Expected output:

🔍 Fetching Sei balances...
💰 Sei Balances:
  SEI: 1250.5 (3125.25 USD)
  USDC: 500.0 (500.0 USD)

API examples

Balances API - Get token balances

async function getSeiBalances() {
  try {
    const response = await axios.get(`${SIM_API_BASE}/evm/balances/${process.env.TEST_WALLET_ADDRESS}?chain_ids=1329`, { headers });

    const seiBalances = response.data.balances.filter((balance) => balance.chain === 'sei');

    console.log('💰 Sei Balances:');
    seiBalances.forEach((balance) => {
      console.log(`  ${balance.symbol}: ${balance.amount} (${balance.value_usd} USD)`);
    });
  } catch (error) {
    console.error('❌ Error fetching balances:', error.response?.data || error.message);
  }
}

Transactions API - Monitor wallet transactions

async function monitorSeiTransactions(address) {
  try {
    console.log(`📡 Monitoring transactions for ${address}...`);

    const response = await axios.get(`${SIM_API_BASE}/evm/transactions/${address}`, {
      headers,
      params: {
        chain: 'sei',
        limit: 10
      }
    });

    const transactions = response.data.transactions;

    console.log('🔄 Recent Transactions:');
    transactions.forEach((tx) => {
      console.log(`  Hash: ${tx.hash}`);
      console.log(`  From: ${tx.from} → To: ${tx.to}`);
      console.log(`  Value: ${tx.value} SEI`);
      console.log(`  Gas Used: ${tx.gas_used}`);
      console.log(`  Status: ${tx.success}`);
      console.log('  ---');
    });
  } catch (error) {
    console.error('❌ Error monitoring transactions:', error.message);
  }
}

Token Info API - Get token metadata

async function getTokenInfo(tokenAddress) {
  try {
    console.log('🏷️ Fetching token information...');

    const response = await axios.get(`${SIM_API_BASE}/evm/token-info/${tokenAddress}?chain_ids=1329`, { headers });
    const tokenInfo = response.data.tokens[0];

    console.log('📝 Token Information:');
    console.log(`  Name: ${tokenInfo.name}`);
    console.log(`  Symbol: ${tokenInfo.symbol}`);
    console.log(`  Decimals: ${tokenInfo.decimals}`);
    console.log(`  Total Supply: ${tokenInfo.total_supply}`);
    console.log(`  Current Price: ${tokenInfo.price_usd}`);
    console.log(`  Logo: ${tokenInfo.logo}`);

    return tokenInfo;
  } catch (error) {
    console.error('❌ Error fetching token info:', error.message);
  }
}

// Example usage with USDC address
getTokenInfo('0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392');

Token Holders API - Find top holders

async function getTokenHolders(tokenAddress, limit = 20) {
  try {
    console.log('👥 Fetching token holders...');

    const response = await axios.get(`${SIM_API_BASE}/evm/token-holders/1329/${tokenAddress}`, {
      headers,
      params: { limit }
    });

    const holders = response.data.holders;
    console.log(`🏆 Top ${holders.length} holders:`);
    holders.forEach((holder, index) => {
      console.log(`${index + 1}. ${holder.wallet_address}`);
      console.log(`   Balance: ${parseFloat(holder.balance)}`);
      console.log(`   First Acquired: ${holder.first_acquired}`);
      console.log('   ---');
    });

    return holders;
  } catch (error) {
    console.error('❌ Error fetching token holders:', error.message);
  }
}

Activity API - Track swaps and transfers

async function getWalletActivity(walletAddress, limit = 10) {
  try {
    console.log('⚡ Fetching wallet activity on Sei...');

    const response = await axios.get(`${SIM_API_BASE}/evm/activity/${walletAddress}?chain_ids=1329`, {
      headers,
      params: { limit }
    });

    const activities = response.data.activity;

    console.log(`📊 Recent activities (${activities.length}):`);
    activities.forEach((activity, index) => {
      console.log(`${index + 1}. Type: ${activity.type.toUpperCase()}`);
      console.log(`   Hash: ${activity.tx_hash}`);
      console.log(`   Time: ${new Date(activity.block_time).toLocaleString()}`);

      if (activity.type === 'receive' && activity.asset_type === 'erc20') {
        console.log(`   Received: ${activity.value} ${activity.token_metadata?.symbol}`);
        console.log(`   From: ${activity.from}`);
      }

      console.log('   ---');
    });

    return activities;
  } catch (error) {
    console.error('❌ Error fetching activity:', error.message);
  }
}

Collectibles API - Get NFT collections

async function getNFTCollections(walletAddress) {
  try {
    console.log('🖼️ Fetching NFT collections...');

    const response = await axios.get(`${SIM_API_BASE}/evm/collectibles/${walletAddress}?chain_ids=1329`, { headers });

    const collectibles = response.data.entries;

    console.log(`🎨 NFT Collections (${collectibles.length}):`);

    // Group by collection
    const collections = {};
    collectibles.forEach((nft) => {
      if (!collections[nft.contract_address]) {
        collections[nft.contract_address] = {
          name: nft.collection_name,
          items: []
        };
      }
      collections[nft.contract_address].items.push(nft);
    });

    Object.entries(collections).forEach(([address, collection]) => {
      console.log(`📚 ${collection.name} (${collection.items.length} items)`);
      console.log(`   Contract: ${address}`);

      collection.items.slice(0, 3).forEach((nft) => {
        console.log(`   • Token ID: ${nft.token_id}`);
        console.log(`     Name: ${nft.name || 'Unnamed'}`);
        console.log(`     Image: ${nft.image_url || 'No image'}`);
      });

      if (collection.items.length > 3) {
        console.log(`   ... and ${collection.items.length - 3} more`);
      }
      console.log('   ---');
    });

    return collectibles;
  } catch (error) {
    console.error('❌ Error fetching NFTs:', error.message);
  }
}

Advanced use cases

Portfolio analytics dashboard

require('dotenv').config();
const axios = require('axios');

const SIM_API_BASE = 'https://api.sim.dune.com/v1';

const headers = {
  'X-Sim-Api-Key': process.env.SIM_API_KEY,
  'Content-Type': 'application/json'
};

async function buildAdvancedPortfolio(walletAddress) {
  try {
    console.log('📊 Building advanced portfolio analytics...');

    // Get all data in parallel for better performance
    const [balancesRes, transactionsRes, activityRes, nftsRes] = await Promise.all([
      axios.get(`${SIM_API_BASE}/evm/balances/${walletAddress}?chain_ids=1329`, { headers }),
      axios.get(`${SIM_API_BASE}/evm/transactions/${walletAddress}`, {
        headers,
        params: { limit: 50, chain: 'sei' }
      }),
      axios.get(`${SIM_API_BASE}/evm/activity/${walletAddress}?chain_ids=1329`, {
        headers,
        params: { limit: 50 }
      }),
      axios.get(`${SIM_API_BASE}/evm/collectibles/${walletAddress}?chain_ids=1329`, { headers })
    ]);

    const balances = balancesRes.data.balances;
    const transactions = transactionsRes.data.transactions;
    const activities = activityRes.data.activity;
    const nfts = nftsRes.data.entries;

    // Calculate comprehensive metrics
    const totalValue = balances.reduce((sum, asset) => sum + parseFloat(asset.value_usd || 0), 0);
    const seiAssets = balances.filter((b) => b.chain === 'sei');
    const seiValue = seiAssets.reduce((sum, asset) => sum + parseFloat(asset.value_usd || 0), 0);

    console.log('💼 Advanced Portfolio Analytics:');
    console.log(`  Total Portfolio Value: $${totalValue.toFixed(2)}`);
    console.log(`  Sei Network Value: $${seiValue.toFixed(2)} (${((seiValue / totalValue) * 100).toFixed(1)}%)`);
    console.log(`  Total Assets: ${balances.length} tokens`);
    console.log(`  NFT Collections: ${new Set(nfts.map((n) => n.contract_address)).size}`);
    console.log(`  Total NFTs: ${nfts.length}`);

    return { totalValue, seiValue, balances, transactions, activities, nfts };
  } catch (error) {
    console.error('❌ Portfolio analytics error:', error.message);
  }
}

Token analysis tool

require('dotenv').config();
const axios = require('axios');

const SIM_API_BASE = 'https://api.sim.dune.com/v1';

const headers = {
  'X-Sim-Api-Key': process.env.SIM_API_KEY,
  'Content-Type': 'application/json'
};

async function analyzeToken(tokenAddress) {
  try {
    console.log(`🔍 Analyzing token: ${tokenAddress}`);

    // Get comprehensive token data
    const [infoRes, holdersRes] = await Promise.all([
      axios.get(`${SIM_API_BASE}/evm/token-info/${tokenAddress}?chain_ids=1329`, { headers }),
      axios.get(`${SIM_API_BASE}/evm/token-holders/1329/${tokenAddress}`, {
        headers,
        params: { limit: 100 }
      })
    ]);

    const tokenInfo = infoRes.data.tokens[0];
    const holders = holdersRes.data.holders;

    // Calculate holder distribution
    const totalSupply = parseFloat(tokenInfo.total_supply);
    const holderAnalysis = {
      whales: holders.filter((h) => parseFloat(h.balance) / totalSupply > 0.01).length, // >1%
      large: holders.filter((h) => {
        const pct = parseFloat(h.balance) / totalSupply;
        return pct > 0.001 && pct <= 0.01; // 0.1% - 1%
      }).length,
      medium: holders.filter((h) => {
        const pct = parseFloat(h.balance) / totalSupply;
        return pct > 0.0001 && pct <= 0.001; // 0.01% - 0.1%
      }).length
    };

    // Top holder concentration
    const top10Concentration = holders.slice(0, 10).reduce((sum, holder) => sum + parseFloat(holder.balance) / totalSupply, 0) * 100;

    console.log('📊 Token Analysis Results:');
    console.log(`  Name: ${tokenInfo.name} (${tokenInfo.symbol})`);
    console.log(`  Price: ${tokenInfo.price_usd}`);
    console.log(`  Total Supply: ${parseFloat(tokenInfo.total_supply).toLocaleString()}`);
    console.log(`  Total Holders: ${holders.length}`);
    console.log(`  Whales (>1%): ${holderAnalysis.whales}`);
    console.log(`  Large Holders (0.1-1%): ${holderAnalysis.large}`);
    console.log(`  Medium Holders (0.01-0.1%): ${holderAnalysis.medium}`);
    console.log(`  Top 10 Concentration: ${top10Concentration.toFixed(2)}%`);

    return { tokenInfo, holders, holderAnalysis };
  } catch (error) {
    console.error('❌ Token analysis failed:', error.message);
  }
}
// Run the function with a sample token address
analyzeToken('0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392'); // USDC address

Error handling & best practices

Comprehensive error handling

class SimAPIClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.sim.dune.com/v1';
    this.headers = {
      'X-Sim-Api-Key': apiKey,
      'Content-Type': 'application/json'
    };
  }

  async makeRequest(endpoint, params = {}) {
    const maxRetries = 3;
    let retries = 0;

    while (retries < maxRetries) {
      try {
        const response = await axios.get(`${this.baseURL}${endpoint}`, {
          headers: this.headers,
          params,
          timeout: 10000 // 10 second timeout
        });

        return response.data;
      } catch (error) {
        retries++;

        // Handle specific error types
        if (error.response?.status === 429) {
          console.log(`⏳ Rate limit hit. Waiting ${retries * 2} seconds...`);
          await this.sleep(retries * 2000);
          continue;
        }

        if (error.response?.status === 500 && retries < maxRetries) {
          console.log(`🔄 Server error. Retrying (${retries}/${maxRetries})...`);
          await this.sleep(1000);
          continue;
        }

        console.error('❌ API Error:', {
          status: error.response?.status,
          message: error.response?.data?.message || error.message,
          endpoint: endpoint
        });

        throw error;
      }
    }
  }

  sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
}

Rate limiting

class RateLimitedClient {
  constructor(apiKey, requestsPerSecond = 10) {
    this.client = new SimAPIClient(apiKey);
    this.requestsPerSecond = requestsPerSecond;
    this.lastRequest = 0;
  }

  async throttledRequest(endpoint, params) {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;
    const minInterval = 1000 / this.requestsPerSecond;

    if (timeSinceLastRequest < minInterval) {
      await new Promise((resolve) => setTimeout(resolve, minInterval - timeSinceLastRequest));
    }

    this.lastRequest = Date.now();
    return this.client.makeRequest(endpoint, params);
  }
}

Troubleshooting

Error	Cause	Solution
`Invalid API key`	Wrong or expired key	Check the API key in the dashboard
`Rate limit exceeded`	Too many requests	Implement exponential backoff
`Chain not supported`	The chain is not supported	Check the list of supported chains
`Invalid address format`	Malformed wallet address	Validate the address format
`Request timeout`	Network issues	Increase the timeout and add retries
`Insufficient data`	New address/contract	Wait for indexing to complete

Resources

Official documentation

Sim documentation: https://docs.sim.dune.com
Sim dashboard: https://sim.dune.com
Sei explorer: https://seiscan.io

Community resources

Dune Discord: https://discord.gg/dune
Sei Discord: https://discord.gg/sei

Next steps

To scale your application, implement caching, database storage, and horizontal scaling.
Build a frontend, such as a React or Vue.js dashboard, to visualize your data.
Implement machine learning for predictive analytics.
Build custom indexers, which are specialized data pipelines for specific protocols.
Connect your application to other services, such as price feeds and news APIs.

​Overview

​What this guide teaches you:

​Some use cases:

​Supported APIs

​Balances API

​Transactions API

​Token Info API

​Token Holders API

​Activity API

​Collectibles API

​Quick start

​1. Getting your API key

​2. Project setup

​3. Your first API call

​API examples

​Balances API - Get token balances

​Transactions API - Monitor wallet transactions

​Token Info API - Get token metadata

​Token Holders API - Find top holders

​Activity API - Track swaps and transfers

​Collectibles API - Get NFT collections

​Advanced use cases

​Portfolio analytics dashboard

​Token analysis tool

​Error handling & best practices

​Comprehensive error handling

​Rate limiting

​Troubleshooting

​Resources

​Official documentation

​Community resources

​Next steps

Overview

What this guide teaches you:

Some use cases:

Supported APIs

Balances API

Transactions API

Token Info API

Token Holders API

Activity API

Collectibles API

Quick start

1. Getting your API key

2. Project setup

3. Your first API call

API examples

Balances API - Get token balances

Transactions API - Monitor wallet transactions

Token Info API - Get token metadata

Token Holders API - Find top holders

Activity API - Track swaps and transfers

Collectibles API - Get NFT collections

Advanced use cases

Portfolio analytics dashboard

Token analysis tool

Error handling & best practices

Comprehensive error handling

Rate limiting

Troubleshooting

Resources

Official documentation

Community resources

Next steps