> ## 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.

# Birdeye to Codex

> Move your Birdeye Data Services integration to Codex

Birdeye Data Services (BDS) and Codex cover a similar problem space: real-time token, trade, and wallet data across Solana and EVM chains. This guide maps every Birdeye endpoint to its 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 migrate the rest of your codebase.

## Mental model

Birdeye is a REST API where the network is a request header (`x-chain`, defaults to Solana) and most resources have separate v1, v2, and v3 endpoints with different field naming conventions (camelCase in v1/v2, snake\_case in v3+). 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 (`networkId`) on each field.

What that means in practice:

* You stop maintaining version-specific code paths (the `/defi/v2/...` vs `/defi/v3/...` decision goes away).
* You stop juggling `x-chain` headers. Network selection lives next to the data, so the same query covers Solana, Ethereum, Base, BNB, and [80+ networks](https://docs.codex.io/networks).
* Multi-token requests stop needing separate batch endpoints. GraphQL aliases and array inputs handle that natively, and you only pay for the fields you request.
* Real-time data has two delivery options instead of one. Birdeye is WebSocket-only; Codex gives you [WebSocket subscriptions](/concepts/subscriptions) and [webhooks](/concepts/webhooks), and you can mix them in the same app.

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

Birdeye uses an `X-API-KEY` header plus an `x-chain` header that defaults to `solana` (so it's effectively required for every non-Solana request). Codex uses an `Authorization` header with your API key from the [dashboard](https://dashboard.codex.io?utm_source=codex\&utm_medium=docs\&utm_campaign=migrations-birdeye), and network comes through as a field argument instead of a header.

```bash Birdeye theme={null}
curl "https://public-api.birdeye.so/defi/price?address=So11111111111111111111111111111111111111112" \
  -H "X-API-KEY: $BIRDEYE_API_KEY" \
  -H "x-chain: solana"
```

```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: \"So11111111111111111111111111111111111111112\", networkId: 1399811149 }]) { priceUsd timestamp address } }"}'
```

For browser-facing apps, generate a short-lived JWT with [`createApiTokens`](/api-reference/mutations/createapitokens) and pass it as `Bearer <token>`. See [Authentication](/concepts/authentication) for the full pattern.

## Endpoint mapping

The table covers the Birdeye endpoints customers ask about most often, grouped by surface area. Where Birdeye splits a concept across v1, v2, and v3 endpoints, the Codex equivalent on the right replaces all of them.

### Prices and OHLCV

| Birdeye                                                                 | Codex equivalent                                                                   | Notes                                                                                                                                       |
| :---------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /defi/price`                                                       | [`getTokenPrices`](/api-reference/queries/gettokenprices)                          | Pass a single-element array.                                                                                                                |
| `GET /defi/multi_price`, `POST /defi/multi_price`                       | [`getTokenPrices`](/api-reference/queries/gettokenprices)                          | Native batch input, max 25 tokens per call (anything over is truncated). Birdeye's `multi_price` allows up to 100, so chunk larger batches. |
| `GET /defi/historical_price_unix`                                       | [`getTokenPrices`](/api-reference/queries/gettokenprices) with a `timestamp` input | Pass the unix timestamp on the input to get the price at that moment.                                                                       |
| `GET /defi/history_price`                                               | [`getTokenBars`](/api-reference/queries/gettokenbars)                              | Token-level OHLCV; pair-level via [`getBars`](/api-reference/queries/getbars).                                                              |
| `GET /defi/ohlcv`, `/defi/v3/ohlcv`                                     | [`getTokenBars`](/api-reference/queries/gettokenbars)                              | Codex supports 1-second up to weekly (`7D`) intervals.                                                                                      |
| `GET /defi/ohlcv/pair`, `/defi/v3/ohlcv/pair`                           | [`getBars`](/api-reference/queries/getbars)                                        | Pair-scoped OHLCV.                                                                                                                          |
| `GET /defi/ohlcv/base_quote`                                            | [`getBars`](/api-reference/queries/getbars) with `quoteToken`                      | Invert the pair to quote in the other token.                                                                                                |
| `GET /defi/price_volume/single`, `POST /defi/price_volume/multi`        | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)            | Price and volume in one query, plus much more.                                                                                              |
| `GET /defi/v3/price/stats/single`, `POST /defi/v3/price/stats/multiple` | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)            | Stats over multiple timeframes.                                                                                                             |

### Token data

| Birdeye                                                                       | Codex equivalent                                                                                                                                | Notes                                                                                                                         |
| :---------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `GET /defi/token_overview`                                                    | [`token`](/api-reference/queries/token) + [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)                               | One GraphQL request returns metadata, stats, safety, and launchpad context.                                                   |
| `GET /defi/v3/token/meta-data/single`                                         | [`token`](/api-reference/queries/token)                                                                                                         | Richer payload than Birdeye's, including social links and image URLs.                                                         |
| `GET /defi/v3/token/meta-data/multiple`                                       | [`tokens(ids: [{ address, networkId }])`](/api-reference/queries/tokens)                                                                        | Batch token metadata.                                                                                                         |
| `GET /defi/v3/token/market-data` (single + multiple)                          | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)                                                                         |                                                                                                                               |
| `GET /defi/v3/token/trade-data/single`, `/defi/v3/token/trade-data/multiple`  | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats)                                                                         | Trade stats are part of detailed token stats.                                                                                 |
| `GET /defi/token_security`                                                    | [`token`](/api-reference/queries/token)                                                                                                         | Safety fields (`isScam`, `mintable`, `freezable`, `creatorAddress`, top-holder concentration) are inline on the token object. |
| `GET /defi/token_creation_info`                                               | [`token`](/api-reference/queries/token)                                                                                                         | `createdAt`, `creatorAddress`.                                                                                                |
| `GET /defi/v3/token/exit-liquidity`, `/defi/v3/token/exit-liquidity/multiple` | [`liquidityMetadata`](/api-reference/queries/liquiditymetadata) + [`liquidityMetadataByToken`](/api-reference/queries/liquiditymetadatabytoken) | Plus [`liquidityLocks`](/api-reference/queries/liquiditylocks) for locked-LP context.                                         |

### Discovery and search

| Birdeye                                                                            | Codex equivalent                                                                                                   | Notes                                                                                                                                                                            |
| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /defi/token_trending`                                                         | [`filterTokens`](/api-reference/queries/filtertokens) ranked by `trendingScore24`                                  | See the [Discover Tokens recipe](/recipes/discover-tokens).                                                                                                                      |
| `GET /defi/v3/token/list`, `GET /defi/v3/token/list/scroll`, `GET /defi/tokenlist` | [`filterTokens`](/api-reference/queries/filtertokens)                                                              | Filters and rankings collapse into one query.                                                                                                                                    |
| `GET /defi/v2/tokens/new_listing`                                                  | [`filterTokens`](/api-reference/queries/filtertokens) ranked by `createdAt`                                        | Or subscribe to [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated) / [`onLatestTokens`](/api-reference/subscriptions/onlatesttokens). |
| `GET /defi/v3/search`                                                              | [`filterTokens(phrase: ...)`](/api-reference/queries/filtertokens)                                                 | Use `$SYMBOL` for exact symbol matches.                                                                                                                                          |
| `GET /defi/v3/token/meme/detail/single`, `GET /defi/v3/token/meme/list`            | [`filterTokens`](/api-reference/queries/filtertokens) + [launchpad context](/launchpads)                           | Codex models meme launches as launchpad lifecycle events (pump.fun, LetsBonk, etc.).                                                                                             |
| `GET /smart-money/v1/token/list`                                                   | [`filterTokens`](/api-reference/queries/filtertokens) plus [`filterWallets`](/api-reference/queries/filterwallets) | See the [Wallets recipe](/recipes/wallets) for the smart-money pattern.                                                                                                          |

### Pairs and markets

| Birdeye                               | Codex equivalent                                                                                                                                          | Notes                                                                                                                                                                   |
| :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /defi/v3/pair/overview/single`   | [`getDetailedPairStats`](/api-reference/queries/getdetailedpairstats)                                                                                     | Pair-level trade stats (volume, buys/sells, price change) are included. Birdeye has no separate pair `trade-data` endpoint; those fields live on the overview response. |
| `GET /defi/v3/pair/overview/multiple` | [`getDetailedPairsStats`](/api-reference/queries/getdetailedpairsstats)                                                                                   |                                                                                                                                                                         |
| `GET /defi/v2/markets`                | [`listPairsForToken`](/api-reference/queries/listpairsfortoken) + [`listPairsWithMetadataForToken`](/api-reference/queries/listpairswithmetadatafortoken) | All venues for a token.                                                                                                                                                 |

### Trades

| Birdeye                                                                             | Codex equivalent                                                                                                             | Notes                                                                                           |
| :---------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| `GET /defi/txs/token`, `GET /defi/v3/token/txs`, `GET /defi/txs/token/seek_by_time` | [`getTokenEvents`](/api-reference/queries/gettokenevents)                                                                    | Swap and lifecycle events for a token; pass a `timestamp` range for the "seek by time" variant. |
| `GET /defi/txs/pair`, `GET /defi/txs/pair/seek_by_time`                             | [`getTokenEvents`](/api-reference/queries/gettokenevents)                                                                    | Pass the pair address in `query: { address: ... }`.                                             |
| `GET /defi/v3/txs`, `GET /defi/v3/txs/recent`                                       | [`getTokenEvents`](/api-reference/queries/gettokenevents)                                                                    |                                                                                                 |
| `GET /defi/v3/token/txs-by-volume`                                                  | [`getTokenEvents`](/api-reference/queries/gettokenevents) with `priceUsdTotal` filter                                        | Filter swaps by USD size.                                                                       |
| `GET /defi/v3/token/mint-burn-txs` (Solana)                                         | [`getTokenEvents`](/api-reference/queries/gettokenevents) with `eventDisplayType: [Mint, Burn]`                              | Mint/burn lifecycle events.                                                                     |
| `GET /defi/v3/all-time/trades/single`, `POST /defi/v3/all-time/trades/multiple`     | [`getDetailedTokenStats`](/api-reference/queries/getdetailedtokenstats) (`statsUsd.volume`, `statsNonCurrency.transactions`) | Aggregate metrics, not raw rows.                                                                |

### Holders

| Birdeye                          | Codex equivalent                                                                                               | Notes                                                                                  |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| `GET /defi/v3/token/holder`      | [`holders`](/api-reference/queries/holders)                                                                    | Ranked holder list.                                                                    |
| `GET /holder/v1/distribution`    | `top10HoldersPercent` field on [`token`](/api-reference/queries/token)                                         | Concentration in one field.                                                            |
| `GET /token/v1/holder-profile`   | `top10HoldersPercent` on [`token`](/api-reference/queries/token) + [`holders`](/api-reference/queries/holders) | Combine concentration with the ranked holder list.                                     |
| `GET /token/v1/holder/chart`     | Partial via [`onHoldersUpdated`](/api-reference/subscriptions/onholdersupdated)                                | Codex streams live holder counts; historical timeseries is not a first-class endpoint. |
| `GET /token/v1/holder-positions` | [`filterTokenWallets`](/api-reference/queries/filtertokenwallets)                                              | Wallets ranked by per-token PnL.                                                       |
| `POST /token/v1/holder/batch`    | [`balances`](/api-reference/queries/balances) (per wallet)                                                     | One call per wallet; aliases let you batch in a single GraphQL request.                |

### Wallets

| Birdeye                                                                                                      | Codex equivalent                                                                                                              | Notes                                                                                                     |
| :----------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `GET /v1/wallet/token_list`                                                                                  | [`balances`](/api-reference/queries/balances)                                                                                 | Wallet portfolio with prices. Native balances on EVM chains require traces support; not available on Sui. |
| `GET /v1/wallet/token_balance`, `POST /wallet/v2/token-balance`                                              | [`balances`](/api-reference/queries/balances) with `tokens: [...]`                                                            | Pass the token IDs (`address:networkId`) you want; max 200 per request.                                   |
| `GET /v1/wallet/list_supported_chain`                                                                        | [`getNetworks`](/api-reference/queries/getnetworks)                                                                           | Network catalog used everywhere else in the API.                                                          |
| `GET /v1/wallet/tx_list`                                                                                     | [`getTokenEventsForMaker`](/api-reference/queries/gettokeneventsformaker)                                                     | Codex returns swap events for a wallet; raw transfers are not exposed.                                    |
| `GET /wallet/v2/current-net-worth`                                                                           | [`detailedWalletStats`](/api-reference/queries/detailedwalletstats)                                                           | PnL, volume, swap counts.                                                                                 |
| `GET /wallet/v2/net-worth`, `/wallet/v2/net-worth-details`, `POST /wallet/v2/net-worth-summary/multiple`     | [`walletChart`](/api-reference/queries/walletchart) + [`detailedWalletStats`](/api-reference/queries/detailedwalletstats)     | Use GraphQL aliases to batch multiple wallets in one request.                                             |
| `GET /wallet/v2/pnl`, `/wallet/v2/pnl/summary`, `GET /wallet/v2/pnl/multiple`, `POST /wallet/v2/pnl/details` | [`detailedWalletStats`](/api-reference/queries/detailedwalletstats) + [`filterWallets`](/api-reference/queries/filterwallets) |                                                                                                           |
| `GET /wallet/v2/balance-change`                                                                              | [`onBalanceUpdated`](/api-reference/subscriptions/onbalanceupdated) subscription                                              | Live balance changes; historical reconstruction requires combining events.                                |
| `POST /wallet/v2/tx/first-funded`                                                                            | Not directly supported                                                                                                        | Flag during migration.                                                                                    |

### Traders

| Birdeye                           | Codex equivalent                                                                       | Notes                                         |
| :-------------------------------- | :------------------------------------------------------------------------------------- | :-------------------------------------------- |
| `GET /defi/v2/tokens/top_traders` | [`tokenTopTraders`](/api-reference/queries/tokentoptraders)                            | Top buyers/sellers/PnL for a token.           |
| `GET /trader/txs/seek_by_time`    | [`getTokenEventsForMaker`](/api-reference/queries/gettokeneventsformaker)              |                                               |
| `GET /trader/gainers-losers`      | [`filterWallets`](/api-reference/queries/filterwallets) ranked by `realizedProfitUsd*` | Far richer filtering than Birdeye's endpoint. |

### Utility

| Birdeye                         | Codex equivalent                                           | Notes                                                                                                     |
| :------------------------------ | :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `GET /defi/networks`            | [`getNetworks`](/api-reference/queries/getnetworks)        | Returns `networkId`s you'll use everywhere else.                                                          |
| `GET /defi/v3/txs/latest-block` | [`blocks`](/api-reference/queries/blocks)                  | Look up blocks by `blockNumbers` or `timestamps`; pass the current timestamp to resolve the latest block. |
| `GET /utils/v1/credits`         | Codex usage in the [dashboard](https://dashboard.codex.io) |                                                                                                           |

## Side-by-side examples

The four patterns below are the ones Birdeye customers most commonly migrate first. Token addresses are real and queries are runnable.

### 1. Multi-token price

<CodeGroup>
  ```bash Birdeye theme={null}
  curl -X POST "https://public-api.birdeye.so/defi/multi_price" \
    -H "X-API-KEY: $BIRDEYE_API_KEY" \
    -H "x-chain: solana" \
    -H "Content-Type: application/json" \
    -d '{"list_address":"So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}'
  ```

  ```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: "So11111111111111111111111111111111111111112", networkId: 1399811149 },
      { address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", networkId: 1399811149 },
    ],
  })

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

  ```graphql Codex GraphQL theme={null}
  query MultiPrice {
    getTokenPrices(
      inputs: [
        { address: "So11111111111111111111111111111111111111112", networkId: 1399811149 }
        { address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", networkId: 1399811149 }
      ]
    ) {
      address
      networkId
      priceUsd
      timestamp
    }
  }
  ```
