# Codex API Documentation

Codex provides a unified GraphQL API for accessing token prices, trades, liquidity pools, NFT data, and wallet analytics across EVM and non-EVM chains. Used by trading bots, portfolio trackers, analytics dashboards, DeFi applications, and AI agents.

## Key Information

- **GraphQL endpoint**: `https://graph.codex.io/graphql`
- **WebSocket endpoint**: `wss://graph.codex.io/graphql`
- **Auth**: Pass your API key in the `Authorization` header
- **Full docs**: https://docs.codex.io
- **llms-full.txt**: https://docs.codex.io/llms-full.txt
- **AI Agents**: Install the Codex skill for your AI coding agent to write Codex API queries directly: https://docs.codex.io/agents/codex-skills#codex-skills

## Getting Started
- [Intro to Codex](/index): Codex is the fastest, most reliable enhanced data API for DeFi data across 100+ networks
- [Get Started](/get-started): Make your first request on the Codex API
- [Add Codex to Your App](/build): You have two options for adding the Codex API into your app
- [Using the SDK](/sdk): Adding the Codex Typescript SDK to your app
- [Using the GraphQL API](/learn-graphql): Learn useful terminology and concepts for using the GraphQL API

## Core Concepts
- [Authentication](/concepts/authentication): Making requests to the Codex API
- [Queries](/concepts/queries): On-demand data requests — the basic building block of the Codex API
- [Subscriptions](/concepts/subscriptions): Real-time data streams via GraphQL subscriptions over WebSockets
- [Webhooks](/concepts/webhooks): Use your own HTTP endpoints to receive real-time updates
- [Rate Limits & Connection Limits](/concepts/rate-limits): Understand how requests are counted, connection limits, and how to optimize your usage
- [Optimization](/concepts/optimization): Best practices for reducing API usage, improving performance, and architecting efficient integrations

## Recipes & Use Cases
- [Token Dashboard](/recipes/token-dashboard): Learn how to build a comprehensive token detail page with price, holders, safety, trades, and real-time updates
- [Discover Tokens](/recipes/discover-tokens): Learn how to build token dashboards with trending data, advanced filters, and token search
- [Events](/recipes/events): Learn how to get a list of token events
- [Charts](/recipes/charts): Learn how to render a token chart with the Codex API
- [Launchpads](/recipes/launchpads): Filter through launchpad data and get realtime updates.
- [Launchpad Lifecycle](/recipes/launchpad-lifecycle): Understand how tokens progress through launchpad stages — from creation to bonding curve to graduation and migration.
- [Wallets](/recipes/wallets): Learn how to analyze wallet performance and discover traders with the Codex API
- [Prediction Event Dashboard](/recipes/prediction-event-dashboard): Learn how to build a comprehensive prediction event detail page with markets, charts, trades, and real-time pricing
- [Discover Prediction Markets](/recipes/discover-prediction-markets): Learn how to build prediction market discovery pages with filtering, ranking, and search
- [Prediction Charts](/recipes/prediction-charts): Learn how to render prediction market charts with outcome probabilities, event activity, and multi-market comparisons
- [Prediction Traders](/recipes/prediction-traders): Learn how to build trader leaderboards, profiles, and portfolio analytics for prediction market traders

## Agents & AI Integration
- [Codex Docs MCP](/agents/docs-mcp): Add the Codex documentation MCP server to your AI coding tools for instant access to API docs.
- [Codex Skills](/agents/codex-skills): Install the Codex skills to give your AI coding agent the ability to write Codex API queries.
- [x402 & MPP](/agents/x402-mpp): Enable AI agents to pay for Codex API access using the Machine Payments Protocol (MPP) over HTTP 402.

## Resources
- [Frequently Asked Questions](/extra/faq): Find answers to commonly asked questions about Codex
- [Troubleshooting](/extra/troubleshooting): Solutions for common errors and issues with the Codex API
- [Queries vs Subscriptions](/extra/queries-vs-subscriptions): Understand when to use queries vs subscriptions, and which endpoints map to each other

## Supported Networks
[Supported Networks](/networks/index), [Ethereum API](/networks/ethereum), [Base API](/networks/base), [BNB Chain API](/networks/bsc), [Arbitrum API](/networks/arbitrum), [Polygon API](/networks/polygon), [Avalanche API](/networks/avalanche), [Optimism API](/networks/optimism), [MegaETH API](/networks/megaeth), [Unichain API](/networks/unichain), [Plasma API](/networks/plasma), [Monad API](/networks/monad), [Tempo API](/networks/tempo), [Solana API](/networks/solana), [Sui API](/networks/sui), [Aptos API](/networks/aptos), [StarkNet API](/networks/starknet)

