Dune Sim to Codex

Dune is sunsetting Sim on August 1, 2026 and pointing customers at three alternatives, Codex among them. This guide maps every Sim endpoint to its closest Codex equivalent, shows working side-by-side examples for the most common patterns, and ends with a copy-paste prompt you can hand to an LLM to translate the rest of your integration.

Sim’s documentation will go offline alongside the API. If you’re reading this after August 1, 2026, the Sim endpoint paths and parameters referenced here are historical.

Mental model

Sim is a REST API, organized by chain family (EVM, SVM), with one resource per URL. Codex is a single GraphQL Supergraph: one endpoint (https://graph.codex.io/graphql), one auth header, one query language, and the network is just a parameter on each query (networkId: Int on most queries, networks: [Int!] on balances). Most patterns that took two or three Sim calls collapse into a single Codex query. A few practical consequences:

You don’t need different code paths per chain. Codex covers Ethereum, Solana, and 100+ networks under the same schema.
Real-time data is first-class. Anything available as a query usually has a matching GraphQL subscription over WebSocket, plus an option to fan out to your servers via webhooks.
You request only the fields you need, so payloads are usually smaller than the equivalent Sim response.

If you’ve never used GraphQL, Learn GraphQL is a 10-minute primer that’s enough to follow the rest of this guide.

Authentication

Sim uses an X-Sim-Api-Key header. Codex uses an Authorization header with your API key from the dashboard.

Sim

curl https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045 \
  -H "X-Sim-Api-Key: $SIM_API_KEY"

Codex

curl https://graph.codex.io/graphql \
  -H "Authorization: $CODEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ balances(input: { walletAddress: \"0xd8da6bf26964af9d7eed9e03e53415d37aa96045\", networks: [1] }) { items { tokenId balance shiftedBalance walletId } } }"}'

If you serve requests from a browser, generate a short-lived JWT with createApiTokens (a Growth or Enterprise plan feature) and pass it as Bearer <token> (see Authentication for the full pattern).

Endpoint mapping

Sim endpoint	Codex equivalent	Notes
`GET /v1/evm/balances/{address}`	`balances` query	Native + ERC-20 with USD pricing inline (`balanceUsd`, `tokenPriceUsd`). Works on Solana too. Requires a Growth or Enterprise plan.
`GET /v1/evm/balances/{address}/token/{token_address}`	`balances` with `tokens: ["<address>:<networkId>"]`	Same query, narrowed to specific tokens (up to 200 per request).
`GET /v1/evm/balances/{address}/stablecoins`	`balances` with a curated stablecoin `tokens` list, or `filterTokens`	No dedicated stablecoin endpoint; pass the stablecoin token IDs you care about.
`GET /v1/evm/activity/{address}`	`getTokenEventsForMaker` query	Sim returns transfers, NFT moves, approvals, swaps, and decoded contract calls; Codex returns DEX events only (Swap, Mint, Burn, Sync, Collect, CollectProtocol, PoolBalanceChanged, LiquidityLock). If your code uses `activity_type=swap`, the port is straightforward; for `approve`/`call`/NFT activity, see “Gaps” below.
`GET /v1/evm/transactions/{address}`	`getTokenEventsForMaker` query	Same DEX-only caveat. Codex doesn’t expose raw transactions with gas, nonce, or decoded calldata; see “Gaps” below.
`GET /v1/evm/collectibles/{address}`	Not supported	Codex is a fungible-token API. See “Gaps” below.
`GET /v1/evm/token-info/{address}?chain_ids=...`	`token` query + `getTokenPrices`	Codex returns richer metadata: safety signals, launchpad context, 19 social link fields, supply, image URLs.
`GET /v1/evm/token-holders/{chain_id}/{address}`	`holders` query	Returns ranked holders with balances. `top10HoldersPercent` is returned on the same response, or available as a standalone `top10HoldersPercent` query. Codex’s `limit` defaults to 50, max 200 (Sim defaults to 500). Paginate to match. Requires a Growth or Enterprise plan.
`GET /v1/evm/search/tokens?query=...`	`filterTokens` query	Far more powerful: rank by trending score, volume, market cap, plus filter clauses. Paginates up to 200 per request (Sim caps at 50).
`GET /v1/evm/defi/positions/{address}`	Partial via `liquidityMetadata` / `liquidityMetadataByToken`	Codex exposes pair-level liquidity and lock breakdowns, not aggregated per-wallet LP positions across protocols. Requires Growth or Enterprise plan. See “Gaps” below.
`GET /v1/evm/defi/supported-protocols`	Not directly supported	Codex doesn’t aggregate per-wallet DeFi positions, so there’s no protocol-family list. Use `filterTokens` with `filters: { exchangeId: ... }` if you need to confirm coverage of a specific DEX.
`GET /v1/evm/supported-chains`	`getNetworks` query	Returns the full list of networks Codex indexes, including chain IDs. Takes no arguments.
`GET /beta/svm/balances/{address}`	`balances` with `networks: [1399811149]`	Same query, different network ID. Note Sim’s SVM endpoints use `chains=solana,eclipse` (not `chain_ids`) — drop the param shape when porting.
`GET /beta/svm/transactions/{address}`	`getTokenEventsForMaker`	Same shape as EVM; Sim’s response wraps raw RPC data, Codex returns decoded DEX events.
Sim Balances webhook (`POST /beta/evm/subscriptions/webhooks`, `type: balances`)	`onBalanceUpdated` subscription or `createWebhooks` with `TOKEN_TRANSFER_EVENT`	Codex’s `TOKEN_TRANSFER_EVENT` filters by target wallet with direction `TO`/`FROM`/both.
Sim Activities webhook (`type: activities`)	`onEventsCreatedByMaker` subscription or `TOKEN_PAIR_EVENT` webhook	Subscription gives per-wallet streams; `TOKEN_PAIR_EVENT` accepts a `maker` filter condition, so you can also fire it for a single wallet’s trades server-side.
Sim Transactions webhook (`type: transactions`)	No direct equivalent	Codex doesn’t fan out raw txs. Closest is `TOKEN_TRANSFER_EVENT` for transfer-style traffic.