</CodeGroup>

For a live price feed instead of polling, subscribe to [`onPricesUpdated`](/api-reference/subscriptions/onpricesupdated).

### 2. OHLCV chart

<CodeGroup>
  ```bash Birdeye theme={null}
  curl "https://public-api.birdeye.so/defi/v3/ohlcv?address=So11111111111111111111111111111111111111112&type=1H&time_from=1716595200&time_to=1717200000" \
    -H "X-API-KEY: $BIRDEYE_API_KEY" \
    -H "x-chain: solana"
  ```

  ```graphql Codex GraphQL theme={null}
  query TokenChart {
    getTokenBars(
      symbol: "So11111111111111111111111111111111111111112:1399811149"
      from: 1716595200
      to: 1717200000
      resolution: "60"
    ) {
      t
      o
      h
      l
      c
      volume
    }
  }
  ```
</CodeGroup>

Codex supports resolutions from 1-second up to weekly (`7D`). Sub-minute resolutions (`1S`-`30S`) are only populated for the last 24 hours, and Birdeye's monthly (`1M`) candles have no direct equivalent (aggregate from `1D` or `7D` bars). For live chart updates, layer in the [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated) subscription. See the [Charts recipe](/recipes/charts) for a full Lightweight Charts integration.

### 3. Token overview (metadata + stats + safety)

