What is a Subscription?

Subscription is defined by the subscription type of GraphQL request:

subscription {
  eth: EVM(network: eth) {
  ...
  }
}

Almost any query can be converted to a subscription just by replacing the query type with subscription. Trading cube queries are the main exception — see What does not survive streaming.

Streaming token trades or prices? Use the Trading API

If your subscription is a DEXTrades / DEXTradeByTokens stream filtered to specific tokens just to get live trades or prices, use the Trading API (Trading.Trades, Trading.Tokens, Trading.Pairs, Trading.Currencies) instead. It covers 9 chains in one stream, has USD price, market cap, and supply on every row, is MEV/outlier-filtered, and ships pre-aggregated OHLC down to 1-second candles — so you stream far fewer rows for the same signal. See the Trading Data Overview for when to use which.

When creating queries for GraphQL subscriptions, here are some tips to consider:

1. Avoid Limiting Results: In most cases, you should avoid limiting the results of your subscription query. This is because subscriptions are meant to stream data in real-time and limiting the results could cause you to miss out on new data.

2. Ordering Might Not Be Necessary: Given that subscriptions are meant to provide real-time data, ordering might not be necessary or even meaningful since data is sent as it becomes available.

3. Test Your Queries: Before deploying your application, make sure to thoroughly test your subscription queries to ensure they return the data you expect and can handle high volumes of data.

4. Modifying Subscriptions Does Not Work: If you try to modify a running subscription, it will end the subscription.

In addition, optimizing your queries can significantly enhance the performance of your subscriptions. For more insights on how to optimize your websocket queries, go here.

Subscriptions are also priced using our point-based system. Read about it here

Default Parameters (GraphQL v2)

GraphQL v2 applies the following default to subscriptions. You can override it by specifying a different value explicitly in your GraphQL filters.

Parameter	Default value
Subscription limit	800 (per message)

Each subscription message returns at most 800 items by default. Override this by specifying a different limit in your subscription filters if you need a different batch size.

For default success and other filters (e.g. only successful transactions, calls, events, transfers, DEX trades; Trade API defaults), see Default filters (GraphQL v2) in Query Principles. For default limits on queries, see Limits.

Creating Multiple Subscriptions in one Websocket

It is possible—and often more efficient—to manage multiple subscriptions over a single WebSocket connection. This approach allows you to bundle various subscriptions, such as DEX Trades, Transactions, Blocks, and Transfers, into a single Websocket stream. However, it's important to note that your top-level element must be only one.

subscription{
  EVM{
    Transfers{

    }
    Transactions{

    }
  }
}

Example: Tracking USDT Transfers on Ethereum

In this graphQL stream, we see how to run multiple streams with a single WebSocket.

This query will return two sets of transfer data for USDT on the Ethereum network: transfers_above_10K and transfers_below_10K. The transfers_above_10K data set includes all transfers with an amount greater than or equal to 10,000 USDT. The transfers_below_10K data set includes all transfers with an amount less than 10,000 USDT. Both data sets include the transaction hash, sender, receiver, and amount of each transfer.

You can run the query here

subscription ($token: String!, $minamount: String!, $mempool: Boolean, $network: evm_network!) {
  usdt: EVM(network: $network, mempool: $mempool) {
    transfers_above_10K: Transfers(
      where: {Transfer: {Amount: {ge: $minamount}, Currency: {SmartContract: {is: $token}}}}
    ) {
      Transaction {
        Hash
        From
        Gas
      }
      Receipt {
        GasUsed
      }
      Transfer {
        Sender
        Receiver
        Amount
      }
    }
    transfers_below_10K: Transfers(
      where: {Transfer: {Amount: {lt: $minamount}, Currency: {SmartContract: {is: $token}}}}
    ) {
      Transaction {
        Hash
        From
        Gas
      }
      Receipt {
        GasUsed
      }
      Transfer {
        Sender
        Receiver
        Amount
      }
    }
  }
}
{
  "token": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "minamount": "10000",
  "mempool": true,
  "network": "eth"
}