Subscriptions

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.

​

What is a Subscription?

​

When to Use Subscriptions

• Live price feeds — streaming token or pair prices as they change
• Real-time trade notifications — watching for new swaps, mints, or burns as they happen
• Streaming chart updates — keeping OHLCV bars current without polling
• Launchpad monitoring — detecting new token launches and graduation events instantly
• Live holder/balance tracking — watching holder counts or wallet balances update in real-time

​

How It Works

Try it

This subscription uses your account’s monthly request limit while active. Stop the subscription when you’re done testing to conserve your limit.

SDK

If you’re using the SDK, then you can just call sdk.subscribe with the subscription you want to use and it will handle the connections.

onPriceUpdated

sdk.subscribe(gql`
  subscription($address: String!, $networkId: Int!) {
    onPriceUpdated(address: $address, networkId: $networkId) {
      priceUsd
      timestamp
      address
    }
  }
`, {
  address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
  networkId: 56,
})

Custom

We use the graphql-ws library to handle websocket connections on the backend, you can learn more about it here .

​

Example

graphql-ws

browser socket

import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://graph.codex.io/graphql",
  connectionParams: {
    Authorization: apiKey,
  },
});

client.subscribe({
  query: `
    subscription($address: String!, $networkId: Int!) {
      onPriceUpdated(address: $address, networkId: $networkId) {
        priceUsd
        timestamp
        address
      }
    }
  `,
  variables: {
    address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
    networkId: 56,
  },
  sink: {
    next: (data) => {
      console.log(data);
    },
    error: (error) => {
      console.error(error);
    },
    complete: () => {
      console.log("complete");
    },
  }
})

​

Multiple Subscriptions

• Throughput of the subscriptions. If you are subscribed to onTokenEventsCreated to the SOL token, then you’re going to get a lot more messages than a token with no volume.
• The number of tokens you’re watching across all subscriptions on a connection. onPricesUpdated accepts up to 25 tokens per subscription as a hard input cap — that’s an API limit on each call, not a recommendation on connection density. You can run several onPricesUpdated subscriptions on the same connection, just account for the combined token count when sizing the connection.
• Your internet connection, the amount of network capacity matters if you’re making a lot of subscriptions.
• Geography (how close is your application to Western US)

​

Connection Management

• WebSocket connections remain open indefinitely with no automatic server-side disconnection
• Connections require heartbeat messages to stay alive (handled automatically if using our SDK)
• Growth plans are limited to 300 connections. For Enterprise accounts, there isn’t a defined “hard-limit”, however, please contact our team if you have questions about your number of required connections. As each connection can handle multiple subscriptions, our “soft-limit” of connections is rarely reached by our customers.
• No time-based limits on how long subscriptions can run

• Use idle detection hooks (e.g.https://usehooks.com/useidle )
• Pause subscriptions after ‘N’ minutes of inactivity
• Resume when user becomes active again
• This prevents burning through API usage from idle browser tabs

• Implement multiple subscriptions per connection (more reliable, easier to manage)
• Exception: High-volume subscriptions like launchpad events should use dedicated connections
• Proxy data through your backend to serve multiple users from a single subscription
  • Example: 10 users viewing the same chart = 1 subscription, instead of 10

​

FAQ