Subscriptions

Websockets

For websockets, you use the Authorization connection parameter when sending the connection_init payload.

Try it

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 .

note: you must wait for connection_ack before sending any messages

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");
    },
  }
})

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 ~25 subscriptions per connection should be fine. It 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.
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.

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

First steps

Concepts

Recipes

Resources

Subscriptions

Websockets

Example

Multiple Subscriptions

Connection Management

First steps

Concepts

Recipes

Resources

​Websockets

​Multiple Subscriptions

​Connection Management

Websockets

Multiple Subscriptions

Connection Management