CoinGecko to Codex

Codex competes most directly with CoinGecko’s OnChain DEX API (the /onchain/* endpoints, powered by GeckoTerminal): pool, token, trade, and OHLCV data addressed by contract address. That’s where this guide focuses. CoinGecko’s classic market data API (coin-ID slugs like bitcoin, CEX tickers, derivatives, NFTs, treasury holdings, global aggregates) is a separate surface. Codex covers parts of it, doesn’t cover others, and we call out which is which lower down on the page.

If you only use CoinGecko for CEX tickers, derivatives, NFTs, treasury holdings, global market cap aggregates, or coin-ID lookups against non-DEX endpoints, Codex isn’t a drop-in replacement. See Gaps below for the specifics.If you use the /onchain/* endpoints (or simple/token_price and coins/{id}/contract/{address} with contract addresses), this guide is for you. Every CoinGecko field you rely on has a Codex equivalent, most Codex responses carry extra fields CoinGecko doesn’t expose (safety signals, launchpad state, multi-timeframe stats), and you pick up entire surfaces CoinGecko has no answer for: live trade streams, wallet PnL and discovery, launchpad lifecycle events, and prediction markets.

Mental model

CoinGecko’s OnChain DEX API is a REST surface where the network is a URL path segment (/onchain/networks/eth/..., /onchain/networks/solana/...) and every resource (token, pool, OHLCV, trades, holders) has its own endpoint with its own response shape. Codex is a single GraphQL Supergraph: one endpoint (https://graph.codex.io/graphql), one auth header, one query language, and the network is a numeric networkId parameter on each field. What that means in practice:

Network is a parameter, not a URL. You stop building /onchain/networks/${chain}/tokens/${address} strings. Pass { address, networkId: 1 } to a Codex field and any of 80+ networks routes through the same query.
Token and pair IDs are explicit strings. Codex addresses every token by "<address>:<networkId>" and every pair by the same shape. Once your network-slug → networkId map is in place (eth → 1, solana → 1399811149, base → 8453, …), everything composes cleanly.
You compose data in one request. GraphQL lets you fetch token metadata, current price, holders, recent trades, and OHLCV bars in a single round trip instead of three or four sequential REST calls.
Real-time is first-class. Most CoinGecko integrations poll on intervals. Codex gives you WebSocket subscriptions and webhooks for live prices, trades, holders, and balances.

If you also touch the coin-ID-based market data endpoints (/simple/price?ids=..., /coins/{id}), there’s a one-time slug-to-address translation step covered in Coin IDs vs contract addresses below. If you’ve never used GraphQL, Learn GraphQL is a 10-minute primer that’s enough to follow the rest of this guide.

Authentication

CoinGecko uses one of two API key headers depending on plan: x-cg-demo-api-key for the free demo tier or x-cg-pro-api-key for paid plans (which also flips the base URL to pro-api.coingecko.com). Codex uses a single Authorization header with a key from the dashboard.

CoinGecko

curl "https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" \
  -H "x-cg-pro-api-key: $COINGECKO_API_KEY"

Codex

curl https://graph.codex.io/graphql \
  -H "Authorization: $CODEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ getTokenPrices(inputs: [{ address: \"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", networkId: 1 }]) { address priceUsd timestamp } }"}'

For browser-facing apps, generate a short-lived JWT with createApiTokens and pass it as Bearer <token>. See Authentication for the full pattern.

Endpoint mapping

OnChain DEX API: tokens

The most-used CoinGecko OnChain endpoints. Codex addresses tokens by address:networkId where CoinGecko addresses them by {network}/{address}, but the data behind each endpoint is the same shape.

CoinGecko OnChain	Codex equivalent	Notes
`GET /onchain/networks/{network}/tokens/{address}`	`token`	Richer metadata including safety signals, launchpad context, social links.
`GET /onchain/networks/{network}/tokens/multi/{addresses}`	`tokens`	Batch token metadata.
`GET /onchain/networks/{network}/tokens/{address}/info`	`token`
`GET /onchain/simple/networks/{network}/token_price/{addresses}`	`getTokenPrices`	For the `include_*` flags (`include_market_cap`, `include_24hr_vol`, `include_24hr_price_change`, `include_total_reserve_in_usd`), use `filterTokens`, whose results expose `marketCap`/`circulatingMarketCap`, `volume24`, `change24`, and `liquidity` directly. (`getDetailedTokenStats` covers bucketed volume and OHLC, but does not expose market cap.)
`GET /onchain/networks/{network}/tokens/{address}/ohlcv/{timeframe}`	`getTokenBars`
`GET /onchain/networks/{network}/tokens/{address}/trades`	`getTokenEvents`	CoinGecko’s token-level trades endpoint is Analyst+ and capped at the last 300 trades over 24 hours (across all of the token’s pools); Codex retains the full event history on every plan. Note: `getTokenEvents` is pair-scoped (a token address resolves to its top pair), so to cover every pool either iterate the token’s pairs or stream token-wide via `onTokenEventsCreated`.
`GET /onchain/networks/{network}/tokens/{address}/top_holders`	`holders` (+ `top10HoldersPercent` for the aggregate)
`GET /onchain/networks/{network}/tokens/{address}/top_traders`	`tokenTopTraders`	Supports time-range filters and PnL data.
`GET /onchain/networks/{network}/tokens/{address}/holders_chart`	Partial via `onHoldersUpdated`	Live count; historical chart is not a first-class endpoint.
`GET /onchain/tokens/info_recently_updated`	`filterTokens` ranked by recent activity	Cross-network on CoinGecko; filter by `network` in Codex if you need to scope it.

OnChain DEX API: pools and pairs

CoinGecko OnChain	Codex equivalent	Notes
`GET /onchain/networks/{network}/pools/{pool}`	`getDetailedPairStats`
`GET /onchain/networks/{network}/pools/multi/{addresses}`	`getDetailedPairsStats`
`GET /onchain/networks/{network}/tokens/{address}/pools`	`listPairsForToken`
`GET /onchain/networks/{network}/pools/{pool}/info`	`pairMetadata`
`GET /onchain/networks/{network}/pools/{pool}/trades`	`getTokenEvents` with a pair filter	Last 300 trades over 24 hours vs. Codex’s full event history.
`GET /onchain/networks/{network}/pools/{pool}/ohlcv/{timeframe}`	`getBars`	Both APIs cover sub-minute candles; Codex extends one step further with `7D` (weekly) bars.
`GET /onchain/networks/{network}/pools`	`filterPairs` with `filters: { network: [<id>] }`	Top pools on a single network.
`GET /onchain/networks/{network}/new_pools`, `/onchain/networks/new_pools`	`filterPairs` ranked by `createdAt`	Or subscribe to `onTokenLifecycleEventsCreated`.
`GET /onchain/networks/trending_pools`, `/onchain/networks/{network}/trending_pools`	`filterPairs` ranked by `trendingScore24`
`GET /onchain/pools/trending_search`	`filterPairs(phrase: ..., rankings: { attribute: trendingScore24 })`	Trending matches for a search phrase.
`GET /onchain/networks/{network}/dexes/{dex}/pools`	`filterPairs` filtered by exchange
`GET /onchain/pools/megafilter`	`filterPairs`	Rich filter clauses across all networks.

OnChain DEX API: networks, dexes, search

CoinGecko OnChain	Codex equivalent	Notes
`GET /onchain/networks`	`getNetworks`
`GET /onchain/networks/{network}/dexes`	`filterExchanges`
`GET /onchain/search/pools`	`filterPairs(phrase: ...)`
`GET /onchain/categories`, `GET /onchain/categories/{id}/pools`	Not supported	See Gaps — Codex doesn’t curate DEX pool categories.

CoinGecko market data (coin-ID based)

These endpoints sit on the CoinGecko market data side rather than the OnChain DEX side. Most DEX-focused integrations don’t hit them, but if yours does, here’s the mapping.

CoinGecko	Codex equivalent	Notes
`GET /simple/price?ids=bitcoin,ethereum`	`getTokenPrices` (+ `filterTokens`)	Resolve coin IDs to contract addresses first; see Coin IDs vs contract addresses below. If you use `include_24hr_change`, `include_24hr_vol`, or `include_market_cap`, pull `change24`, `volume24`, and `marketCap`/`circulatingMarketCap` from `filterTokens` (market cap is not on `getDetailedTokenStats`).
`GET /simple/token_price/{platform}?contract_addresses=...`	`getTokenPrices`	Direct mapping; `{platform}` becomes `networkId`. Same caveat as above for `include_*` flags.
`GET /coins/{id}`	`token` + `getDetailedTokenStats` (+ `filterTokens` for market cap)	Resolve ID first. `token` returns metadata, safety, launchpad; `getDetailedTokenStats` adds volume/OHLC stats. For `market_cap`, read `marketCap`/`circulatingMarketCap` from `filterTokens` (neither `token` nor `getDetailedTokenStats` exposes it).
`GET /coins/{id}/market_chart`, `/market_chart/range`	`getTokenBars`	OHLCV from 1-second up to weekly (`7D`).
`GET /coins/{id}/ohlc`, `/ohlc/range`	`getTokenBars`
`GET /coins/{id}/contract/{address}/market_chart`, `/market_chart/range`	`getTokenBars`	Already contract-addressed; no slug resolution.
`GET /coins/{id}/history?date=...`	`getBars` with a single bar covering the date
`GET /coins/markets`	`filterTokens` with ranking	Filter by network, liquidity, market cap; rank by volume, trending, etc.
`GET /coins/list`, `/token_lists/{asset_platform_id}/all.json`	`filterTokens` (optionally `filters: { network: [<id>] }`)	Filter at the point of use instead of maintaining a full list.
`GET /coins/list/new`	`filterTokens` ranked by `createdAt`, or `onTokenLifecycleEventsCreated`
`GET /coins/top_gainers_losers`	`filterTokens` ranked by `change24`	`change24` is the 24h price-change ranking attribute on tokens (the pair-side analogue is `priceChange24`).
`GET /coins/{id}/tickers`	`listPairsForToken` + `listPairsWithMetadataForToken`	DEX pairs only; CEX tickers are out of scope.
`GET /coins/{id}/contract/{contract_address}`	`token`	The contract-address form is already the Codex native shape.
`GET /coins/{id}/circulating_supply_chart`, `/total_supply_chart` (+ `/range`)	Not supported	See Gaps — no historical supply timeseries. Current supply is on `token.info`.
`GET /search?query=...`	`filterTokens(phrase: "$SYMBOL", ...)`	Use `$SYMBOL` prefix for exact symbol matches.
`GET /search/trending`	`filterTokens(rankings: { attribute: trendingScore24, direction: DESC })`	Tokens only; trending NFTs and categories are out of scope. See the Discover Tokens recipe.
`GET /coins/categories`, `/coins/categories/list`	Not supported	See Gaps.
`GET /simple/supported_vs_currencies`, `/exchange_rates`	Not supported	Codex returns USD only. Pair with an FX provider.

Utilities

CoinGecko	Codex equivalent	Notes
`GET /asset_platforms`	`getNetworks`	Returns `networkId`s you’ll use everywhere else.
`GET /ping`	Not needed	Codex doesn’t require health-checking.
`GET /key`	Codex usage in the dashboard	CoinGecko’s `/key` returns your plan’s usage, rate limits, and remaining credits; Codex surfaces the same in the dashboard.

Coin IDs vs contract addresses

This only matters if your integration touches CoinGecko’s coin-ID-based endpoints (/simple/price?ids=..., /coins/{id}, /coins/{id}/market_chart). CoinGecko addresses tokens by slug (bitcoin, ethereum, pepe); Codex takes a contract address plus a networkId. The OnChain DEX endpoints already use contract addresses, so they translate cleanly. The cleanest path is to keep a small static mapping for the head tokens you reference by ID (BTC, ETH, USDC, USDT, SOL, etc.), and use filterTokens(phrase: ...) at runtime for the long tail. If you currently call GET /coins/list to maintain a coin-ID map, replace it with that filter at the point of use.

Side-by-side examples

1. Token price by contract address

curl "https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599,0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" \
  -H "x-cg-pro-api-key: $COINGECKO_API_KEY"

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

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

const { getTokenPrices } = await sdk.queries.getTokenPrices({
  inputs: [
    { address: "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", networkId: 1 }, // WBTC
    { address: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", networkId: 1 }, // WETH
  ],
})

getTokenPrices.forEach((p) => console.log(p.address, p.priceUsd))

query MultiPrice {
  getTokenPrices(
    inputs: [
      { address: "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", networkId: 1 }
      { address: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", networkId: 1 }
    ]
  ) {
    address
    networkId
    priceUsd
    timestamp
  }
}

For a live price feed instead of polling, subscribe to onPricesUpdated. If you’re calling /simple/price?ids=... instead, see Coin IDs vs contract addresses for the slug-to-address translation step.

2. Pool detail

CoinGecko’s /onchain/networks/{network}/pools/{pool} returns a pool snapshot. Codex returns the same shape plus stats over multiple timeframes in a single query.

curl "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640?include=base_token,quote_token,dex" \
  -H "x-cg-pro-api-key: $COINGECKO_API_KEY"

query PairOverview {
  getDetailedPairStats(
    pairAddress: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
    networkId: 1
    durations: [hour1, day1]
  ) {
    pairAddress
    networkId
    stats_day1 {
      statsUsd {
        volume { currentValue change }
        buyVolume { currentValue }
        sellVolume { currentValue }
      }
      statsNonCurrency {
        transactions { currentValue change }
        buyers { currentValue }
        sellers { currentValue }
      }
    }
    stats_hour1 {
      statsUsd {
        volume { currentValue change }
      }
      statsNonCurrency {
        transactions { currentValue }
      }
    }
  }
  pairMetadata(pairId: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:1") {
    liquidity
    fee
    exchangeId
    price
    priceChange24
    volume24
    token0 { name symbol address }
    token1 { name symbol address }
  }
}

3. OHLCV chart

curl "https://pro-api.coingecko.com/api/v3/onchain/networks/eth/pools/0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640/ohlcv/hour?aggregate=1&limit=100" \
  -H "x-cg-pro-api-key: $COINGECKO_API_KEY"

query PairChart {
  getBars(
    symbol: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:1"
    from: 1716595200
    to: 1717200000
    resolution: "60"
  ) {
    t
    o
    h
    l
    c
    volume
  }
}

Codex’s resolution set is 1S, 5S, 15S, 30S, 1, 5, 15, 30, 60, 240, 720, 1D, 7D (1-second up to weekly), one step longer than CoinGecko’s longest bar (day). Sub-minute bars are only retained for the last 24 hours. Layer in onBarsUpdated for live chart updates, and see the Charts recipe for a full Lightweight Charts integration.

curl "https://pro-api.coingecko.com/api/v3/onchain/networks/trending_pools?include=base_token,quote_token,dex" \
  -H "x-cg-pro-api-key: $COINGECKO_API_KEY"

query TrendingPairs {
  filterPairs(
    filters: { liquidity: { gt: 100000 } }
    rankings: { attribute: trendingScore24, direction: DESC }
    limit: 25
  ) {
    results {
      pair {
        address
        token0
        token1
        exchangeHash
      }
      liquidity
      volumeUSD24
      priceChange24
      marketCap
    }
  }
}

For trending tokens (rather than pools), use filterTokens with the same ranking attribute. See Discover Tokens.

Real-time data

CoinGecko offers WebSocket streams on higher tiers, but most CoinGecko integrations are built on polling. Moving to Codex usually means replacing polling loops with WebSocket subscriptions (for user-facing dashboards and trading UIs) or webhooks (for server-side alerts and queues).

You want updates for…	Codex subscription	Codex webhook
Token prices	`onPriceUpdated`, `onPricesUpdated`	`TOKEN_PRICE_EVENT`
OHLCV bars	`onBarsUpdated`, `onTokenBarsUpdated`
Token-level stats	`onDetailedTokenStatsUpdated`
Pair-level stats	`onDetailedStatsUpdated`
Market cap thresholds	`onPricesUpdated` (derive: price × circulating supply)	`MARKET_CAP_EVENT` (thresholds on `fdvMarketCapUsd` / `circulatingMarketCapUsd`)
Token trade events	`onTokenEventsCreated`, `onEventsCreated`	`TOKEN_PAIR_EVENT` (swaps, mints, burns)
Token transfers	—	`TOKEN_TRANSFER_EVENT`
Holder count changes	`onHoldersUpdated`	Approximate via `TOKEN_TRANSFER_EVENT`
New pools/listings	`onTokenLifecycleEventsCreated`, `onLaunchpadTokenEvent`

Gaps

Things CoinGecko covers that Codex doesn’t, and what to do about them:

CEX tickers, exchange metadata, and order-book data (/coins/{id}/tickers for centralized exchanges, /exchanges, /exchanges/list, /exchanges/{id}, /exchanges/{id}/tickers, /exchanges/{id}/volume_chart, /exchanges/{id}/volume_chart/range). Codex is onchain-only. Keep CoinGecko for CEX coverage or pair with an exchange-data provider.
Derivatives and futures (/derivatives, /derivatives/exchanges, /derivatives/exchanges/{id}, /derivatives/exchanges/list). Codex doesn’t cover perps or futures venues.
NFTs (/nfts/*, NFT floor prices, collection data, trending NFTs from /search/trending). Codex is a fungible-token API. Pair with a dedicated NFT provider (Reservoir, OpenSea, Alchemy NFT).
Treasury holdings and entity data (the current entity-based surface: /entities/list, /{entity}/public_treasury/{coin_id}, /public_treasury/{entity_id}, /public_treasury/{entity_id}/{coin_id}/holding_chart, /public_treasury/{entity_id}/transaction_history, plus the legacy /companies/public_treasury/{coin_id} shape). No equivalent.
Global market data aggregates (/global, /global/decentralized_finance_defi, /global/market_cap_chart). Codex doesn’t produce “total crypto market cap” rollups.
Historical supply timeseries (/coins/{id}/circulating_supply_chart, /total_supply_chart, and their /range variants). Codex exposes current supply on token.info, not historical curves.
Crypto news (/news). Out of scope.
Fiat exchange rates beyond USD (/exchange_rates, /simple/supported_vs_currencies). Codex returns USD pricing only; pair with an FX provider for other quote currencies.
Hand-curated categories (/coins/categories, /coins/categories/list, /onchain/categories, /onchain/categories/{id}/pools, trending categories from /search/trending). Codex doesn’t classify tokens or pools into curated categories.

What you pick up

Things Codex offers that CoinGecko doesn’t:

Full trade history with real-time streaming. Per-trade fields are roughly comparable between the two APIs (maker address, token-in/token-out amounts, USD price at execution, transaction hash). The differentiator is depth and delivery: Codex retains every swap per token and per pair and pushes new ones live via onTokenEventsCreated or onEventsCreated, where CoinGecko’s onchain trade endpoints cap at the last 300 trades over 24 hours with no streaming surface.
Wallet analytics. balances, detailedWalletStats, walletChart, and filterWallets let you build portfolio screens, PnL summaries, and “smart money” discovery flows. None of this is in CoinGecko.
Launchpad lifecycle data. First-class support for pump.fun, LetsBonk, Believe, and other launchpads, including bonding-curve state, graduation, and migration events. See Launchpads.
Prediction markets. Polymarket and Kalshi event, market, trade, and trader data via the filterPredictionEvents family (Growth or Enterprise plan). See Prediction Markets.
Liquidity locks. liquidityLocks surfaces locked-LP context that CoinGecko doesn’t track.
Webhooks. Push real-time data to your servers without holding open a WebSocket. Configure via createWebhooks.
One query, many shapes. GraphQL lets you combine token metadata, price, holders, recent trades, pair stats, and chart data into a single request. Three-or-four-call sequences collapse to one.
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 CoinGecko integrations spread across many call sites: a price service, a chart loader, a token search, a trending feed, polling loops, maybe a few /onchain calls for pool data. Hand the prompt below to an IDE agent (Claude Code, Cursor, Codex CLI, or similar), run it from the repo root, and it will discover every CoinGecko touchpoint, 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 the CoinGecko API to Codex (https://docs.codex.io). CoinGecko has two distinct API surfaces: a coin-ID-based market data API and a contract-address-based OnChain DEX API. Most of the OnChain DEX API maps cleanly to Codex; some of the market data API does not.

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

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

- HTTP calls to `api.coingecko.com`, `pro-api.coingecko.com`, or `api.geckoterminal.com` (any path).
- Imports of any CoinGecko SDK (`coingecko-api-v3`, `@coingecko/coingecko-typescript`, `pycoingecko`, etc.) or GeckoTerminal client.
- Environment variables and config keys named `COINGECKO_*`, `CG_*`, `GECKOTERMINAL_*`.
- Header usage of `x-cg-pro-api-key` or `x-cg-demo-api-key`.
- Hardcoded coin-ID slugs (`"bitcoin"`, `"ethereum"`, `"solana"`, `"pepe"`, etc.) used to address CoinGecko endpoints.
- Network-slug mappings (`eth`, `polygon_pos`, `bsc`, `solana`) used in `/onchain` paths.
- 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 CoinGecko 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/config first, then leaf call sites, then tests).
5. New dependencies, env vars, and config you will introduce.
6. A list of every coin-ID slug used in the codebase that needs a contract-address mapping.

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. Prefer the official TypeScript SDK (`@codex-data/sdk`) for TS/JS projects. There is no official SDK for Python or other languages: for those, call raw GraphQL against `https://graph.codex.io/graphql`.
3. Network is a numeric parameter (`networkId`), not a URL path segment. Convert CoinGecko network slugs to Codex network IDs: `eth` → 1, `solana` → 1399811149, `base` → 8453, `bsc` → 56, `polygon_pos` → 137, `arbitrum` → 42161, `optimism` → 10, `avax` → 43114, `sui-network` → 101. For others, call `getNetworks` once and build a lookup.
4. Token IDs in Codex are the string `"<address>:<networkId>"`. Pair IDs use the same shape. Construct them explicitly.
5. Resolve coin-ID slugs to contract addresses once at startup (or call `filterTokens(phrase: ...)` at the call site). Store the resulting address+networkId in your config rather than carrying the slug through the codebase.
6. Where a CoinGecko integration hits two or three endpoints to fill one screen (for example `/coins/{id}` + `/coins/{id}/market_chart` + `/coins/{id}/tickers`), collapse them into a single GraphQL query.
7. For real-time data, replace polling loops with 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).
8. Preserve existing public function signatures, return shapes, and error semantics wherever possible. Internal helpers can be refactored freely.
9. Update tests as you change code. If a test relied on a CoinGecko response fixture, replace the fixture with a Codex equivalent rather than deleting the test.
10. When you hit a gap (CEX tickers, derivatives, NFTs, treasury holdings, global market cap aggregates, news, non-USD fiat conversions, hand-curated categories), 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.

## CoinGecko → Codex endpoint mapping

OnChain DEX tokens (the most commonly migrated surface):
- `GET /onchain/networks/{network}/tokens/{address}` → `token`
- `GET /onchain/networks/{network}/tokens/multi/{addresses}` → `tokens`
- `GET /onchain/networks/{network}/tokens/{address}/info` → `token`
- `GET /onchain/simple/networks/{network}/token_price/{addresses}` → `getTokenPrices`
- `GET /onchain/networks/{network}/tokens/{address}/ohlcv/{timeframe}` → `getTokenBars`
- `GET /onchain/networks/{network}/tokens/{address}/trades` → `getTokenEvents` (pair-scoped: a token address resolves to its top pair; iterate the token's pairs or use `onTokenEventsCreated` for token-wide coverage across all pools)
- `GET /onchain/networks/{network}/tokens/{address}/top_holders` → `holders(input: { tokenId: "<address>:<networkId>" })` (default sort is holdings DESC)
- `GET /onchain/networks/{network}/tokens/{address}/top_traders` → `tokenTopTraders`
- `GET /onchain/networks/{network}/tokens/{address}/holders_chart` → partial via `onHoldersUpdated` (live only; flag if historical timeseries is required)
- `GET /onchain/tokens/info_recently_updated` → `filterTokens` ranked by recent activity (CoinGecko's path is cross-network, with no `networks/{network}` segment)

OnChain DEX (pools and pairs):
- `GET /onchain/networks/{network}/pools/{pool}` → `getDetailedPairStats(pairAddress: "0x...", networkId: <id>, durations: [...])` (top-level args, not `input: { pairId }`)
- `GET /onchain/networks/{network}/pools/multi/{addresses}` → `getDetailedPairsStats`
- `GET /onchain/networks/{network}/tokens/{address}/pools` → `listPairsForToken`
- `GET /onchain/networks/{network}/pools/{pool}/info` → `pairMetadata` (selects `exchangeId`, not `exchangeHash`)
- `GET /onchain/networks/{network}/pools/{pool}/trades` → `getTokenEvents` with pair filter
- `GET /onchain/networks/{network}/pools/{pool}/ohlcv/{timeframe}` → `getBars` (use `volume` field, not deprecated `v`)
- `GET /onchain/networks/{network}/pools` → `filterPairs(filters: { network: [<id>] })`
- `GET /onchain/networks/{network}/new_pools`, `/onchain/networks/new_pools` → `filterPairs` ranked by `createdAt` or subscribe to `onTokenLifecycleEventsCreated`
- `GET /onchain/networks/trending_pools`, `/onchain/networks/{network}/trending_pools` → `filterPairs(rankings: { attribute: trendingScore24, direction: DESC })`. `trendingScore24` is a ranking attribute, not a queryable result field.
- `GET /onchain/pools/trending_search` → `filterPairs(phrase: ..., rankings: { attribute: trendingScore24 })`
- `GET /onchain/networks/{network}/dexes/{dex}/pools` → `filterPairs` filtered by exchange
- `GET /onchain/pools/megafilter` → `filterPairs`

OnChain DEX (networks, dexes, search):
- `GET /onchain/networks` → `getNetworks`
- `GET /onchain/networks/{network}/dexes` → `filterExchanges`
- `GET /onchain/search/pools` → `filterPairs(phrase: ...)`
- `GET /onchain/categories`, `GET /onchain/categories/{id}/pools` → not supported (no curated DEX categories)

CoinGecko market data, coin-ID based (only relevant if the codebase hits these endpoints):
- `GET /simple/price?ids=...` → resolve IDs to addresses, then `getTokenPrices(inputs: [...])`. If the call uses `include_24hr_change`, `include_24hr_vol`, or `include_market_cap`, also call `filterTokens` and read `change24`, `volume24`, and `marketCap`/`circulatingMarketCap` from its results. `getDetailedTokenStats` provides bucketed volume/OHLC but does not expose market cap.
- `GET /simple/token_price/{platform}?contract_addresses=...` → `getTokenPrices(inputs: [...])` (no slug resolution needed). Same caveat for `include_*` flags.
- `GET /coins/{id}` → resolve ID first, then `token` + `getDetailedTokenStats` (+ `filterTokens` for `marketCap`/`circulatingMarketCap`, which neither of the first two exposes)
- `GET /coins/{id}/market_chart`, `/market_chart/range`, `/ohlc`, `/ohlc/range` → `getTokenBars`
- `GET /coins/{id}/contract/{address}/market_chart`, `/market_chart/range` → `getTokenBars` (already contract-addressed)
- `GET /coins/{id}/history` → `getBars` with a single bar covering the date
- `GET /coins/markets` → `filterTokens(rankings: ..., filters: ...)`
- `GET /coins/list`, `GET /token_lists/{asset_platform_id}/all.json` → `filterTokens` at point of use; drop the local coin list
- `GET /coins/list/new` → `filterTokens(rankings: { attribute: createdAt, direction: DESC })` or `onTokenLifecycleEventsCreated`
- `GET /coins/top_gainers_losers` → `filterTokens(rankings: { attribute: change24, direction: DESC })` (use `change24`; `priceChange24` is the pair-side analogue and is not valid on `TokenRankingAttribute`)
- `GET /coins/{id}/tickers` → `listPairsForToken` / `listPairsWithMetadataForToken` (DEX only; flag CEX)
- `GET /coins/{id}/contract/{address}` → `token`
- `GET /coins/{id}/circulating_supply_chart`, `/total_supply_chart` (+ `/range`) → not supported (no historical supply timeseries; current supply on `token.info`)
- `GET /search?query=...` → `filterTokens(phrase: "$SYMBOL", ...)`
- `GET /search/trending` → `filterTokens(rankings: { attribute: trendingScore24, direction: DESC })`. Tokens only — flag NFT and category results as gaps.
- `GET /exchange_rates`, `/simple/supported_vs_currencies` → not supported (USD only)
- `GET /coins/categories`, `/coins/categories/list` → not supported (no curated categories)

Real-time (polling → Codex subscription):
- Polled `/simple/price`, `/simple/token_price` → `onPriceUpdated` / `onPricesUpdated`
- Polled `/onchain/.../ohlcv` → `onBarsUpdated` / `onTokenBarsUpdated`
- Polled token-stats endpoints → `onDetailedTokenStatsUpdated`
- Polled pair-stats endpoints → `onDetailedStatsUpdated`
- Polled trades → `onTokenEventsCreated` / `onEventsCreated`
- Polled holders → `onHoldersUpdated`
- Polled `new_pools` → `onTokenLifecycleEventsCreated` / `onLaunchpadTokenEvent`

Gaps (flag, do not drop):
- `/coins/{id}/tickers` for CEX exchanges: Codex is onchain-only
- `/exchanges`, `/exchanges/list`, `/exchanges/{id}`, `/exchanges/{id}/tickers`, `/exchanges/{id}/volume_chart`, `/derivatives*`: not supported
- `/nfts/*` and NFT/category buckets in `/search/trending`: Codex is a fungible-token API
- `/entities/list`, `/public_treasury/*`, legacy `/companies/public_treasury/*`: not supported
- `/global`, `/global/decentralized_finance_defi`, `/global/market_cap_chart`: Codex does not aggregate global market totals
- `/coins/{id}/circulating_supply_chart`, `/total_supply_chart` (and `/range` variants): no historical supply timeseries (current supply available on `token.info`)
- `/news`: not supported
- `/exchange_rates`, non-USD `vs_currencies`: Codex returns USD only
- `/coins/categories`, `/coins/categories/list`, `/onchain/categories`, `/onchain/categories/{id}/pools`: Codex does not curate token or pool categories

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. The coin-ID → contract-address mapping you ended up with, so the human can audit it.
4. New env vars and dependencies, with the line to add to `.env.example` and the package manager command to install.
5. CoinGecko integrations that were removed entirely, and what replaced them.
6. 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.

First steps

Codex for Agents

Concepts

Recipes

Migration Guides

Resources

CoinGecko to Codex

Mental model

Authentication

Endpoint mapping

OnChain DEX API: tokens

OnChain DEX API: pools and pairs

OnChain DEX API: networks, dexes, search

CoinGecko market data (coin-ID based)

Utilities

Coin IDs vs contract addresses

Side-by-side examples

1. Token price by contract address

2. Pool detail

3. OHLCV chart

Real-time data

Gaps

What you pick up

AI migration prompt

Getting help

​Mental model

​Authentication

​Endpoint mapping

​OnChain DEX API: tokens

​OnChain DEX API: pools and pairs

​OnChain DEX API: networks, dexes, search

​CoinGecko market data (coin-ID based)

​Utilities

​Coin IDs vs contract addresses

​Side-by-side examples

​1. Token price by contract address

​2. Pool detail

​3. OHLCV chart

​4. Trending pools

​Real-time data

​Gaps

​What you pick up

​AI migration prompt

​Getting help

Mental model

Authentication

Endpoint mapping

OnChain DEX API: tokens

OnChain DEX API: pools and pairs

OnChain DEX API: networks, dexes, search

CoinGecko market data (coin-ID based)

Utilities

Coin IDs vs contract addresses

Side-by-side examples

1. Token price by contract address

2. Pool detail

3. OHLCV chart

4. Trending pools

Real-time data

Gaps

What you pick up

AI migration prompt

Getting help