Codex SDK

The TypeScript SDK for the Codex API — real-time blockchain data, token prices, OHLCV charts, wallet balances, and holder analytics for 60M+ tokens across 80+ networks including Ethereum, Solana, Base, Arbitrum, BSC, and Polygon.

Codex is a GraphQL API used by teams like Coinbase, TradingView, Uniswap, Rainbow, FOMO, Farcaster, and hundreds of others.

• Documentation
• Get an API Key
• GraphQL Explorer

Installation

npm install @codex-data/sdk

yarn add @codex-data/sdk

pnpm add @codex-data/sdk

Quick Start

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

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

const networks = await sdk.queries.getNetworks({});
console.log(networks.getNetworks); // [{ id: 1, name: "ethereum" }, { id: 1399811149, name: "solana" }, ...]

Get Token Prices

Get the current USD price of any token. Supports up to 25 tokens per request. Prices are liquidity-weighted across all valid pools.

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

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

const prices = await sdk.queries.getTokenPrices({
  inputs: [
    { address: "So11111111111111111111111111111111111111112", networkId: 1399811149 }, // SOL
    { address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", networkId: 1 },         // WETH
  ],
});

prices.getTokenPrices?.forEach((price) => {
  console.log(`${price?.address}: $${price?.priceUsd}`);
});

To get a historical price, pass a timestamp:

const historicalPrice = await sdk.queries.getTokenPrices({
  inputs: [
    {
      address: "So11111111111111111111111111111111111111112",
      networkId: 1399811149,
      timestamp: 1704067200, // Unix timestamp
    },
  ],
});

Get OHLCV Chart Data

Get candlestick data for any token or trading pair. Supports resolutions from 1-second to 7-day.

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

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

const bars = await sdk.queries.getBars({
  symbol: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1", // WETH on Ethereum
  from: 1704067200,
  to: 1704153600,
  resolution: "60", // 1-hour candles
  removeEmptyBars: true,
});

bars.getBars?.o?.forEach((open, i) => {
  console.log({
    open,
    high: bars.getBars?.h?.[i],
    low: bars.getBars?.l?.[i],
    close: bars.getBars?.c?.[i],
    volume: bars.getBars?.volume?.[i],
    timestamp: bars.getBars?.t?.[i],
  });
});

Available resolutions: 1S, 5S, 15S, 30S, 1, 5, 15, 30, 60, 240, 720, 1D, 7D

Discover and Filter Tokens

Search and filter tokens by price, volume, market cap, liquidity, holder count, trading activity, and more.

import { Codex, TokenRankingAttribute, RankingDirection } from "@codex-data/sdk";

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

const result = await sdk.queries.filterTokens({
  filters: {
    network: [1],                         // Ethereum
    liquidity: { gte: "100000" },         // $100k+ liquidity
    marketCap: { gte: "1000000" },        // $1M+ market cap
    txnCount24: { gte: "500" },           // 500+ transactions in 24h
  },
  rankings: [
    {
      attribute: TokenRankingAttribute.TrendingScore24,
      direction: RankingDirection.Desc,
    },
  ],
  limit: 20,
});

result.filterTokens?.results?.forEach((token) => {
  console.log(`${token?.token?.name} (${token?.token?.symbol}): $${token?.priceUSD}`);
});

Get Wallet Balances

Get all token balances for a wallet address with USD values.

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

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

const balances = await sdk.queries.balances({
  input: {
    walletAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", // vitalik.eth
    networks: [1],
    includeNative: true,
    removeScams: true,
    limit: 50,
  },
});

balances.balances?.items?.forEach((item) => {
  console.log(`${item?.token?.symbol}: ${item?.shiftedBalance} ($${item?.balanceUsd})`);
});

Get Token Holders

Get the list of wallets holding a specific token, sorted by balance.

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

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

const holders = await sdk.queries.holders({
  input: {
    tokenId: "So11111111111111111111111111111111111111112:1399811149", // SOL
    limit: 50,
  },
});

console.log(`Total holders: ${holders.holders?.count}`);
console.log(`Top 10 hold: ${holders.holders?.top10HoldersPercent}%`);

holders.holders?.items?.forEach((holder) => {
  console.log(`${holder?.address}: ${holder?.shiftedBalance} ($${holder?.balanceUsd})`);
});

Get Token Trade History

Get buy, sell, mint, and burn events for any token or pair.

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

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

const events = await sdk.queries.getTokenEvents({
  query: {
    address: "So11111111111111111111111111111111111111112",
    networkId: 1399811149,
    eventDisplayType: ["Buy", "Sell"],
  },
  limit: 25,
});

events.getTokenEvents?.items?.forEach((event) => {
  console.log(`${event?.eventDisplayType} by ${event?.maker} — $${event?.token0SwapValueUsd}`);
});

Stream Real-Time Prices

Note: WebSocket subscriptions require a paid plan.

Subscribe to live price updates via WebSocket. Fires on every on-chain swap.

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

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

const unsubscribe = sdk.subscriptions.onPriceUpdated(
  {
    address: "So11111111111111111111111111111111111111112",
    networkId: 1399811149,
  },
  {
    next: (result) => {
      console.log("Price:", result.data?.onPriceUpdated?.priceUsd);
    },
    error: (err) => console.error(err),
    complete: () => console.log("Stream ended"),
  },
);

// Call unsubscribe() to clean up

Stream Real-Time OHLCV Bars

Note: WebSocket subscriptions require a paid plan.

Get live candlestick updates across all resolutions simultaneously.

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

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

const unsubscribe = sdk.subscriptions.onBarsUpdated(
  {
    pairId: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:1", // USDC/WETH on Ethereum
    quoteToken: QuoteToken.Token1,
  },
  {
    next: (result) => {
      const bar = result.data?.onBarsUpdated;
      const oneMin = bar?.aggregates?.r1?.usd;
      console.log(`1min candle — O: ${oneMin?.o} H: ${oneMin?.h} L: ${oneMin?.l} C: ${oneMin?.c}`);
    },
    error: (err) => console.error(err),
    complete: () => console.log("Stream ended"),
  },
);

Stream Live Trades

Note: WebSocket subscriptions require a paid plan.

Watch buy/sell events as they happen on any trading pair.

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

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

const unsubscribe = sdk.subscriptions.onEventsCreated(
  {
    id: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:1",
    quoteToken: QuoteToken.Token0,
  },
  {
    next: (result) => {
      result.data?.onEventsCreated?.events?.forEach((event) => {
        console.log(`${event?.eventDisplayType} by ${event?.maker} — $${event?.token0SwapValueUsd}`);
      });
    },
    error: (err) => console.error(err),
    complete: () => console.log("Stream ended"),
  },
);

Raw GraphQL Queries

Use sdk.send() to execute any GraphQL query directly.

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

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

const result = await sdk.send<{
  getNetworks: Array<{ id: number; name: string }>;
}>(
  `query GetNetworks {
    getNetworks { id name }
  }`,
  {},
);

console.log("Networks:", result.getNetworks);

Common Network IDs

| Network | ID | | --- | --- | | Ethereum | 1 | | BSC | 56 | | Polygon | 137 | | Arbitrum | 42161 | | Base | 8453 | | Avalanche | 43114 | | Solana | 1399811149 |

Use sdk.queries.getNetworks({}) for the full list of 80+ supported networks.

ID Format Convention

IDs in the Codex API follow the pattern address:networkId:

• Token ID: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2:1 (WETH on Ethereum)
• Pair ID: 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640:1 (USDC/WETH on Ethereum)
• Wallet ID: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045:1

All Available Methods

Queries (sdk.queries.*)

| Method | Description | | --- | --- | | filterTokens | Search and filter tokens by price, volume, market cap, liquidity | | getTokenPrices | Get current or historical USD prices for up to 25 tokens | | getBars | Get OHLCV candlestick data for a trading pair | | holders | Get token holder list sorted by balance (paid) | | filterPairs | Search and filter trading pairs | | balances | Get wallet token balances with USD values (paid) | | getTokenEvents | Get buy/sell/mint/burn trade events | | pairMetadata | Get trading pair stats and metadata | | token | Get metadata for a single token | | listPairsWithMetadataForToken | List pairs with full metadata | | getTokenEventsForMaker | Get trade events for a specific wallet | | getDetailedPairStats | Get detailed bucketed stats for a pair | | listPairsForToken | List all trading pairs for a token | | tokenTopTraders | Get top traders for a token | | tokens | Get metadata for multiple tokens | | top10HoldersPercent | Get percentage held by top 10 wallets | | getDetailedPairsStats | Get detailed stats for multiple pairs | | filterTokenWallets | Get per-wallet trading stats (profit/loss, buy/sell counts) (paid) | | liquidityMetadata | Get liquidity pool metadata (paid) | | tokenSparklines | Get sparkline price data for tokens | | filterWallets | Filter wallets by trading statistics (paid) | | detailedWalletStats | Get comprehensive wallet analytics (paid) | | getExchanges | Get DEX information | | getNetworks | List all 80+ supported networks | | getTokenBars | Get OHLCV data for a token across all pairs | | chartUrls | Get pre-rendered chart image URLs (paid) | | walletChart | Get wallet portfolio chart data (paid) | | filterExchanges | Filter decentralized exchanges | | liquidityLocks | Get liquidity lock information (paid) | | getNetworkConfigs | Get network configuration details | | getNetworkStats | Get network-level statistics | | getNetworkStatus | Get network sync status | | tokenLifecycleEvents | Get token creation and migration events | | blocks | Get block data by number or timestamp |

Subscriptions (sdk.subscriptions.*) — paid plan required

| Method | Description | | --- | --- | | onPairMetadataUpdated | Live pair stat updates | | onLaunchpadTokenEventBatch | Batched launchpad events | | onBarsUpdated | Real-time OHLCV bars for a trading pair | | onPriceUpdated | Real-time price for a single token | | onHoldersUpdated | Live holder count and balance changes | | onDetailedStatsUpdated | Live detailed stats updates | | onDetailedTokenStatsUpdated | Live detailed token stats aggregated across pools | | onEventsCreated | Live buy/sell events for a pair | | onPricesUpdated | Real-time prices for multiple tokens | | onUnconfirmedEventsCreated | Unconfirmed (mempool) trade events | | onTokenEventsCreated | Live events across all pools for a token | | onLaunchpadTokenEvent | Individual launchpad events (Pump.fun, etc.) | | onTokenBarsUpdated | Real-time OHLCV bars for a token | | onLatestPairUpdated | New trading pair creation events | | onUnconfirmedBarsUpdated | Unconfirmed bar updates | | onEventsCreatedByMaker | Live events for a specific wallet | | onBalanceUpdated | Live wallet balance updates | | onTokenLifecycleEventsCreated | Token lifecycle events | | onLatestTokens | New token creation events | | onNftEventsCreated | NFT trade events |

Mutations (sdk.mutations.*)

| Method | Description | | --- | --- | | createWebhooks | Create webhook alerts (paid) | | deleteWebhooks | Delete webhook alerts (paid) | | backfillWalletAggregates | Trigger wallet data backfill (paid) | | createApiTokens | Create short-lived API tokens for client-side use (paid) | | deleteApiToken | Delete an API token (paid) | | refreshBalances | Refresh wallet balances |

Configuration

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

const sdk = new Codex("YOUR_API_KEY", {
  apiUrl: "https://graph.codex.io/graphql",         // default
  apiRealtimeUrl: "wss://graph.codex.io/graphql",   // default
  ws: true,                                          // enable WebSocket (default: true)
});

// Update config at runtime
sdk.updateConfig({ ws: false });

// Clean up WebSocket connection
sdk.dispose();

Examples

See the examples directory for full working projects:

• Simple — Basic queries, filtering, and subscriptions
• Codegen — Using GraphQL Code Generator for fully typed custom queries
• Next.js — Full-stack web application

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

pnpm install    # Install dependencies
pnpm run build  # Build the SDK
pnpm run test   # Run tests
pnpm run lint   # Lint the codebase

Releasing

On a branch, make your changes then:

• pnpm run build
• change package.json version accordingly
• merge to main
• create a github release with the same tag as the version in package.json

Upgrading to v2

See UPGRADING.md for migration instructions from v1 to v2.

Links

• Codex API Documentation
• Popular Endpoints
• GraphQL Explorer
• Get an API Key
• Codex MCP Server
• Discord
• Twitter

License

MIT