Birdeye splits this across `/defi/token_overview`, `/defi/v3/token/market-data`, and `/defi/token_security`. Codex returns the same picture in a single request.

<CodeGroup>
  ```bash Birdeye theme={null}
  curl "https://public-api.birdeye.so/defi/token_overview?address=So11111111111111111111111111111111111111112" \
    -H "X-API-KEY: $BIRDEYE_API_KEY" \
    -H "x-chain: solana"

  curl "https://public-api.birdeye.so/defi/token_security?address=So11111111111111111111111111111111111111112" \
    -H "X-API-KEY: $BIRDEYE_API_KEY" \
    -H "x-chain: solana"
  ```

  ```graphql Codex GraphQL theme={null}
  query TokenOverview {
    token(input: { address: "So11111111111111111111111111111111111111112", networkId: 1399811149 }) {
      name
      symbol
      decimals
      address
      isScam
      mintable
      freezable
      creatorAddress
      createdAt
      top10HoldersPercent
      info {
        circulatingSupply
        totalSupply
        imageLargeUrl
        description
      }
      socialLinks {
        twitter
        telegram
        discord
        website
      }
      launchpad {
        launchpadName
        graduationPercent
        completed
      }
    }
    getDetailedTokenStats(
      tokenAddress: "So11111111111111111111111111111111111111112"
      networkId: 1399811149
      durations: [day1]
    ) {
      stats_day1 {
        statsUsd {
          volume {
            currentValue
            change
          }
          close {
            currentValue
            change
          }
        }
        statsNonCurrency {
          transactions {
            currentValue
          }
          buys {
            currentValue
          }
          sells {
            currentValue
          }
        }
      }
    }
  }
  ```
