Sim APIs

https://docs.sim.dune.com/
Admin
Sim APIs provide fast, reliable access to real-time blockchain activity and ownership data for...
Tokens:489,312
Snippets:2,651
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Dune Go Client

Source: https://docs.sim.dune.com/dune-analytics-api

Install the Dune Go client library using go get. This enables interaction with the Dune API from Go applications.

```bash
go get github.com/duneanalytics/duneapi-client-go

```

--------------------------------

### Start Express Server

Source: https://docs.sim.dune.com/llms-full.txt

Run this command in the terminal to start the Express server. Ensure your .env file has the correct API keys.

```bash
node server.js
```

--------------------------------

### Install Project Dependencies

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

Installs necessary packages: Express.js for the server, EJS for templating, dotenv for environment variables, and numbro for number formatting.

```bash
npm install express ejs dotenv numbro
```

--------------------------------

### Quick Endpoint Guide

Source: https://docs.sim.dune.com/build-with-ai

A quick reference guide for common tasks and their corresponding Sim API endpoints.

```APIDOC
## Quick Endpoint Guide for Agents

| I want to...                              | Use this endpoint                                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| Get a wallet's token balances             | [Balances](/evm/balances) (EVM) or [Balances](/svm/balances) (Solana)                 |
| See a wallet's recent transfers and swaps | [Activity](/evm/activity)                                                             |
| Get raw transaction data with logs        | [Transactions](/evm/transactions) (EVM) or [Transactions](/svm/transactions) (Solana) |
| Look up token price and metadata          | [Token Info](/evm/token-info)                                                         |
| See who holds a token                     | [Token Holders](/evm/token-holders)                                                   |
| Get a wallet's NFTs                       | [Collectibles](/evm/collectibles)                                                     |
| Get a wallet's DeFi positions             | [DeFi Positions](/evm/defi-positions)                                                 |
| Get real-time notifications               | [Subscriptions](/evm/subscriptions) (webhooks)                                        |

<Note>
  **EVM vs Solana:** EVM endpoints use `chain_ids` with numeric IDs (e.g., `1` for Ethereum, `8453` for Base). Solana endpoints use `chains` with string values (`solana`, `eclipse`, `all`).
</Note>
```

--------------------------------

### Native Token Request Example

Source: https://docs.sim.dune.com/evm/token-info

This is an example of an HTTP GET request to retrieve information about a native chain asset. Ensure the `?chain_ids` query parameter is included.

```http
GET /v1/evm/token-info/native?chain_ids=1
```

--------------------------------

### Install Project Dependencies

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Install necessary npm packages: Express for the web server, postgres for database interaction, and csv-parse for handling CSV data.

```bash
npm install express postgres csv-parse
```

--------------------------------

### Initialize Tracker Setup

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Trigger the initial setup process for the top holders tracker bot. This involves fetching top holder addresses from a CSV file and creating necessary webhooks for monitoring.

```bash
# 1. Fetch top holder addresses from your tokens.csv
curl -X POST https://your-url.com/setup/fetch-holders
```

```bash
# 2. Create webhooks for monitoring
curl -X POST https://your-url.com/setup/create-webhooks
```

--------------------------------

### Install Dune TypeScript Client

Source: https://docs.sim.dune.com/dune-analytics-api

Install the Dune TypeScript client library using npm. This is required to use the Dune API with TypeScript.

```bash
npm install @duneanalytics/client

```

--------------------------------

### Install Project Dependencies

Source: https://docs.sim.dune.com/evm/build-a-realtime-chat-agent

Installs the necessary packages: express for the web server, openai for interacting with OpenAI's API, and dotenv for environment variable management.

```bash
npm install express openai dotenv
```

--------------------------------

### Get Token Holders (Python)

Source: https://docs.sim.dune.com/chains/wemix

This Python example shows how to retrieve token holder information using the requests library. Remember to substitute YOUR_API_KEY with your valid API key. The chain ID and token address are mandatory.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/token-holders/1111/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Install Dune Python Client

