Skip to main content
Subscriptions (WebSockets) require a Growth or Enterprise plan. Learn more.

​
What is a Subscription?

A subscription is a persistent connection that pushes data to you in real-time. Instead of repeatedly polling the API for updates, you open a WebSocket connection and tell Codex what data you want to watch. Whenever that data changes, Codex sends you the update automatically. Every message the subscription sends you counts as 1 request against your plan’s monthly limit. For example, if you subscribe to price updates for a token and receive 1,000 updates in an hour, that’s 1,000 requests.
Not sure whether to use a query or a subscription? See Queries vs Subscriptions for a side-by-side comparison and endpoint mapping.

​
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
If you only need data once (e.g. loading a page, fetching historical data, or responding to a user action), use Queries instead.

​
How It Works

Subscriptions use the WebSocket protocol. You open a connection to wss://graph.codex.io/graphql, authenticate via the connection_init payload, and then send subscribe messages for the data you want.

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.
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,
})
We use the graphql-ws library to handle websocket connections on the backend, you can learn more about it here .
Websocket handshake

​
Example

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");
    },
  }
})
You can refer to this datafeed example using the SDK for onTokenBarsUpdated to get you started with a chart rendering subscription.

​
Multiple Subscriptions

You can subscribe multiple times in the same connection, just send additional subscribe messages.
The maximum number of subscriptions you can have open concurrently before the socket is overloaded depends on many factors, but generally we recommend ~25 subscriptions per connection should be fine, though there is no predetermined “hard limit”. Be aware that there could be data dropped if there are too many updates pushed through the WebSocket. Reliability depends on:
  • 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 subscriptions and how many tokens you are subscribed to in each. For example, with subscriptions such as onPricesUpdated you could subscribe to 25 tokens per subscription, but have multiple subscriptions on 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)
If you’re subscribing to lower throughput subscriptions, then you could easily have upwards of 100 at once, but you would want to monitor this closely.

​
Connection Management

Connection Persistence:
  • 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
Reducing Usage for Idle Users: Implement client-side idle detection to pause subscriptions when users are inactive:
  • 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
Best Practices:
  • 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
Ensure you close subscriptions if you no longer want them to run. Deactivating an API key will still permit active subscriptions to remain open until they are disconnected or otherwise require reconnection.