</CodeGroup>

The [Detailed Token Page recipe](/recipes/detailed-token-page) shows the full pattern Codex customers use to build a token detail screen.

### 4. Wallet portfolio

<CodeGroup>
  ```bash Birdeye theme={null}
  curl "https://public-api.birdeye.so/v1/wallet/token_list?wallet=Bi4rd5FH5bYEN8scZ7wevxNZyNmKHdaBcvewdPFxYdLt" \
    -H "X-API-KEY: $BIRDEYE_API_KEY" \
    -H "x-chain: solana"
  ```

  ```graphql Codex GraphQL theme={null}
  query WalletPortfolio {
    balances(
      input: {
        walletAddress: "Bi4rd5FH5bYEN8scZ7wevxNZyNmKHdaBcvewdPFxYdLt"
        networks: [1399811149]
        removeScams: true
      }
    ) {
      items {
        tokenId
        shiftedBalance
        balanceUsd
        tokenPriceUsd
      }
      cursor
    }
  }
  ```
</CodeGroup>

Enrich the response with live USD pricing by batching the returned `tokenId`s into [`getTokenPrices`](/api-reference/queries/gettokenprices). For wallet-level PnL and volume, see [`detailedWalletStats`](/api-reference/queries/detailedwalletstats) and the [Wallets recipe](/recipes/wallets).

