> ## Documentation Index > Fetch the complete documentation index at: https://docs.codex.io/llms.txt > Use this file to discover all available pages before exploring further. # CoinGecko to Codex > Move your CoinGecko integration to Codex for deeper onchain data, real-time events, and wallet analytics 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](#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](/networks) routes through the same query. * **Token and pair IDs are explicit strings.** Codex addresses every token by `"
:"` 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](/concepts/subscriptions) and [webhooks](/concepts/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](#coin-ids-vs-contract-addresses) below. If you've never used GraphQL, [Learn 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](https://dashboard.codex.io?utm_source=codex\&utm_medium=docs\&utm_campaign=migrations-coingecko). ```bash CoinGecko theme={null} curl "https://pro-api.coingecko.com/api/v3/onchain/simple/networks/eth/token_price/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" \ -H "x-cg-pro-api-key: $COINGECKO_API_KEY" ``` ```bash Codex theme={null} 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`](/api-reference/mutations/createapitokens) and pass it as `Bearer `. See [Authentication](/concepts/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`](/api-reference/queries/token) | Richer metadata including safety signals, launchpad context, social links. | | `GET /onchain/networks/{network}/tokens/multi/{addresses}` | [`tokens`](/api-reference/queries/tokens) | Batch token metadata. | | `GET /onchain/networks/{network}/tokens/{address}/info` | [`token`](/api-reference/queries/token) | | | `GET /onchain/simple/networks/{network}/token_price/{addresses}` | [`getTokenPrices`](/api-reference/queries/gettokenprices) | For the `include_*` flags (`include_market_cap`, `include_24hr_vol`, `include_24hr_price_change`, `include_total_reserve_in_usd`), use [`filterTokens`](/api-reference/queries/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`](/api-reference/queries/gettokenbars) | | | `GET /onchain/networks/{network}/tokens/{address}/trades` | [`getTokenEvents`](/api-reference/queries/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`](/api-reference/subscriptions/ontokeneventscreated). | | `GET /onchain/networks/{network}/tokens/{address}/top_holders` | [`holders`](/api-reference/queries/holders) (+ [`top10HoldersPercent`](/api-reference/queries/top10holderspercent) for the aggregate) | | | `GET /onchain/networks/{network}/tokens/{address}/top_traders` | [`tokenTopTraders`](/api-reference/queries/tokentoptraders) | Supports time-range filters and PnL data. | | `GET /onchain/networks/{network}/tokens/{address}/holders_chart` | Partial via [`onHoldersUpdated`](/api-reference/subscriptions/onholdersupdated) | Live count; historical chart is not a first-class endpoint. | | `GET /onchain/tokens/info_recently_updated` | [`filterTokens`](/api-reference/queries/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`](/api-reference/queries/getdetailedpairstats) | | | `GET /onchain/networks/{network}/pools/multi/{addresses}` | [`getDetailedPairsStats`](/api-reference/queries/getdetailedpairsstats) | | | `GET /onchain/networks/{network}/tokens/{address}/pools` | [`listPairsForToken`](/api-reference/queries/listpairsfortoken) | | | `GET /onchain/networks/{network}/pools/{pool}/info` | [`pairMetadata`](/api-reference/queries/pairmetadata) | | | `GET /onchain/networks/{network}/pools/{pool}/trades` | [`getTokenEvents`](/api-reference/queries/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`](/api-reference/queries/getbars) | Both APIs cover sub-minute candles; Codex extends one step further with `7D` (weekly) bars. | | `GET /onchain/networks/{network}/pools` | [`filterPairs`](/api-reference/queries/filterpairs) with `filters: { network: [] }` | Top pools on a single network. | | `GET /onchain/networks/{network}/new_pools`, `/onchain/networks/new_pools` | [`filterPairs`](/api-reference/queries/filterpairs) ranked by `createdAt` | Or subscribe to [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated). | | `GET /onchain/networks/trending_pools`, `/onchain/networks/{network}/trending_pools` | [`filterPairs`](/api-reference/queries/filterpairs) ranked by `trendingScore24` | | | `GET /onchain/pools/trending_search` | [`filterPairs(phrase: ..., rankings: { attribute: trendingScore24 })`](/api-reference/queries/filterpairs) | Trending matches for a search phrase. | | `GET /onchain/networks/{network}/dexes/{dex}/pools` | [`filterPairs`](/api-reference/queries/filterpairs) filtered by exchange | | | `GET /onchain/pools/megafilter` | [`filterPairs`](/api-reference/queries/filterpairs) | Rich filter clauses across all networks. | ### OnChain DEX API: networks, dexes, search | CoinGecko OnChain | Codex equivalent | Notes | | :-------------------------------------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------ | | `GET /onchain/networks` | [`getNetworks`](/api-reference/queries/getnetworks) | | | `GET /onchain/networks/{network}/dexes` | [`filterExchanges`](/api-reference/queries/filterexchanges) | | | `GET /onchain/search/pools` | [`filterPairs(phrase: ...)`](/api-reference/queries/filterpairs) | | | `GET /onchain/categories`, `GET /onchain/categories/{id}/pools` | Not supported | See [Gaps](#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`](/api-reference/queries/gettokenprices) (+ [`filterTokens`](/api-reference/queries/filtertokens)) | Resolve coin IDs to contract addresses first; see [Coin IDs vs contract addresses](#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`](/api-reference/queries/gettokenprices) | Direct mapping; `{platform}` becomes `networkId`. Same caveat as above for `include_*` flags. | | `GET /coins/{id}` | [`token`](/api-reference/queries/token) + [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats) (+ [`filterTokens`](/api-reference/queries/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`](/api-reference/queries/gettokenbars) | OHLCV from 1-second up to weekly (`7D`). | | `GET /coins/{id}/ohlc`, `/ohlc/range` | [`getTokenBars`](/api-reference/queries/gettokenbars) | | | `GET /coins/{id}/contract/{address}/market_chart`, `/market_chart/range` | [`getTokenBars`](/api-reference/queries/gettokenbars) | Already contract-addressed; no slug resolution. | | `GET /coins/{id}/history?date=...` | [`getBars`](/api-reference/queries/getbars) with a single bar covering the date | | | `GET /coins/markets` | [`filterTokens`](/api-reference/queries/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`](/api-reference/queries/filtertokens) (optionally `filters: { network: [] }`) | Filter at the point of use instead of maintaining a full list. | | `GET /coins/list/new` | [`filterTokens`](/api-reference/queries/filtertokens) ranked by `createdAt`, or [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated) | | | `GET /coins/top_gainers_losers` | [`filterTokens`](/api-reference/queries/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`](/api-reference/queries/listpairsfortoken) + [`listPairsWithMetadataForToken`](/api-reference/queries/listpairswithmetadatafortoken) | DEX pairs only; CEX tickers are out of scope. | | `GET /coins/{id}/contract/{contract_address}` | [`token`](/api-reference/queries/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](#gaps) — no historical supply timeseries. Current supply is on `token.info`. | | `GET /search?query=...` | [`filterTokens(phrase: "$SYMBOL", ...)`](/api-reference/queries/filtertokens) | Use `$SYMBOL` prefix for exact symbol matches. | | `GET /search/trending` | [`filterTokens(rankings: { attribute: trendingScore24, direction: DESC })`](/api-reference/queries/filtertokens) | Tokens only; trending NFTs and categories are out of scope. See the [Discover Tokens recipe](/recipes/discover-tokens). | | `GET /coins/categories`, `/coins/categories/list` | Not supported | See [Gaps](#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`](/api-reference/queries/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](https://dashboard.codex.io) | 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: ...)`](/api-reference/queries/filtertokens) 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 ```bash CoinGecko theme={null} 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" ``` ```typescript Codex SDK theme={null} 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)) ``` ```graphql Codex GraphQL theme={null} 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`](/api-reference/subscriptions/onpricesupdated). If you're calling `/simple/price?ids=...` instead, see [Coin IDs vs contract addresses](#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. ```bash CoinGecko theme={null} 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" ``` ```graphql Codex GraphQL theme={null} 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 ```bash CoinGecko theme={null} 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" ``` ```graphql Codex GraphQL theme={null} 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`](/api-reference/subscriptions/onbarsupdated) for live chart updates, and see the [Charts recipe](/recipes/charts) for a full Lightweight Charts integration. ### 4. Trending pools ```bash CoinGecko theme={null} 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" ``` ```graphql Codex GraphQL theme={null} 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`](/api-reference/queries/filtertokens) with the same ranking attribute. See [Discover Tokens](/recipes/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](/concepts/subscriptions) (for user-facing dashboards and trading UIs) or [webhooks](/concepts/webhooks) (for server-side alerts and queues). | You want updates for... | Codex subscription | Codex webhook | | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | Token prices | [`onPriceUpdated`](/api-reference/subscriptions/onpriceupdated), [`onPricesUpdated`](/api-reference/subscriptions/onpricesupdated) | `TOKEN_PRICE_EVENT` | | OHLCV bars | [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated), [`onTokenBarsUpdated`](/api-reference/subscriptions/ontokenbarsupdated) | | | Token-level stats | [`onDetailedTokenStatsUpdated`](/api-reference/subscriptions/ondetailedtokenstatsupdated) | | | Pair-level stats | [`onDetailedStatsUpdated`](/api-reference/subscriptions/ondetailedstatsupdated) | | | Market cap thresholds | [`onPricesUpdated`](/api-reference/subscriptions/onpricesupdated) (derive: price × circulating supply) | `MARKET_CAP_EVENT` (thresholds on `fdvMarketCapUsd` / `circulatingMarketCapUsd`) | | Token trade events | [`onTokenEventsCreated`](/api-reference/subscriptions/ontokeneventscreated), [`onEventsCreated`](/api-reference/subscriptions/oneventscreated) | `TOKEN_PAIR_EVENT` (swaps, mints, burns) | | Token transfers | — | `TOKEN_TRANSFER_EVENT` | | Holder count changes | [`onHoldersUpdated`](/api-reference/subscriptions/onholdersupdated) | Approximate via `TOKEN_TRANSFER_EVENT` | | New pools/listings | [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated), [`onLaunchpadTokenEvent`](/api-reference/subscriptions/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`](/api-reference/subscriptions/ontokeneventscreated) or [`onEventsCreated`](/api-reference/subscriptions/oneventscreated), where CoinGecko's onchain trade endpoints cap at the last 300 trades over 24 hours with no streaming surface. * **Wallet analytics.** [`balances`](/api-reference/queries/balances), [`detailedWalletStats`](/api-reference/queries/detailedwalletstats), [`walletChart`](/api-reference/queries/walletchart), and [`filterWallets`](/api-reference/queries/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](/launchpads). * **Prediction markets.** Polymarket and Kalshi event, market, trade, and trader data via the [`filterPredictionEvents`](/api-reference/queries/filterpredictionevents) family (Growth or Enterprise plan). See [Prediction Markets](/prediction-markets). * **Liquidity locks.** [`liquidityLocks`](/api-reference/queries/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`](/api-reference/mutations/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](/agents/docs-mcp), prebuilt [Codex Skills](/agents/codex-skills) for Claude/Cursor/Codex CLI, and pay-per-query access via [MPP](/agents/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](/agents/codex-skills) and [docs MCP server](/agents/docs-mcp) so the agent can look up Codex queries on demand instead of guessing at field names. ```markdown theme={null} 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: ` for long-lived keys, or `Authorization: Bearer ` 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 `"
:"`. 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: "
:" })` (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: , 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: [] })` - `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/` (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](/api-reference/introduction) for the full schema. * Skim the [Recipes](/recipes/discover-tokens) for end-to-end examples that solve specific product problems. * Ask in [our community](https://t.me/codex_community) if you hit a wall during migration.