Source: https://docs.sim.dune.com/dune-analytics-api

Install the Dune Python client library using pip. This is the first step to programmatically interact with the Dune API in Python.

```bash
pip install dune-client

```

--------------------------------

### Create Project Directory and Initialize Node.js

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

Sets up a new project directory, initializes npm, and configures it to use ES modules.

```bash
mkdir wallet-ui
cd wallet-ui
npm init -y
npm pkg set type="module"
```

--------------------------------

### Initialize Project Directory and npm

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Create a new directory for the project, navigate into it, and initialize npm for package management.

```bash
mkdir top-holders-tracker
cd top-holders-tracker
npm init -y
```

--------------------------------

### ERC20 Token Request Example

Source: https://docs.sim.dune.com/evm/token-info

This is an example of an HTTP GET request to retrieve information about an ERC20 token using its contract address. The `?chain_ids` parameter is mandatory.

```http
GET /v1/evm/token-info/0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca?chain_ids=8453
```

--------------------------------

### Create Project Directory and Initialize Node.js

Source: https://docs.sim.dune.com/evm/build-a-realtime-chat-agent

Sets up the project directory and initializes a new Node.js project with module support.

```bash
mkdir simchat
cd simchat
npm init -y
npm pkg set type="module"
```

--------------------------------

### Initialize Server and Database Tables

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Set up an Express server, configure database connections using Supabase, and initialize necessary tables (top_holders, subscribers, webhooks) on startup. Includes environment variable loading and basic error handling.

```javascript
import express from "express";
import postgres from "postgres";
import { setTimeout } from "node:timers/promises";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { parse } from "csv-parse/sync";

// ES Module directory resolution
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 1. Environment Setup
const SIM_API_KEY = process.env.SIM_API_KEY || "";
const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN || "";
const WEBHOOK_BASE_URL = process.env.WEBHOOK_BASE_URL || "";
const PORT = process.env.PORT || 3001;
const DATABASE_URL = process.env.DATABASE_URL || "";

if (!SIM_API_KEY || !TELEGRAM_BOT_TOKEN || !DATABASE_URL) {
  console.error("Missing required environment variables");
  process.exit(1);
}

// 2. Database Setup (PostgreSQL via Supabase)
const sql = postgres(DATABASE_URL);

// Initialize Tables
async function initDatabase() {
  await sql`
    CREATE TABLE IF NOT EXISTS top_holders (
      id SERIAL PRIMARY KEY,
      token_address TEXT,
      chain_id INTEGER,
      symbol TEXT,
      blockchain TEXT,
      holders_json TEXT,
      UNIQUE(token_address, chain_id)
    )
  `;

  await sql`
    CREATE TABLE IF NOT EXISTS subscribers (
      chat_id TEXT PRIMARY KEY,
      subscribed_at TEXT
    )
  `;

  await sql`
    CREATE TABLE IF NOT EXISTS webhooks (
      id TEXT PRIMARY KEY,
      token_address TEXT,
      chain_id INTEGER,
      active INTEGER DEFAULT 1
    )
  `;
}

// Initialize database when module loads
initDatabase().catch(err => {
  console.error("Failed to initialize database:", err);
});

// 3. Express Setup
const app = express();
app.use(express.json()); // Parse JSON bodies

app.get("/health", (req, res) => {
  res.json({ ok: true });
});

// ... route definitions go here (added in subsequent sections) ...

// Start server for local development
// For Vercel deployment, export the app instead (see Deploy section)
const server = app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

```

--------------------------------

### Filter by Multiple Activity Types

Source: https://docs.sim.dune.com/evm/activity.md

Example GET request to filter by multiple activity types. Accepts a comma-separated list of accepted values.

```http
GET /v1/evm/activity/{address}?activity_type=send,receive
```

--------------------------------