## Real-time data

Birdeye delivers real-time data exclusively through WebSocket subscriptions at `wss://public-api.birdeye.so/socket/<chain>`. Codex gives you the same data with two delivery options, and you can use both at once:

* [WebSocket subscriptions](/concepts/subscriptions): persistent connection, updates pushed inline. Best for dashboards, trading UIs, anything user-facing.
* [Webhooks](/concepts/webhooks): Codex calls an HTTP endpoint you control when an event fires. Best for background jobs, alerts, and queue-driven systems.

| Birdeye channel                                     | Codex subscription                                                                                                                                                                                                                            | Codex webhook                                                                                                       |
| :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `SUBSCRIBE_PRICE`                                   | [`onPriceUpdated`](/api-reference/subscriptions/onpriceupdated), [`onPricesUpdated`](/api-reference/subscriptions/onpricesupdated)                                                                                                            | Price webhook                                                                                                       |
| `SUBSCRIBE_BASE_QUOTE_PRICE`                        | [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated)                                                                                                                                                                                 |                                                                                                                     |
| `SUBSCRIBE_TOKEN_STATS`                             | [`onDetailedTokenStatsUpdated`](/api-reference/subscriptions/ondetailedtokenstatsupdated)                                                                                                                                                     |                                                                                                                     |
| `SUBSCRIBE_TXS`                                     | [`onTokenEventsCreated`](/api-reference/subscriptions/ontokeneventscreated), [`onEventsCreated`](/api-reference/subscriptions/oneventscreated)                                                                                                | Token swap webhook                                                                                                  |
| `SUBSCRIBE_WALLET_TXS`                              | [`onEventsCreatedByMaker`](/api-reference/subscriptions/oneventscreatedbymaker)                                                                                                                                                               | Token swap webhook (maker filter)                                                                                   |
| `SUBSCRIBE_LARGE_TRADE_TXS`                         | [`onEventsCreated`](/api-reference/subscriptions/oneventscreated) with min-volume filter                                                                                                                                                      |                                                                                                                     |
| `SUBSCRIBE_NEW_PAIR`, `SUBSCRIBE_TOKEN_NEW_LISTING` | [`onTokenLifecycleEventsCreated`](/api-reference/subscriptions/ontokenlifecycleeventscreated), [`onLatestTokens`](/api-reference/subscriptions/onlatesttokens), [`onLaunchpadTokenEvent`](/api-reference/subscriptions/onlaunchpadtokenevent) |                                                                                                                     |
| `SUBSCRIBE_MEME`                                    | [`onLaunchpadTokenEvent`](/api-reference/subscriptions/onlaunchpadtokenevent) + [`onDetailedTokenStatsUpdated`](/api-reference/subscriptions/ondetailedtokenstatsupdated)                                                                     |                                                                                                                     |
| `SUBSCRIBE_TRANSFER`                                | Not directly supported                                                                                                                                                                                                                        | Codex streams swap and lifecycle events, not arbitrary token transfers. Pair with an RPC provider if you need this. |

