examples

Codex SDK Examples

This directory contains comprehensive examples demonstrating how to use the Codex SDK in various scenarios. Each example is self-contained and showcases different aspects of the SDK functionality.

Prerequisites

• Node.js >= 17.5.0
• pnpm (recommended)
• A Codex API key from docs.codex.io

Quick Start

1. Install dependencies (from the root directory):

   pnpm install

2. Set your API key:

   export CODEX_API_KEY="your_api_key_here"

3. Run any example:

   cd examples/simple
   pnpm run dev

Examples Directory

📁 simple/

Basic SDK Usage Examples

A collection of focused examples demonstrating core SDK functionality:

File	Description	Key Features
index.ts	Complete SDK overview	Queries, mutations, subscriptions, webhooks
token.ts	Token data queries	Custom headers, GraphQL queries
filterTest.ts	Token filtering	Advanced filtering, liquidity checks
realtime.ts	Real-time price updates	WebSocket subscriptions, custom sink
simpleSubscription.ts	Basic subscriptions	Built-in subscription methods
apiKeys.ts	API token management	Token creation, short-lived tokens
apiKeysSubscription.ts	Token + subscriptions	Token auth with real-time data
updateConfig.ts	Dynamic configuration	Runtime config updates
profile.ts	Event profiling	Unconfirmed events, timing analysis
auto.ts	Automated queries	Simple token lookups

Usage:

cd examples/simple
pnpm run dev                    # Run index.ts
tsx token.ts                    # Run specific example
CODEX_API_KEY=xyz tsx auto.ts   # With inline API key

📁 codegen/

GraphQL Code Generation

Shows how to use GraphQL Code Generator for fully typed queries and mutations.

Features:

• Type-safe GraphQL operations
• Generated TypeScript types
• Custom document nodes
• Full IntelliSense support

Usage:

cd examples/codegen
pnpm run codegen    # Generate types
pnpm run dev        # Run example

Key Files:

• codegen.ts - Code generation configuration
• src/index.ts - Typed query example
• src/gql/ - Generated types and utilities

📁 next/

Next.js Integration

A complete Next.js application demonstrating SDK usage in a React environment.

Features:

• Server-side rendering with SDK
• Client-side data fetching
• Real-time updates
• Modern UI components
• Network and token exploration

Usage:

cd examples/next
pnpm run dev    # Start development server
pnpm run build  # Build for production

Key Features:

• 🌐 Network browsing
• 🪙 Token exploration
• 📊 Price charts
• 🔄 Real-time updates
• 📱 Responsive design

TypeScript Support

The Codex SDK provides full TypeScript support with generated types for all GraphQL operations:

import {
  Codex,
  TokenQuery,
  OnPriceUpdatedSubscription,
  CreateWebhooksMutation,
} from "@codex-data/sdk";

// All operations are fully typed
const token: TokenQuery = await sdk.queries.token({
  input: { address, networkId },
});

Available Type Categories

• Query Types: TokenQuery, GetNetworksQuery, etc.
• Mutation Types: CreateWebhooksMutation, DeleteWebhooksMutation, etc.
• Subscription Types: OnPriceUpdatedSubscription, OnTokenEventsCreatedSubscription, etc.
• Input Types: TokenInput, CreateWebhooksInput, etc.
• Scalar Types: All GraphQL scalars and custom types

Common Patterns

Basic Query

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

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

const token = await sdk.queries.token({
  input: {
    address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
    networkId: 56,
  },
});

Real-time Subscription

sdk.subscriptions.onPriceUpdated(
  {
    address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
    networkId: 56,
  },
  {
    next: (data) => console.log("Price update:", data),
    error: (err) => console.error("Error:", err),
    complete: () => console.log("Subscription complete"),
  },
);

Custom GraphQL Query

Custom queries let you request only the fields you need — you're billed for the fields your query requests, so this is the recommended pattern for production. Wrap the SDK's exported query types in DeepPartial so the compiler stays honest about fields your query didn't select:

import { DeepPartial, GetNetworksQuery } from "@codex-data/sdk";

const result = await sdk.send<DeepPartial<GetNetworksQuery>>(
  `query GetNetworks { getNetworks { id name } }`,
  {},
);

For exact types inferred from your query (no DeepPartial needed), see the codegen example.

Mutation Example

const webhook = await sdk.mutations.createWebhooks({
  input: {
    priceWebhooksInput: {
      webhooks: [
        {
          name: "Price Alert",
          callbackUrl: "https://your-webhook-url.com",
          conditions: {
            priceUsd: { gt: "100" },
            networkId: { eq: 1 },
          },
        },
      ],
    },
  },
});

Environment Variables

All examples support these environment variables:

Variable	Description	Default
CODEX_API_KEY	Your Codex API key	Required
CODEX_API_URL	Custom API endpoint	https://graph.codex.io/graphql
CODEX_WS_URL	Custom WebSocket endpoint	wss://graph.codex.io/graphql

Development Scripts

Each example directory includes these scripts:

• pnpm run dev - Run the main example file
• pnpm run codegen - Generate GraphQL types (codegen example only)
• pnpm run build - Build for production (Next.js example only)

Tips & Best Practices

🔑 API Key Management

• Store API keys in environment variables
• Use .env.local files for local development
• Never commit API keys to version control

🚀 Performance

• Use subscriptions for real-time data
• Implement proper error handling
• Consider rate limiting for production use

🛠 Development

• Use TypeScript for better development experience
• Leverage code generation for type safety
• Test with different network configurations

🔄 Real-time Data

• Handle subscription lifecycle properly
• Implement reconnection logic for production
• Use appropriate cleanup mechanisms

Troubleshooting

Common Issues

"API key not found"

export CODEX_API_KEY="your_api_key_here"

"Module not found"

pnpm install  # From project root

"WebSocket connection failed"

• Check your network connection
• Verify WebSocket URL is correct
• Ensure API key has subscription permissions

Getting Help

• 📖 Official Documentation
• 🐛 Report Issues
• 💬 Community Support

Contributing

Found a bug or want to add an example? We welcome contributions!

1. Fork the repository
2. Create your feature branch
3. Add your example with proper documentation
4. Submit a pull request

---

Happy coding with Codex SDK! 🚀