Skip to main content

​
Websockets

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

Try it

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

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