## Gaps

Things Birdeye does that Codex doesn't, and what to do about them:

* **Perpetuals data** (`/perps/v1/*`). Codex is a spot-trading API. If your product depends on open positions, liquidation maps, or perp wallets, keep Birdeye for that surface or pair Codex with a perps-native provider.
* **Wallet-level transfers (non-swap)** (`/wallet/v2/transfer*`, `/token/v1/transfer*`). Codex returns swap and token-lifecycle events, not arbitrary token transfers. Combine Codex with an RPC provider or Etherscan-family API if transfer history is core to your product.
* **NFT data.** Birdeye doesn't ship a full NFT product either, but if your codebase touches NFT collections or holdings, Codex won't fill that gap.
* **Centralized exchange liquidity dashboards.** Codex is onchain-only.
* **First-funded-by lookup** (`POST /wallet/v2/tx/first-funded`). No direct equivalent; flag during migration.
* **Native-token balances on chains without traces.** `balances` returns ERC-20/SPL holdings on every supported network, but native-token amounts on EVM chains require traces support. Sui balances aren't available at all (`networkId: 101`).

## What you pick up

Things Codex offers that Birdeye doesn't:

* **One query, many shapes.** GraphQL lets you combine token metadata, price, holders, recent trades, and chart data into a single request and only pull the fields you render. A typical Birdeye-powered token page hits three or four endpoints; the Codex equivalent is one.
* **Webhooks alongside subscriptions.** Push real-time data to your servers without holding open a WebSocket. Configure via [`createWebhooks`](/api-reference/mutations/createwebhooks).
* **Prediction markets.** Polymarket and Kalshi event, market, trade, and trader data via the [`filterPredictionEvents`](/api-reference/queries/filterpredictionevents) family. See [Prediction Markets](/prediction-markets).
* **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).
* **Wallet discovery by performance.** [`filterWallets`](/api-reference/queries/filterwallets) lets you query for wallets matching specific PnL, win-rate, or trading-volume criteria across all networks, not just for a single token.
* **Liquidity locks.** [`liquidityLocks`](/api-reference/queries/liquiditylocks) surfaces locked-LP context that Birdeye's `/defi/v3/token/exit-liquidity` doesn't.
* **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 Birdeye integrations span dozens of call sites: a price service here, a chart loader there, a portfolio screen, a webhook handler. 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 Birdeye touchpoint, propose a plan, and execute the migration with your approval.

<Tip>
  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.
</Tip>

```markdown theme={null}
You are migrating this codebase from Birdeye Data Services (BDS) to Codex (https://docs.codex.io). Birdeye and Codex overlap heavily on token, trade, holder, and wallet data, so most call sites have a direct replacement. A few do not, and those need to be surfaced rather than silently dropped.

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

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

- HTTP calls to `public-api.birdeye.so` (any path under `/defi`, `/wallet`, `/token`, `/trader`, `/perps`, `/smart-money`, `/utils`, `/holder`, or `/v1/wallet`).
- WebSocket connections to `wss://public-api.birdeye.so/socket/...`.
- Imports of any Birdeye SDK or client library.
- Environment variables and config keys named `BIRDEYE_*` or `BDS_*`.
- Header usage of `X-API-KEY` and `x-chain`.
- Code that switches behavior on Birdeye `chain` strings (`solana`, `ethereum`, `base`, etc.).
- 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 Birdeye 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.

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. Codex ships an official SDK for TypeScript/JavaScript only (`@codex-data/sdk`). Prefer it over hand-rolled HTTP in TS/JS projects. For Python and every other language there is no official SDK: use raw GraphQL over HTTP against `https://graph.codex.io/graphql`.
3. Network is a parameter (`networkId`), not a header. Convert Birdeye `x-chain` strings to Codex network IDs: `solana` → 1399811149, `ethereum` → 1, `base` → 8453, `bsc` → 56, `polygon` → 137, `arbitrum` → 42161, `optimism` → 10, `avalanche` → 43114, `sui` → 101. For others, call `getNetworks` once and build a lookup.
4. Token IDs in Codex are the string `"<address>:<networkId>"`. Construct them explicitly; never assume an integration relies on bare addresses.
5. Where a Birdeye integration hits two or three endpoints to fill one screen (for example token_overview + token_security + market-data), collapse them into a single GraphQL query.
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).
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 Birdeye response fixture, replace the fixture with a Codex equivalent rather than deleting the test.
9. When you hit a gap (perpetuals, non-swap wallet transfers, first-funded-by lookup, CEX liquidity), 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. Note that Sui (`networkId: 101`) is supported broadly, but `balances` is not available on Sui: flag any Sui balance lookups specifically.