Plan requirements. A few of the mappings above need a Growth or Enterprise plan: balances, holders, liquidityMetadata, every WebSocket subscription, and the createWebhooks and createApiTokens mutations. The rest, including getTokenEventsForMaker, token, getTokenPrices, filterTokens, getNetworks, and top10HoldersPercent, don’t carry that requirement. Check the dashboard for your plan’s current limits.

Side-by-side examples

The four patterns below cover most Sim integrations. Token addresses and the wallet (vitalik.eth’s resolved address) are real and the queries are runnable in our Explorer. Codex’s balances does not resolve ENS names, so always pass the raw address.

1. Wallet balances

curl "https://api.sim.dune.com/v1/evm/balances/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?chain_ids=1" \
  -H "X-Sim-Api-Key: $SIM_API_KEY"

import { Codex } from "@codex-data/sdk"

const sdk = new Codex(process.env.CODEX_API_KEY!)

const { balances } = await sdk.queries.balances({
  input: {
    walletAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    networks: [1],
  },
})

balances.items.forEach((b) => {
  console.log(b.tokenId, b.shiftedBalance)
})

query WalletBalances {
  balances(
    input: {
      walletAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
      networks: [1]
    }
  ) {
    items {
      tokenId
      balance
      shiftedBalance
      balanceUsd
      tokenPriceUsd
      walletId
    }
  }
}

USD pricing is returned inline: balanceUsd and tokenPriceUsd come back on each item, so most Sim integrations that hit /v1/evm/balances and read value_usd only need one Codex call, not two. Reach for getTokenPrices only when you need historical prices, a specific pool, or per-block pricing (capped at 25 inputs per request). If balances feel stale (Codex caches them), call the refreshBalances mutation first.

2. Wallet activity

Sim’s activity feed filters by activity_type across send, receive, mint, burn, swap, approve, call, and transfer. Codex’s getTokenEventsForMaker returns DEX-only events (Swap, Mint, Burn, Sync, Collect, CollectProtocol, PoolBalanceChanged, LiquidityLock) and exposes the same set as an eventType filter on the query. If your Sim integration is mostly swap, the port is one-for-one. If it leans on approve / call or NFT moves, see “Gaps” below.

curl "https://api.sim.dune.com/v1/evm/activity/0xd8da6bf26964af9d7eed9e03e53415d37aa96045?chain_ids=1&limit=25" \
  -H "X-Sim-Api-Key: $SIM_API_KEY"

query MakerActivity {
  getTokenEventsForMaker(
    query: {
      maker: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
      networkId: 1
    }
    limit: 25
  ) {
    items {
      timestamp
      eventType
      eventDisplayType
      maker
      transactionHash
      networkId
      token0Address
      token1Address
      quoteToken
      data {
        ... on SwapEventData {
          amountNonLiquidityToken
          priceUsd
        }
      }
    }
    cursor
  }
}

For a live feed instead of polling, swap the query for the onEventsCreatedByMaker subscription over WebSocket.

3. Token holders

