> ## 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.

# onTokenBarsUpdated

> Live-streamed aggregate bar chart data to track price changes over time for a token. onTokenBarsUpdated subscription reference: arguments and payload fields.

> **Confirmed vs. unconfirmed events:** Use the `commitmentLevel` argument to choose which events you receive.
>
> * `confirmed` — receive events only after they're confirmed on-chain. This is the default if `commitmentLevel` is not specified.
> * `processed`: receive events as soon as they're observed on-chain (unconfirmed; may be reorged out). You must explicitly set `commitmentLevel: processed` to opt in. **Currently available on Solana, Base, and Robinhood.**
>
> For the fastest `processed` data, connect to an [edge node](https://docs.codex.io/concepts/edge-nodes.md).

## GraphQL

```
type Subscription {
  # Requires a Growth or Enterprise plan.
  onTokenBarsUpdated(
    tokenId: String
    commitmentLevel: [BarCommitmentLevel!]
    statsType: TokenPairStatisticsType
    networkId: Int
  ): OnTokenBarsUpdatedResponse
}

enum BarCommitmentLevel {
  Processed
  Confirmed
}

enum TokenPairStatisticsType {
  FILTERED
  UNFILTERED
}

type IndividualBarData {
  o: Float!
  h: Float!
  l: Float!
  c: Float!
  v: Int
  t: Int!
  volume: String!
  volumeNativeToken: String!
  buyers: Int!
  buys: Int!
  buyVolume: String!
  sellers: Int!
  sells: Int!
  sellVolume: String!
  liquidity: String!
  traders: Int!
  transactions: Int!
  poolFees: String
  baseFees: String
  priorityFees: String
  builderTips: String
  l1DataFees: String
}

type CurrencyBarData {
  t: Int!
  usd: IndividualBarData!
  token: IndividualBarData!
}

type ResolutionBarData {
  r1S: CurrencyBarData
  r5S: CurrencyBarData
  r15S: CurrencyBarData
  r30S: CurrencyBarData
  r1: CurrencyBarData
  r5: CurrencyBarData
  r15: CurrencyBarData
  r30: CurrencyBarData
  r60: CurrencyBarData
  r240: CurrencyBarData
  r720: CurrencyBarData
  r1D: CurrencyBarData
  r7D: CurrencyBarData
}

enum QuoteToken {
  token0
  token1
}

type OnTokenBarsUpdatedResponse {
  commitmentLevel: BarCommitmentLevel!
  networkId: Int!
  timestamp: Int!
  statsType: TokenPairStatisticsType!
  eventSortKey: String!
  aggregates: ResolutionBarData!
  tokenAddress: String!
  tokenId: String!
}
```

This is the live-streamed subscription version of our [getTokenBars](https://docs.codex.io/api-reference/queries/gettokenbars.md) aggregated chart data endpoint.

> [!NOTE]
>
> Pricing for aggregate charts will no longer only use the top pair. Weighted average pricing will be used across a token's top pairs, based on liquidity/recency, while filtering out lower quality pairs from contributing.

> [!NOTE]
>
> **Network-wide bar streams (BarFeed)**: `onTokenBarsUpdated` can also stream aggregated bars for **every token on a network** by passing `networkId` and omitting `tokenId`, so you do not need to know token addresses in advance. This capability isn't part of standard plans — it's a dedicated add-on billed at a flat monthly rate per network rather than per request, and it must be enabled before use. The BarFeed entitlement is attached to **specific API keys**, not to your account as a whole: a key without the entitlement still requires `tokenId` and returns `arguments: tokenId required on field: onTokenBarsUpdated but missing`. If you need it on more than one key, ask us to enable each key. Contact us at [hello@codex.io](mailto:hello@codex.io?subject=Network-wide%20Bar%20Updates) or on [Telegram](https://t.me/CodexData) to get set up.

### Example

[Test this query in the Explorer →](https://docs.codex.io/explore.md)

```graphql theme={null}
subscription {
  onTokenBarsUpdated(
    tokenId: "So11111111111111111111111111111111111111112:1399811149"
  ) {
    tokenAddress
    tokenId
    networkId
    timestamp
    statsType
    eventSortKey
    aggregates {
      r1 {
        t
        usd {
          t
          o
          h
          l
          c
          v
          volume
          buyers
          sellers
          buys
          sells
          buyVolume
          sellVolume
          liquidity
          transactions
        }
      }
      r5 {
        t
        usd {
          t
          o
          h
          l
          c
          v
        }
      }
      r60 {
        t
        usd {
          t
          o
          h
          l
          c
          v
        }
      }
    }
  }
}
```

```json Example Response theme={null}
{
  "data": {
    "onTokenBarsUpdated": {
      "tokenAddress": "So11111111111111111111111111111111111111112",
      "tokenId": "So11111111111111111111111111111111111111112:1399811149",
      "networkId": 1399811149,
      "timestamp": 1769563445,
      "quoteToken": null,
      "statsType": "FILTERED",
      "eventSortKey": "0000000396381322#00001195#00000002#00000010",
      "aggregates": {
        "r1": {
          "t": 1769563440,
          "usd": {
            "t": 1769563440,
            "o": 127.012034416,
            "h": 127.016839607,
            "l": 127.009237799,
            "c": 127.014855249,
            "v": null,
            "volume": "469721.0884137",
            "buyers": 749,
            "sellers": 927,
            "buys": 996,
            "sells": 1203,
            "buyVolume": "225517.7527296",
            "sellVolume": "244203.3356831",
            "liquidity": "1172794156.1",
            "transactions": 2200
          }
        },
        "r5": {
          "t": 1769563200,
          "usd": {
            "t": 1769563200,
            "o": 127.055827666,
            "h": 127.112302294,
            "l": 126.852901585,
            "c": 127.014855249,
            "v": null
          }
        },
        "r60": {
          "t": 1769562000,
          "usd": {
            "t": 1769562000,
            "o": 127.070132344,
            "h": 127.344587246,
            "l": 126.852901585,
            "c": 127.014855249,
            "v": null
          }
        }
      }
    }
  }
}
```

### Usage Guidelines

* Subscribe using `tokenId` in the format `tokenAddress:networkId` to stream aggregate bar data for a token
* With the BarFeed add-on enabled on your API key, pass `networkId` (and omit `tokenId`) to stream bars for every token on that network. Only the resolutions you request are returned, so keep the selection small (for example `r5S`) on a network-wide stream
* Unlike `onBarsUpdated` (which tracks a single pair), this subscription aggregates pricing across a token's top liquidity pairs using weighted averages
* `aggregates` contains OHLCV bar data across multiple resolutions simultaneously (e.g., `r1` for 1-minute, `r5` for 5-minute, `r60` for 1-hour)
* Each resolution provides both `usd` (USD-denominated) and `token` (native token-denominated) bars via `CurrencyBarData`
* Granular trade metrics like `buyers`, `sellers`, `buyVolume`, `sellVolume`, and `liquidity` are available per bar
* The default `statsType` is `FILTERED`, which excludes bot and sandwich attack transactions
* Use the `volume` string field for precise volume data — the `v` integer field may be `null` for aggregate token bars

### Troubleshooting Tips

> [accordion] How does this differ from onBarsUpdated?
>
> `onBarsUpdated` streams bar data for a single trading pair. `onTokenBarsUpdated` aggregates pricing across a token's top liquidity pairs using weighted averages based on liquidity and recency, filtering out lower-quality pairs. Use `onTokenBarsUpdated` for a holistic view of a token's price, and `onBarsUpdated` when you need data for a specific pair.

> [accordion] What resolutions are available?
>
> Resolutions range from 1-second (`r1S`) up to 1-week (`r7D`): `r1S`, `r5S`, `r15S`, `r30S`, `r1` (1 min), `r5`, `r15`, `r30`, `r60`, `r240` (4h), `r720` (12h), `r1D`, `r7D`. You only need to request the resolutions you need in your query.

> [accordion] Why is the v field null?
>
> The `v` integer field may be `null` for aggregate token bars. Use the `volume` string field instead, which provides precise volume data as a string to avoid floating-point precision issues.

> [accordion] Why do I get 'tokenId required' when subscribing by networkId?
>
> Network-wide bar streams require the BarFeed entitlement, which is enabled per API key rather than per account. If one of your keys works and another returns `arguments: tokenId required on field: onTokenBarsUpdated but missing`, the second key does not have the entitlement. Contact [hello@codex.io](mailto:hello@codex.io?subject=Network-wide%20Bar%20Updates) to enable it on additional keys. The same applies to the network-wide `onPriceUpdated` stream (PriceFeed).

> [accordion] What does statsType: Filtered vs Unfiltered mean?
>
> `Filtered` excludes suspected bot and sandwich attack transactions for cleaner price data. `Unfiltered` includes all transactions. Most charting use cases should use `Filtered` for more accurate price representation.

### Related Recipes

* [Detailed Token Page](https://docs.codex.io/recipes/detailed-token-page.md): Build a comprehensive token detail page with price, holders, trades, and real-time updates
* [Charts](https://docs.codex.io/recipes/charts.md): Render token charts with OHLCV data and real-time updates


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.