## Supported Launchpads
[Supported Launchpads](/launchpads/index), [Pump.fun API](/launchpads/pump-fun), [Four.meme API](/launchpads/four-meme), [LaunchLab API](/launchpads/launchlab), [Meteora API](/launchpads/meteora), [Clanker API](/launchpads/clanker), [Virtuals API](/launchpads/virtuals), [Zora API](/launchpads/zora), [Zora Solana API](/launchpads/zora-solana), [Baseapp API](/launchpads/baseapp)

## Prediction Markets
- [Supported Prediction Markets](/prediction-markets/index): Access real-time prediction market data from leading platforms with the Codex API. Track market prices, trading activity, events, and trader analytics.
- [Polymarket API](/prediction-markets/polymarket): Access real-time Polymarket prediction market data through the Codex API. Track market prices, outcome probabilities, trading volumes, events, and trader analytics.
- [Kalshi API](/prediction-markets/kalshi): Access real-time Kalshi prediction market data through the Codex API. Track market prices, trading volumes, events, and trader analytics on the first CFTC-regulated prediction market exchange.

## Tools
- [Explore](/explore/index)

## API Reference
- [GraphQL API Reference](/api-reference/introduction): Explore all of the GraphQL queries, mutations, and types available in the Codex API

## API Queries
- [filterTokens](/api-reference/queries/filtertokens): Returns a list of tokens based on a variety of filters.
- [filterExchanges](/api-reference/queries/filterexchanges): Returns a list of exchanges based on a variety of filters.
- [getDetailedTokenStats](/api-reference/queries/getdetailedtokenstats): Returns bucketed stats for a given token.
- [getTokenPrices](/api-reference/queries/gettokenprices): Returns real-time or historical prices for a list of tokens, fetched in batches.
- [getTokenBars](/api-reference/queries/gettokenbars): Returns aggregated bar chart data to track price changes over time.
- [top10HoldersPercent](/api-reference/queries/top10holderspercent): Returns the percentage of a token's total supply held collectively by its top 10 holders.
- [tokenLifecycleEvents](/api-reference/queries/tokenlifecycleevents): Returns a list of token lifecycle events.
- [token](/api-reference/queries/token): Returns a single token by its address & network id.
- [tokens](/api-reference/queries/tokens): Returns a list of tokens by their addresses & network id, with pagination.
- [tokenSparklines](/api-reference/queries/tokensparklines): Returns a list of token simple chart data (sparklines) for the given tokens.
- [tokenTopTraders](/api-reference/queries/tokentoptraders): Returns a list of top traders for a given token.
- [filterPairs](/api-reference/queries/filterpairs): Returns a list of pairs based on a variety of filters.
- [getDetailedPairStats](/api-reference/queries/getdetailedpairstats): Returns bucketed stats for a given token within a pair.
- [getDetailedPairsStats](/api-reference/queries/getdetailedpairsstats): Returns bucketed stats for a given token within a list of pairs.
- [getSymbol](/api-reference/queries/getsymbol): Returns charting metadata for a given pair. Used for implementing a Trading View datafeed.
- [getBars](/api-reference/queries/getbars): Returns bar chart data to track price changes over time.
- [getExchanges](/api-reference/queries/getexchanges): Returns a list of decentralized exchange metadata.
- [chartUrls](/api-reference/queries/charturls): Returns a URL for a pair chart.
- [pairMetadata](/api-reference/queries/pairmetadata): Returns metadata for a pair of tokens.
- [listPairsForToken](/api-reference/queries/listpairsfortoken): Returns a list of pairs containing a given token.
- [listPairsWithMetadataForToken](/api-reference/queries/listpairswithmetadatafortoken): Returns a list of pair metadata for a token.
- [liquidityLocks](/api-reference/queries/liquiditylocks): Returns liquidity locks for a given pair.
- [liquidityMetadata](/api-reference/queries/liquiditymetadata): Returns liquidity metadata for a given pair. Includes liquidity lock data.
- [liquidityMetadataByToken](/api-reference/queries/liquiditymetadatabytoken): Returns liquidity metadata for a given token. Includes liquidity lock data for up to 100 pairs that the token is in.
- [getTokenEvents](/api-reference/queries/gettokenevents): Returns transactions for a pair.
- [getTokenEventsForMaker](/api-reference/queries/gettokeneventsformaker): Returns a list of token events for a given maker (wallet address).
- [getEventLabels](/api-reference/queries/geteventlabels): Returns a list of event labels for a pair.
- [walletAggregateBackfillState](/api-reference/queries/walletaggregatebackfillstate): Once a wallet backfill has been triggered, this query can be used to check the status of the backfill.
- [filterWallets](/api-reference/queries/filterwallets): Returns a list of wallets based on a variety of filters.
- [filterTokenWallets](/api-reference/queries/filtertokenwallets): Returns a list of wallets with stats narrowed down to a specific token.
- [detailedWalletStats](/api-reference/queries/detailedwalletstats): Returns detailed stats for a wallet.
- [walletChart](/api-reference/queries/walletchart): Returns a chart of a wallet's activity.
- [apiTokens](/api-reference/queries/apitokens): Get all active short-lived api tokens for this api key
- [apiToken](/api-reference/queries/apitoken): Get the active short-lived api token for this api key by the short-lived token
- [balances](/api-reference/queries/balances): Returns list of token balances that a wallet has.
- [holders](/api-reference/queries/holders): Returns list of wallets that hold a given token, ordered by holdings descending. Also has the unique count of holders for that token.
- [getCommunityNotes](/api-reference/queries/getcommunitynotes): Returns community gathered notes.
- [blocks](/api-reference/queries/blocks): Returns block data for the input blockNumbers or timestamps, maximum 25 inputs.
- [getNetworks](/api-reference/queries/getnetworks): Returns a list of all networks supported on Codex.
- [getNetworkStatus](/api-reference/queries/getnetworkstatus): Returns the status of a list of networks supported on Codex.
- [getNetworkConfigs](/api-reference/queries/getnetworkconfigs): Query operation
- [getNetworkStats](/api-reference/queries/getnetworkstats): Returns metadata for a given network supported on Codex.
- [detailedPredictionMarketStats](/api-reference/queries/detailedpredictionmarketstats): Returns windowed and all-time stats for a prediction market.
- [detailedPredictionEventStats](/api-reference/queries/detailedpredictioneventstats): Returns windowed and all-time stats for a prediction event.
- [detailedPredictionTraderStats](/api-reference/queries/detailedpredictiontraderstats): Returns windowed and all-time stats for a prediction trader.
- [predictionTraderMarketsStats](/api-reference/queries/predictiontradermarketsstats): Returns per-market performance stats for a specific trader.
- [predictionTraderBars](/api-reference/queries/predictiontraderbars): Returns bar data for a prediction trader over a time range.
- [predictionMarketBars](/api-reference/queries/predictionmarketbars): Returns OHLC-style bar data for a prediction market.
- [predictionEventBars](/api-reference/queries/predictioneventbars): Returns bar data for a prediction event.
- [predictionEventTopMarketsBars](/api-reference/queries/predictioneventtopmarketsbars): Returns bar data for top markets inside a prediction event.
- [predictionTrades](/api-reference/queries/predictiontrades): Returns prediction trades with cursor-based pagination.
- [predictionMarkets](/api-reference/queries/predictionmarkets): Returns prediction markets by ID.
- [predictionTraders](/api-reference/queries/predictiontraders): Returns prediction traders by ID.
- [predictionTokenHolders](/api-reference/queries/predictiontokenholders): Returns token holder balances for a prediction market.
- [filterPredictionEvents](/api-reference/queries/filterpredictionevents): Filters prediction events using optional text, IDs, and ranking criteria.
- [predictionCategories](/api-reference/queries/predictioncategories): Returns available prediction categories and nested subcategories.
- [filterPredictionMarkets](/api-reference/queries/filterpredictionmarkets): Filters prediction markets using optional text, IDs, event constraints, and ranking criteria.
- [filterPredictionTraderMarkets](/api-reference/queries/filterpredictiontradermarkets): Filters trader-market records using trader, market, event, and ranking criteria.
- [filterPredictionTraders](/api-reference/queries/filterpredictiontraders): Filters prediction traders using optional text, IDs, and ranking criteria.
- [getWebhooks](/api-reference/queries/getwebhooks): Returns a user's list of webhooks.