### Basic Express Server Setup with OpenAI Integration

Source: https://docs.sim.dune.com/evm/build-a-realtime-chat-agent

Sets up an Express server, initializes the OpenAI client using API keys from environment variables, and serves the chat.html file. It also includes logic for handling ES modules.

```javascript
import express from 'express';
import { OpenAI } from 'openai';
import path from 'path';
import { fileURLToPath } from 'url';
import dotenv from 'dotenv';

dotenv.config();

// Set up __dirname for ES modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Initialize Express
const app = express();
app.use(express.json());

// Initialize OpenAI client
const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY
});

// Sim API key
const SIM_API_KEY = process.env.SIM_API_KEY;

// Serve the HTML file
app.get('/', (req, res) => {
    res.sendFile(path.join(__dirname, 'chat.html'));
});

// Start server
const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
});
```

--------------------------------

### Filter by Activity Type and Asset Type

Source: https://docs.sim.dune.com/evm/activity.md

Example GET request to filter activities by type and asset. Use comma-separated values for multiple options.

```http
GET /v1/evm/activity/{address}?activity_type=receive&asset_type=native
```

--------------------------------

### Basic Express.js Server Setup

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

Initializes an Express.js server, configures EJS templating, static file serving, and sets up a basic home route. Loads environment variables including the Sim API key.

```javascript
import express from 'express';
import numbro from 'numbro';
import dotenv from 'dotenv';
import path from 'path';
import { fileURLToPath } from 'url';

// Load environment variables
dotenv.config();
const SIM_API_KEY = process.env.SIM_API_KEY;

if (!SIM_API_KEY) {
    console.error("FATAL ERROR: SIM_API_KEY is not set in your environment variables.");
    process.exit(1);
}

// Set up __dirname for ES modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Initialize Express
const app = express();

// Configure Express settings
app.set('view engine', 'ejs');
app.set('views', path.join(__dirname, 'views'));
app.use(express.static(path.join(__dirname, 'public')));

// Add our home route
app.get('/', async (req, res) => {
    const { 
        walletAddress = '',
        tab = 'tokens' // Default to tokens tab
    } = req.query;

    let tokens = [];
    let totalWalletUSDValue = 0;
    let activities = []; // For Guide 2
    let collectibles = []; // For Guide 3

    // In later steps, these arrays will be populated with API data.
    res.render('wallet', {
        walletAddress: walletAddress,
        currentTab: tab,
        totalWalletUSDValue: '$0.00', // Will be calculated later in this guide.
        tokens: tokens,
        activities: activities,
        collectibles: collectibles
    });
});

// Start the server
app.listen(3001, () => {
    console.log(`Server running at http://localhost:3001`);
});
```

--------------------------------

### Filter by Token Address and Activity Type

Source: https://docs.sim.dune.com/evm/activity.md

Example GET request to filter by a specific token address and activity type. Note that swap and call activities are excluded when filtering by token address.

```http
GET /v1/evm/activity/{address}?token_address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&activity_type=send
```

--------------------------------

### Get Token Holders by Chain and Token Address

Source: https://docs.sim.dune.com/chains/corn

Use this endpoint to retrieve a list of token holders for a specific token. Replace 'YOUR_API_KEY' with your actual API key. The chain ID '21000000' and token address '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' are examples and should be replaced with the desired chain and token.

```bash
curl -X GET "https://api.sim.dune.com/v1/evm/token-holders/21000000/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" \
    -H "X-Sim-Api-Key: YOUR_API_KEY"
```

```javascript
const response = await fetch("https://api.sim.dune.com/v1/evm/token-holders/21000000/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", {
    headers: { "X-Sim-Api-Key": "YOUR_API_KEY" }
  });
  const data = await response.json();