## Birdeye → Codex endpoint mapping

Prices and OHLCV:
- `GET /defi/price`, `GET|POST /defi/multi_price` → `getTokenPrices(inputs: [...])` (max 25 inputs per call; chunk Birdeye `multi_price` batches larger than 25 or they will be silently truncated)
- `GET /defi/historical_price_unix` → `getTokenPrices(inputs: [{ address, networkId, timestamp }])` (the historical price at a unix timestamp)
- `GET /defi/history_price` → `getTokenBars`
- `GET /defi/ohlcv`, `/defi/v3/ohlcv` → `getTokenBars`
- `GET /defi/ohlcv/pair`, `/defi/v3/ohlcv/pair`, `/defi/ohlcv/base_quote` → `getBars` (use `quoteToken: token0 | token1` to invert the pair)
- `GET /defi/price_volume/*`, `/defi/v3/price/stats/*` → `getDetailedTokenStats(tokenAddress, networkId, durations: [...])` (top-level args, not an `input` object)

Token data:
- `GET /defi/token_overview` → `token` + `getDetailedTokenStats` in one query
- `GET /defi/v3/token/meta-data/single` → `token(input: { address, networkId })`
- `GET /defi/v3/token/meta-data/multiple` → `tokens(ids: [{ address, networkId }, ...])`
- `GET /defi/v3/token/market-data*`, `/defi/v3/token/trade-data/*` → `getDetailedTokenStats`
- `GET /defi/token_security` → safety fields on `token` (`isScam`, `mintable`, `freezable`, `creatorAddress`, `top10HoldersPercent`). `circulatingSupply` and `totalSupply` live under `token.info`, not the top-level token object.
- `GET /defi/token_creation_info` → `createdAt`, `creatorAddress` on `token`
- `GET /defi/v3/token/exit-liquidity`, `/defi/v3/token/exit-liquidity/multiple` → `liquidityMetadata`, `liquidityMetadataByToken`, `liquidityLocks`

Discovery:
- `GET /defi/token_trending` → `filterTokens(rankings: [{ attribute: trendingScore24, direction: DESC }])`
- `GET /defi/v3/token/list`, `/defi/v3/token/list/scroll`, `/defi/tokenlist`, `/defi/v2/tokens/new_listing` → `filterTokens(...)`
- `GET /defi/v3/search` → `filterTokens(phrase: "$SYMBOL", ...)`
- `GET /defi/v3/token/meme/*` → `filterTokens` plus launchpad fields on `token.launchpad`
- `GET /smart-money/v1/token/list` → `filterWallets` + `filterTokens` (see Wallets recipe)

Pairs:
- `GET /defi/v3/pair/overview/single` → `getDetailedPairStats` (pair trade stats are part of this response; Birdeye has no separate pair `trade-data` endpoint)
- `GET /defi/v3/pair/overview/multiple` → `getDetailedPairsStats`
- `GET /defi/v2/markets` → `listPairsForToken` or `listPairsWithMetadataForToken`

Trades:
- `GET /defi/txs/token`, `/defi/txs/token/seek_by_time`, `/defi/v3/token/txs`, `/defi/v3/txs`, `/defi/v3/txs/recent` → `getTokenEvents(query: { address, networkId, ... })`
- `GET /defi/txs/pair`, `/defi/txs/pair/seek_by_time` → `getTokenEvents` (pair address as `query.address`)
- `GET /defi/v3/token/txs-by-volume` → `getTokenEvents` with `priceUsdTotal` filter
- `GET /defi/v3/token/mint-burn-txs` → `getTokenEvents` with `eventDisplayType: [Mint, Burn]` (Solana only)
- `GET /defi/v3/all-time/trades/single`, `POST /defi/v3/all-time/trades/multiple` → `getDetailedTokenStats` (read `statsUsd.volume.currentValue`, `statsNonCurrency.transactions.currentValue`)

