Dune Sim to Codex

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.