```

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/token-holders/21000000/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Create Project Structure and Core Files

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

Sets up the necessary directories (views, public) and core files (server.js, views/wallet.ejs, public/styles.css) for the wallet application.

```bash
mkdir views
mkdir public
touch server.js
touch views/wallet.ejs
touch public/styles.css
```

--------------------------------

### Create Main Application Files

Source: https://docs.sim.dune.com/evm/build-a-realtime-chat-agent

Creates the server.js and chat.html files for the backend and frontend of the chat application.

```bash
touch server.js
touch chat.html
```

--------------------------------

### Get Activity for HyperEVM (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python to get activity data for an address on HyperEVM. Remember to substitute YOUR_API_KEY.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/activity/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=999",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Verify Project Structure

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

After setting up the project, verify that the directory structure matches the expected layout for the wallet UI application.

```bash
wallet-ui/
├── server.js             # Main application file with Express server
├── views/                # Directory for EJS templates
│   └── wallet.ejs        # Main wallet UI template
├── public/               # Directory for static assets
│   └── styles.css        # CSS styling for the wallet UI
├── package.json          # Project configuration
├── package-lock.json     # Dependency lock file (if `npm install` was run)
├── node_modules/         # Installed packages (if `npm install` was run)
└── .env                  # Your environment variables
```

--------------------------------

### Webhook Setup

Source: https://docs.sim.dune.com/agent-reference

Sets up a webhook subscription to receive real-time notifications for specific events (e.g., balance changes). Requires a valid webhook URL and subscription details.

```APIDOC
## POST /v1/evm/subscriptions

### Description
Sets up a webhook subscription to receive real-time notifications for specific events (e.g., balance changes). Requires a valid webhook URL and subscription details.

### Method
POST

### Endpoint
`/v1/evm/subscriptions`

### Parameters
#### Request Body
- **webhook_url** (string) - Required - The URL where notifications will be sent.
- **type** (string) - Required - The type of subscription (e.g., `balances`).
- **chain_ids** (array) - Required - A list of chain IDs to subscribe to (e.g., `[1, 8453]`).
- **addresses** (array) - Required - A list of wallet addresses to monitor (e.g., `["0x..."]`).

### Request Example
```json
{
  "webhook_url": "https://your-webhook-url.com",
  "type": "balances",
  "chain_ids": [1, 8453],
  "addresses": ["0x1234567890abcdef1234567890abcdef12345678"]
}
```

### Response
#### Success Response (200)
- **subscription_id** (string) - The unique identifier for the created subscription.
- **message** (string) - A confirmation message.

#### Error Response (400)
- **error** (string) - Description of the error (e.g., invalid input).

### Headers
- **Dune-Webhook-Signature** (string) - Signature for validating incoming webhook requests.
- **Dune-Webhook-Retry-Index** (string) - Index for retrying failed webhook deliveries.
```

--------------------------------

### Get Activity for Redstone (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python to get activity data for an address on Redstone. Remember to include your API key in the request headers.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/activity/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=690",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Get Transactions for HyperEVM (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get transaction data for an address on HyperEVM. Remember to substitute YOUR_API_KEY.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/transactions/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=999",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Get Balances for HyperEVM (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get balance information for an address on HyperEVM. Remember to replace YOUR_API_KEY.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=999",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Webhook Setup

Source: https://docs.sim.dune.com/llms-full.txt

Sets up a webhook subscription to receive real-time notifications for specific event types.

```APIDOC
## POST /v1/evm/subscriptions

### Description
Sets up a webhook subscription to receive real-time notifications for specific event types (e.g., balances) for given wallet addresses and chains. Requires validation using the `dune-webhook-signature` header.

### Method
POST

### Endpoint
/v1/evm/subscriptions

### Parameters
#### Request Body
- **webhook_url** (string) - Required - The URL where notifications will be sent.
- **type** (string) - Required - The type of event to subscribe to (e.g., "balances").
- **chain_ids** (array) - Required - An array of chain IDs to monitor.
- **addresses** (array) - Required - An array of wallet addresses to monitor.