curl "https://api.sim.dune.com/v1/evm/token-holders/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?limit=50" \
  -H "X-Sim-Api-Key: $SIM_API_KEY"

query TopHolders {
  holders(
    input: { tokenId: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48:1" }
  ) {
    count
    top10HoldersPercent
    items {
      walletId
      tokenId
      address
      balance
      shiftedBalance
    }
  }
}

A few things to note: Codex token IDs are address:networkId, and the holders response also returns a top10HoldersPercent field alongside items if you only need the concentration metric. There’s also a standalone top10HoldersPercent query that takes a token ID directly. Page sizes differ: Sim’s token-holders defaults to and caps at 500 per page, while Codex’s limit defaults to 50 and maxes at 200, so a naïve copy of the request will shrink your pages by up to 10× until you adjust pagination.

4. Token info and price

curl "https://api.sim.dune.com/v1/evm/token-info/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?chain_ids=1" \
  -H "X-Sim-Api-Key: $SIM_API_KEY"

query TokenInfo {
  token(input: { address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", networkId: 1 }) {
    name
    symbol
    decimals
    address
    networkId
    isScam
    info {
      circulatingSupply
      totalSupply
      imageLargeUrl
      description
    }
    socialLinks {
      twitter
      website
    }
  }
  getTokenPrices(
    inputs: [
      { address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", networkId: 1 }
    ]
  ) {
    priceUsd
    timestamp
  }
}

The two fields are returned by a single GraphQL request. Codex’s response also carries safety signals and launchpad context that Sim’s token-info doesn’t expose: isScam everywhere, plus mintable and freezable (the actual authority addresses, or null) on Solana SPL tokens.

Real-time data

Sim ships real-time updates exclusively through webhooks. Codex gives you two ways to consume the same events, and you can mix them in the same app:

WebSocket subscriptions: a persistent connection delivers updates inline. Good for dashboards, trading UIs, anything user-facing. See Subscriptions.
Webhooks: Codex calls an HTTP endpoint you own when an event fires. Good for background jobs, alerts, server-to-server fan-out. See Webhooks and the createWebhooks mutation.

Common Sim webhook patterns and their Codex equivalents:

You want to know when…	Codex subscription (WebSocket)	Codex webhook (`WebhookType`)
A wallet’s balance changes	`onBalanceUpdated`	`TOKEN_TRANSFER_EVENT` (filter by target wallet, direction `TO`/`FROM`/both)
A wallet makes a swap	`onEventsCreatedByMaker` (input field is `makerAddress`)	`TOKEN_PAIR_EVENT` (filter by `maker` for a specific wallet, or by pair)
A token’s price moves	`onPriceUpdated`	`TOKEN_PRICE_EVENT` (or `MARKET_CAP_EVENT` if you trigger on market cap thresholds)
New holders appear on a token	`onHoldersUpdated`	Subscription only (no equivalent webhook type today)

Gaps

A few things Sim does that Codex doesn’t, and what to do about them:

NFTs (ERC-721 / ERC-1155 collectibles). Codex is a fungible-token API. If NFT data is core to your product, you’ll want to combine Codex with a dedicated NFT provider (Alchemy, Reservoir, OpenSea).
Aggregated per-wallet DeFi positions. Codex exposes pair-level liquidity via liquidityMetadata and liquidityMetadataByToken, but not “this wallet holds these LP positions across these protocols.” Zerion and DeBank are the usual fill-ins here.
Raw transaction-level data and decoded contract calls. Codex returns trading events, not every transaction a wallet ever sent. If you need full tx history, pair Codex with an RPC provider or Etherscan-family API.
Dedicated stablecoin endpoint. Use filterTokens with a maintained list of stablecoin addresses.

What you pick up

Capabilities Codex offers that Sim didn’t:

One query, many shapes. GraphQL lets you combine token metadata, price, holders, and recent trades into a single request and only pull the fields you render.
Live charting data. OHLCV bars via getBars and getTokenBars, and live updates with onBarsUpdated. Sim didn’t ship a charting endpoint.
Wallet PnL and trader discovery. filterWallets, detailedWalletStats, and walletChart power discovery of profitable traders, with realized profit, swap counts, win/loss tallies, and per-network breakdowns. Available on Growth and Enterprise plans. See the Wallets recipe.
Launchpad lifecycle data. Native support for pump.fun and other launchpads, including graduation status, bonding curves, and migration events. See Launchpads.
Prediction markets. Polymarket and Kalshi data via the filterPredictionEvents family. See the Prediction Markets section.
Pair-level data. Codex has first-class concepts of trading pairs, exchanges, and liquidity locks (Sim is wallet- and token-centric only).
Built for AI agents. A docs MCP server, prebuilt Codex Skills for Claude/Cursor/Codex CLI, and pay-per-query access via MPP.

AI migration prompt

Most teams don’t migrate one file at a time. They hand the whole codebase to an IDE agent (Claude Code, Cursor, Codex CLI, or similar) and tell it to do the job. The prompt below is written for that: drop it in your agent of choice, run it from the repo root, and it will discover Sim usage, propose a plan, and execute the migration with your approval.

Pair this prompt with our Codex Skills and docs MCP server so the agent can look up Codex queries on demand instead of guessing at field names.

You are migrating this codebase from Dune's Sim API to Codex (https://docs.codex.io). Sim is sunsetting on August 1, 2026, so this migration needs to be complete and correct, not partial.

## Phase 1: Discovery (do this first, do not edit yet)

Search the codebase for every Sim integration point. At minimum, look for:

- HTTP calls to `api.sim.dune.com` (any path).
- Imports of any Sim-specific SDK or client library.
- Environment variables and config keys with names like `SIM_API_KEY`, `DUNE_SIM_*`, `SIM_*`.
- Header usage of `X-Sim-Api-Key`.
- Webhook handlers that decode Sim payloads.
- Tests, fixtures, and mocks that reference any of the above.

Produce a Migration Plan with:

1. A grouped list of every call site, organized by Sim endpoint.
2. The proposed Codex equivalent for each group (use the mapping below).
3. Any call sites you cannot map cleanly, flagged for human review.
4. The order you intend to make changes (shared client and config first, then leaf call sites, then tests).
5. New dependencies, env vars, and config you will introduce.

Stop and surface the plan before editing any source files. Wait for confirmation.

## Phase 2: Execution (after the plan is approved)

Ground rules:

1. Codex is a GraphQL API at `https://graph.codex.io/graphql`. Auth header is `Authorization: <api-key>` for long-lived keys, or `Authorization: Bearer <jwt>` for short-lived keys.
2. For TypeScript/JavaScript, prefer the official SDK (`@codex-data/sdk`) over hand-rolled HTTP. There is no SDK for other languages (including Python), so use raw GraphQL over HTTP there.
3. Network is a parameter, not part of the URL. Most queries take a scalar `networkId: Int`; `balances` takes `networks: [Int!]`. Ethereum is 1, Solana is 1399811149. For other chains, call `getNetworks` once and cache the result.
4. Token IDs in Codex are the string `"<address>:<networkId>"`. Construct them explicitly; never assume an integration relies on bare addresses.
5. Prefer combining fields into a single GraphQL query over multiple sequential calls. Sim integrations often chain two or three REST calls for one screen; collapse those. The `balances` query already returns `balanceUsd` and `tokenPriceUsd` inline — do not introduce a follow-up `getTokenPrices` call unless the integration genuinely needs historical or per-pool prices. `getTokenPrices` is capped at 25 inputs per request.
6. For real-time data, use WebSocket subscriptions when the consumer is a long-lived client (dashboards, trading UIs) and webhooks when the consumer is a server endpoint (alerts, background workers, queues). Watch out for one Codex inconsistency: the query `getTokenEventsForMaker` takes a field called `maker`, but the matching subscription `onEventsCreatedByMaker` takes `makerAddress`. Do not copy the name across.
7. Preserve existing public function signatures, return shapes, and error semantics wherever possible. Internal helpers can be refactored freely.
8. Update tests as you change code. If a test relied on a Sim response fixture, replace the fixture with a Codex equivalent rather than deleting the test.
9. When you hit a gap (NFTs/collectibles, aggregated per-wallet DeFi positions, raw transaction-level data with gas/nonce/decoded calldata, dedicated stablecoin filter), do not silently drop the feature. Leave the call site intact, add a `TODO(migration):` comment with a one-line note explaining what's missing and what provider could fill it, and list it in your final report.
10. Watch for parameter-shape differences when porting Sim's SVM endpoints: Sim uses `chains=solana,eclipse` (the string `chains`), Codex uses `networks: [1399811149]` (an array of integer IDs). Sim's EVM endpoints use `chain_ids` plural even when one value is passed.
11. Pagination defaults differ. Sim's `token-holders` defaults to and caps at 500 per page; Codex's `holders` defaults to 50 and caps at 200. Sim's `search/tokens` caps at 50; Codex's `filterTokens` caps at 200. Adjust loop counts accordingly so the migration doesn't silently shrink page sizes by 10×.
12. Some Codex features require a Growth or Enterprise plan: the `balances` and `holders` queries, `liquidityMetadata`, all WebSocket subscriptions, and the `createWebhooks` and `createApiTokens` mutations. `getTokenEventsForMaker`, `token`, `getTokenPrices`, `filterTokens`, `getNetworks`, and `top10HoldersPercent` do not. If the integration depends on a gated feature, note it in the final report so the human can confirm plan coverage before merging.

## Sim → Codex endpoint mapping

- `GET /v1/evm/balances/{address}` → `balances(input: { walletAddress, networks: [networkId] })`
- `GET /v1/evm/balances/{address}/token/{token_address}` → `balances(input: { walletAddress, networks: [networkId], tokens: ["address:networkId"] })`
- `GET /v1/evm/balances/{address}/stablecoins` → `balances` with a curated stablecoin `tokens` list
- `GET /v1/evm/activity/{address}` → `getTokenEventsForMaker(query: { maker, networkId }, limit)` (DEX swap/pool events only; field is `maker`, not `makerAddress`)
- `GET /v1/evm/transactions/{address}` → `getTokenEventsForMaker` (flag if raw txs or contract calls are required)
- `GET /v1/evm/collectibles/{address}` → not supported; flag for a dedicated NFT provider
- `GET /v1/evm/token-info/{address}?chain_ids=...` → `token(input: { address, networkId })` plus `getTokenPrices(inputs: [...])` in one query
- `GET /v1/evm/token-holders/{chain_id}/{address}` → `holders(input: { tokenId: "address:networkId" })` (default sort is balance descending; pass `sort: { attribute: BALANCE, direction: DESC }` to be explicit)
- `GET /v1/evm/search/tokens?query=...` → `filterTokens(phrase, rankings, filters)`
- `GET /v1/evm/defi/positions/{address}` → partial via `liquidityMetadata` / `liquidityMetadataByToken` (Growth/Enterprise plan); flag aggregated per-wallet positions for human review
- `GET /v1/evm/defi/supported-protocols` → no direct equivalent; if confirming DEX coverage, use `filterTokens` with `filters: { exchangeId: ... }`
- `GET /v1/evm/supported-chains` → `getNetworks` (no arguments)
- Sim Balances webhook (`type: balances`) → `onBalanceUpdated` subscription, or `createWebhooks` with `TOKEN_TRANSFER_EVENT` filtered by wallet (direction: `TO`/`FROM`/both)
- Sim Activities webhook (`type: activities`) → `onEventsCreatedByMaker` subscription (input field is `makerAddress`, not `maker`), or `TOKEN_PAIR_EVENT` webhook
- Sim Transactions webhook (`type: transactions`) → no direct equivalent; closest fallback is `TOKEN_TRANSFER_EVENT`. Flag for human review if the consumer needs raw tx fields.
- Webhook events on price/market cap → `TOKEN_PRICE_EVENT` or `MARKET_CAP_EVENT`. Use `TOKEN_PRICE_EVENT` for token price thresholds; the bare `PRICE_EVENT` enum value is legacy, so don't reach for it.

When you need details on any Codex field, fetch the reference page at `https://docs.codex.io/api-reference/queries/<name>` (or `subscriptions`, `mutations`) rather than guessing. Before migrating any real-time code, fetch `https://docs.codex.io/concepts/subscriptions` and `https://docs.codex.io/concepts/webhooks` so you pick the right delivery mechanism.

## Phase 3: Final report

When the migration is done, produce a single report with:

1. Files changed, grouped by area (client/config, call sites, tests, docs).
2. Every `TODO(migration):` you added, with file path, line, and the reason.
3. New env vars and dependencies, with the line to add to `.env.example` and the package manager command to install.
4. Sim integrations that were removed entirely, and what replaced them.
5. A short manual-verification checklist the human should run before merging (which features to click through, which endpoints to spot-check, which dashboards to load).

Run the project's linter and test suite before declaring the migration complete. If tests fail, fix the underlying integration, do not weaken the test.

Getting help

Browse the API Reference for the full schema.
Skim the Recipes for end-to-end examples that solve specific product problems.
Ask in our community if you hit a wall during migration. We’re actively supporting Sim customers through August 1.

​Mental model

​Authentication

​Endpoint mapping

​Side-by-side examples

​1. Wallet balances

​2. Wallet activity

​3. Token holders

​4. Token info and price

​Real-time data

​Gaps

​What you pick up

​AI migration prompt

​Getting help

Mental model

Authentication

Endpoint mapping

Side-by-side examples

1. Wallet balances

2. Wallet activity

3. Token holders

4. Token info and price

Real-time data

Gaps

What you pick up

AI migration prompt

Getting help