## API Subscriptions
- [onTokenBarsUpdated](/api-reference/subscriptions/ontokenbarsupdated): Live-streamed aggregate bar chart data to track price changes over time for a token.
- [onPriceUpdated](/api-reference/subscriptions/onpriceupdated): Live-streamed price updates for a token.
- [onPricesUpdated](/api-reference/subscriptions/onpricesupdated): Live-streamed price updates for multiple tokens.
- [onDetailedTokenStatsUpdated](/api-reference/subscriptions/ondetailedtokenstatsupdated): Live-streamed bucketed stats for a given token.
- [onBarsUpdated](/api-reference/subscriptions/onbarsupdated): Live-streamed bar chart data to track price changes over time.
- [onUnconfirmedBarsUpdated](/api-reference/subscriptions/onunconfirmedbarsupdated): Unconfirmed live-streamed bar chart data to track price changes over time. (Solana only)
- [onPairMetadataUpdated](/api-reference/subscriptions/onpairmetadataupdated): Live-streamed stat updates for a given token within a pair.
- [onDetailedStatsUpdated](/api-reference/subscriptions/ondetailedstatsupdated): Live-streamed bucketed stats for a given token within a pair.
- [onEventsCreated](/api-reference/subscriptions/oneventscreated): Live-streamed transactions for a token.
- [onEventsCreatedByMaker](/api-reference/subscriptions/oneventscreatedbymaker): Live-streamed transactions for a maker.
- [onUnconfirmedEventsCreated](/api-reference/subscriptions/onunconfirmedeventscreated): Live-streamed unconfirmed transactions for a token. (Solana only)
- [onUnconfirmedEventsCreatedByMaker](/api-reference/subscriptions/onunconfirmedeventscreatedbymaker): Live-streamed unconfirmed transactions for a maker. (Solana only)
- [onEventLabelCreated](/api-reference/subscriptions/oneventlabelcreated): Live-streamed event labels for a token.
- [onTokenEventsCreated](/api-reference/subscriptions/ontokeneventscreated): Live-streamed events for a given token across all it's pools
- [onTokenLifecycleEventsCreated](/api-reference/subscriptions/ontokenlifecycleeventscreated): Live-streamed token lifecycle events (mints and burns).
- [onLaunchpadTokenEventBatch](/api-reference/subscriptions/onlaunchpadtokeneventbatch): Live-streamed launchpad token events batched (more efficient).
- [onLaunchpadTokenEvent](/api-reference/subscriptions/onlaunchpadtokenevent): Live-streamed launchpad token event.
- [onHoldersUpdated](/api-reference/subscriptions/onholdersupdated): Live-streamed list of wallets that hold a given token. Also has the unique count of holders for that token.
- [onBalanceUpdated](/api-reference/subscriptions/onbalanceupdated): Live-streamed balance updates for a given wallet.
- [onPredictionTradesCreated](/api-reference/subscriptions/onpredictiontradescreated): Streams new prediction trades as they are ingested.
- [onDetailedPredictionMarketStatsUpdated](/api-reference/subscriptions/ondetailedpredictionmarketstatsupdated): Streams updated detailed stats for a specific prediction market.
- [onDetailedPredictionEventStatsUpdated](/api-reference/subscriptions/ondetailedpredictioneventstatsupdated): Streams updated detailed stats for a specific prediction event.
- [onPredictionMarketBarsUpdated](/api-reference/subscriptions/onpredictionmarketbarsupdated): Live-streamed bar chart data to track price changes over time for a prediction market.
- [onPredictionEventBarsUpdated](/api-reference/subscriptions/onpredictioneventbarsupdated): Live-streamed bar chart data to track price changes over time for a prediction event.