### Request Example
```json
{
  "webhook_url": "https://your-webhook-receiver.com/dune",
  "type": "balances",
  "chain_ids": [1, 8453],
  "addresses": ["0x..."]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the subscription was created.

#### Headers
- **dune-webhook-signature** (string) - Signature to validate incoming webhook requests.
- **dune-webhook-retry-index** (string) - Index for retry tracking of webhook deliveries.

### Response Example
```json
{
  "message": "Subscription created successfully."
}
```
```

--------------------------------

### Get Balances for Metis (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get balance information for an address on Metis. The API key is required in the headers.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=1088",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Start Express Server

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Run your Express application to handle incoming requests and webhooks.

```bash
npm start
```

--------------------------------

### Get Transactions for Katana (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get transaction information for an address on Katana. Include chain_ids=747474 and your API key.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/transactions/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=747474",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Retrieve Token Balances with JavaScript

Source: https://docs.sim.dune.com/llms-full.txt

This JavaScript example demonstrates how to fetch token balances for a given wallet address using the Sim API. Ensure you replace YOUR_API_KEY with your valid API key.

```javascript
const options = {method: 'GET', headers: {'X-Sim-Api-Key': 'YOUR_API_KEY'};

fetch('https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Get Balances for Katana (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get balance information for an address on Katana. Include chain_ids=747474 and your API key.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=747474",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Load Initial Welcome Messages

Source: https://docs.sim.dune.com/llms-full.txt

Displays a welcome message and a list of suggested queries when the chat interface loads. Uses `setTimeout` to stagger the display of messages.

```javascript
// Initial welcome messages
function loadInitialMessages() {
    addMessage("Hi! I'm your Sim APIs assistant. I can help you explore blockchain data across 60+ EVM chains and Solana.", "system");
    
    setTimeout(() => {
        addMessage("Try asking me about:\n\n- Token balances for any wallet\n- Transaction history\n- NFT collections\n- Token information and pricing\n- Solana token data", "system");
    }, 500);
}

// Load initial messages on page load
```

--------------------------------

### Get Activity for Metis (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get activity information for an address on Metis. The API key must be provided in the headers.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/activity/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=1088",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Configure Environment Variables

Source: https://docs.sim.dune.com/evm/build-a-realtime-wallet

Creates a .env file and adds the SIM_API_KEY. Ensure this file is added to .gitignore to prevent committing sensitive keys.

```plaintext
# Your Sim API key (required)
SIM_API_KEY=your_api_key_here
```

--------------------------------

### Get Activity Data for Katana (Python)

Source: https://docs.sim.dune.com/llms-full.txt

Use Python's requests library to get activity information for an address on Katana. Include chain_ids=747474 and your API key.

```python
import requests

response = requests.get(
    "https://api.sim.dune.com/v1/evm/activity/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain_ids=747474",
    headers={"X-Sim-Api-Key": "YOUR_API_KEY"}
)
data = response.json()
```

--------------------------------

### Get Token Information

Source: https://docs.sim.dune.com/evm/token-info

Retrieves information about a specific token or a list of tokens by their contract address. You can specify the chain ID to get information for a token on a particular blockchain.

```APIDOC
## GET /v1/tokens

### Description
Retrieves information about tokens. You can query by contract address and optionally specify a chain ID.

### Method
GET

### Endpoint
/v1/tokens

### Parameters
#### Query Parameters
- **contract_address** (string) - Required - The contract address of the token or 'native' for the native token.
- **chain_id** (integer) - Optional - The ID of the blockchain to query for the token.