Holders:
- `GET /defi/v3/token/holder` → `holders(input: { tokenId, sort: { attribute: BALANCE, direction: DESC } })` (`BALANCE` is the only supported sort attribute; `DATE` exists but is deprecated)
- `GET /holder/v1/distribution`, `/token/v1/holder-profile` → `top10HoldersPercent` on `token` (combine with `holders` for the ranked list)
- `GET /token/v1/holder/chart` → partial via `onHoldersUpdated` (live counts only; no first-class historical timeseries)
- `GET /token/v1/holder-positions` → `filterTokenWallets`
- `POST /token/v1/holder/batch` → `balances` per wallet (use GraphQL aliases to batch)

Wallets:
- `GET /v1/wallet/token_list`, `/v1/wallet/token_balance`, `POST /wallet/v2/token-balance` → `balances(input: { walletAddress, networks: [Int!], removeScams, tokens, limit })` (the network field is plural/array, not `networkId`; max 200 tokens per request)
- `GET /v1/wallet/list_supported_chain` → `getNetworks`
- `GET /v1/wallet/tx_list` → `getTokenEventsForMaker` (swap events; flag if raw transfers are required)
- `GET /wallet/v2/current-net-worth`, `/wallet/v2/pnl`, `/wallet/v2/pnl/summary`, `/wallet/v2/pnl/multiple`, `POST /wallet/v2/pnl/details` → `detailedWalletStats` and `filterWallets`
- `GET /wallet/v2/net-worth`, `/wallet/v2/net-worth-details`, `POST /wallet/v2/net-worth-summary/multiple` → `walletChart` + `detailedWalletStats` (alias multiple wallets in one request)
- `GET /wallet/v2/balance-change` → `onBalanceUpdated` subscription

Traders:
- `GET /defi/v2/tokens/top_traders` → `tokenTopTraders(input: { tokenAddress, networkId, tradingPeriod })` (`tradingPeriod` is `DAY | WEEK | MONTH | YEAR` — no hourly value)
- `GET /trader/txs/seek_by_time` → `getTokenEventsForMaker`
- `GET /trader/gainers-losers` → `filterWallets(input: { rankings: [{ attribute: realizedProfitUsd1d, direction: DESC }] })` (pick `1d` / `1w` / `30d` / `1y` to match the timeframe)

Real-time (WebSocket → Codex subscription):
- `SUBSCRIBE_PRICE` → `onPriceUpdated` / `onPricesUpdated`
- `SUBSCRIBE_BASE_QUOTE_PRICE` → `onBarsUpdated`
- `SUBSCRIBE_TOKEN_STATS` → `onDetailedTokenStatsUpdated`
- `SUBSCRIBE_TXS`, `SUBSCRIBE_LARGE_TRADE_TXS` → `onTokenEventsCreated` / `onEventsCreated` (apply a min-volume filter for the large-trade variant)
- `SUBSCRIBE_WALLET_TXS` → `onEventsCreatedByMaker`
- `SUBSCRIBE_NEW_PAIR`, `SUBSCRIBE_TOKEN_NEW_LISTING`, `SUBSCRIBE_MEME` → `onTokenLifecycleEventsCreated`, `onLatestTokens`, `onLaunchpadTokenEvent`
- `SUBSCRIBE_TRANSFER` → not supported (Codex streams swaps and lifecycle events, not arbitrary transfers)

Utility:
- `GET /defi/networks` → `getNetworks`
- `GET /defi/v3/txs/latest-block` → `blocks(input: { networkId, blockNumbers, timestamps })`

Gaps (flag, do not drop):
- `/perps/v1/*`: not supported
- `/wallet/v2/transfer*`, `/token/v1/transfer*`: Codex is swap-focused; pair with an RPC provider for raw transfers
- `POST /wallet/v2/tx/first-funded`: no direct equivalent
- NFT endpoints: Codex does not expose NFT data
- Sui (`networkId: 101`): broadly supported, but `balances` does not work on Sui. Flag Sui balance call sites specifically.
- EVM native balances via `balances` are only available on networks with traces enabled. If a customer relies on native-token portfolio values on a chain without traces, flag 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. Birdeye 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](/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.