## API Mutations
- [backfillWalletAggregates](/api-reference/mutations/backfillwalletaggregates): Backfill wallet aggregates (trading stats) for a given wallet. This is the data used in the filterWallet/filterTokenWallets and detailedWalletStats queries.
- [createApiTokens](/api-reference/mutations/createapitokens): Create a new set of short-lived api access tokens
- [deleteApiToken](/api-reference/mutations/deleteapitoken): Delete a single short-lived api access token by id
- [refreshBalances](/api-reference/mutations/refreshbalances): Mutation operation
- [createWebhooks](/api-reference/mutations/createwebhooks): Create price, raw transaction, token/pair event, and NFT event webhooks.
- [deleteWebhooks](/api-reference/mutations/deletewebhooks): Delete multiple webhooks.

## Common Query Patterns

### Search tokens by name
```graphql
{ filterTokens(phrase: "$PEPE", rankings: {attribute: trendingScore24, direction: DESC}) { results { token { name symbol address } priceUSD liquidity volume24 } } }
```

### Get token price
```graphql
{ getTokenPrices(inputs: [{ address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c", networkId: 56 }]) { priceUsd address } }
```

### Get OHLCV bars
```graphql
{ getBars(symbol: "0x6982508145454ce325ddbe47a25d4ec3d2311933:1", from: 1700000000, to: 1700086400, resolution: "60") { t o h l c v } }
```

### Subscribe to live prices
```graphql
subscription { onPriceUpdated(address: "0x6982508145454ce325ddbe47a25d4ec3d2311933", networkId: 1) { priceUsd timestamp } }
```

### Get trending tokens
```graphql
{ filterTokens(filters: {network: 1, liquidity: {gt: 10000}}, rankings: {attribute: trendingScore24, direction: DESC}, limit: 25) { results { token { name symbol address } priceUSD volume24 trendingScore24 } } }
```

### List supported networks
```graphql
{ getNetworks { name id } }
```