### Response
#### Success Response (200)
- **contract_address** (string) - The contract address of the token or 'native' for the native token.
- **tokens** (array) - Array of token information across different chains.
  - **chain** (string) - The name of the blockchain.
  - **chain_id** (integer) - The ID of the blockchain.
  - **symbol** (string) - The token symbol.
  - **name** (string) - The token name.
  - **decimals** (integer) - The number of decimals for the token.
  - **price_usd** (number) - The price of the token in USD.
  - **historical_prices** (array) - Historical price points for the requested offsets. Only present when the historical_prices query parameter is provided.
  - **total_supply** (string) - The total supply of the token.
  - **market_cap** (number) - The market capitalization of the token.
  - **logo** (string) - URL to the token logo.
- **warnings** (array) - Array of warnings that occurred during request processing. Warnings indicate non-fatal issues (e.g., unsupported chain IDs) where the request can still be partially fulfilled.
  - **code** (string) - Warning code identifier (e.g., 'UNSUPPORTED_CHAIN_IDS').
  - **message** (string) - Human-readable warning message.
  - **chain_ids** (array) - List of chain IDs that triggered this warning (for chain-related warnings).
- **next_offset** (string) - Pagination cursor for the next page of results.

#### Error Response (400)
- **error** (string) - Error message indicating invalid input, such as an invalid address or chain ID.

#### Error Response (401)
- **error** (string) - 'invalid API Key' - Returned when the API key is invalid or missing.

#### Error Response (404)
- **value** (string) - 'Token not found' - Returned when the specified token or resource cannot be found.

#### Error Response (429)
- **error** (string) - 'Too many requests. Please contact sales@dune.com to increase your limit.' - Returned when the rate limit is exceeded.

#### Error Response (500)
- **value** (string) - 'Failed to read from store: connection timeout' - Returned for internal server errors, such as store read failures.

### Request Example
```json
{
  "example": "/v1/tokens?contract_address=0x1f9840a85d5af5bf1d1762f925bdaddc4201f984&chain_id=1"
}
```

### Response Example
```json
{
  "example": {
    "contract_address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
    "tokens": [
      {
        "chain": "ethereum",
        "chain_id": 1,
        "symbol": "UNI",
        "name": "Uniswap",
        "decimals": 18,
        "price_usd": 7.50,
        "total_supply": "1000000000.0",
        "market_cap": 7500000000.0,
        "logo": "https://example.com/uni.png"
      }
    ],
    "warnings": [],
    "next_offset": null
  }
}
```
```

--------------------------------

### Monitor Swap Activities with Webhook

Source: https://docs.sim.dune.com/evm/subscriptions/create-webhook

Set up a webhook to track specific on-chain activities, such as token swaps, for a given address. This example focuses on filtering for 'swap' activities.

```json
{
  "name": "Swap Monitor",
  "url": "https://example.com/webhooks/swaps",
  "type": "activities",
  "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
  "activity_type": "swap"
}
```

--------------------------------

### Get Token Balances

Source: https://docs.sim.dune.com/llms-full.txt

Access realtime token balances for a given address. Get comprehensive details about native and ERC20 tokens, including token metadata and USD valuations.

```APIDOC
## GET /v1/evm/balances/{address}

### Description
Access realtime token balances for a given address. Get comprehensive details about native and ERC20 tokens, including token metadata and USD valuations.

### Method
GET

### Endpoint
/v1/evm/balances/{address}

### Parameters
#### Path Parameters
- **address** (string) - Required - The wallet address to query balances for.

#### Query Parameters
- **chain_ids** (string) - Optional - Comma-separated list of chain IDs to query. Defaults to low-latency networks.
- **exclude_unpriced** (boolean) - Optional - If true, excludes tokens without available pricing data.
- **exclude_spam_tokens** (boolean) - Optional - If true, excludes tokens with less than $100 USD liquidity.
- **metadata** (string) - Optional - If set to `pools`, includes liquidity pool details for pricing.
- **historical_prices** (string) - Optional - Comma-separated list of hours in the past to retrieve historical prices for (max 3 offsets).

### Response
#### Success Response (200)
- **balances** (array) - List of token balances.
  - **symbol** (string) - Token symbol.
  - **balance** (string) - Token balance amount.
  - **decimals** (integer) - Token decimal places.
  - **usd_valuation** (number) - Token valuation in USD.
  - **price_usd** (number) - Current price of the token in USD.
  - **pool_size** (number) - Liquidity pool size in USD.
  - **low_liquidity** (boolean) - True if liquidity is below $10,000.
  - **historical_prices** (array) - List of historical prices (if requested).
    - **offset_hours** (integer) - Number of hours in the past.
    - **price_usd** (number) - Token price in USD at the specified offset.
- **warnings** (array) - List of warnings for unsupported chain IDs.
  - **chain_id** (integer) - The unsupported chain ID.
  - **message** (string) - Description of the warning.

### Request Example
```json
{
  "balances": [
    {
      "symbol": "ETH",
      "balance": "1.2345",
      "decimals": 18,
      "usd_valuation": 4812.34,
      "price_usd": 3896.83,
      "pool_size": 1000000,
      "low_liquidity": false,
      "historical_prices": [
        { "offset_hours": 8760, "price_usd": 2816.48 },
        { "offset_hours": 720,  "price_usd": 3710.38 },
        { "offset_hours": 168,  "price_usd": 3798.63 }
      ]
    }
  ],
  "warnings": [
    {
      "chain_id": 123,
      "message": "Chain ID 123 is not supported."
    }
  ]
}
```
```

--------------------------------

### Configure Environment Variables

Source: https://docs.sim.dune.com/evm/build-a-realtime-chat-agent

Creates a .env file and adds required API keys for OpenAI and Sim. Ensure this file is added to .gitignore to protect sensitive keys.

```plaintext
# Required API keys
OPENAI_API_KEY=your_openai_api_key_here
SIM_API_KEY=your_sim_api_key_here
```

--------------------------------

### Expose Local Server with ngrok

Source: https://docs.sim.dune.com/evm/build-a-top-holders-tracker-bot

Use ngrok to expose your local development server to the public internet, allowing external services like Sim Subscriptions to send webhooks to it. Ensure you update your .env file with the provided ngrok URL.

```bash
ngrok http 3001
```

--------------------------------

### Fetch Supported Chains (Python)

Source: https://docs.sim.dune.com/evm/supported-chains

This Python script uses the requests library to get the list of supported EVM chains. Remember to substitute 'YOUR_API_KEY' with your actual API key.

```python
import requests

url = "https://api.sim.dune.com/v1/evm/supported-chains"
headers = {"X-Sim-Api-Key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)
```

--------------------------------

### Example Stablecoin Balances Response

Source: https://docs.sim.dune.com/evm/stablecoins

This is an example of the JSON response structure for the Stablecoin Balances endpoint, showing details for each stablecoin including chain, address, amount, symbol, decimals, price, and value in USD.

```json
{
  "request_time": "2026-02-05T10:31:08Z",
  "response_time": "2026-02-05T10:31:08Z",
  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "balances": [
    {
      "chain": "ethereum",
      "chain_id": 1,
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "1000000000",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "price_usd": 1.0,
      "value_usd": 1000.0
    },
    {
      "chain": "gnosis",
      "chain_id": 100,
      "address": "native",
      "amount": "100000000000000000000",
      "symbol": "XDAI",
      "decimals": 18,
      "price_usd": 1.0,
      "value_usd": 100.0
    }
  ]
}
```

--------------------------------

### Example API Response for Supported Chains (Error Codes)

Source: https://docs.sim.dune.com/llms-full.txt

These JSON examples illustrate potential error responses from the Supported Chains API, including Bad Request, Unauthorized, Not Found, Too Many Requests, and Internal Server Error.

```json
{
  "error": "Bad Request"
}
```

```json
{
  "error": "Unauthorized"
}
```

```json
{
  "error": "Not Found"
}
```

```json
{
  "error": "Too many requests"
}
```

```json
{
  "error": "Internal Server Error"
}
```
Tokens:
Raw