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

# onDetailedTokenStatsUpdated

> Live-streamed bucketed stats for a given token.

<div data-generated>
  ## GraphQL

  ```
  type Subscription {
    # Requires a Growth or Enterprise plan.
    onDetailedTokenStatsUpdated(
      tokenId: String
      statsType: TokenPairStatisticsType
    ): DetailedTokenStats
  }

  enum TokenPairStatisticsType {
    FILTERED
    UNFILTERED
  }

  enum DetailedTokenStatsDuration {
    day30
    week1
    day1
    hour12
    hour4
    hour1
    min15
    min5
  }

  type DetailedPairStatsBucketTimestamp {
    start: Int!
    end: Int!
  }

  type DetailedPairStatsStringMetrics {
    change: Float
    currentValue: String
    previousValue: String
    buckets: [String]!
  }

  type WindowedDetailedCurrencyPairStats {
    volume: DetailedPairStatsStringMetrics
    buyVolume: DetailedPairStatsStringMetrics
    sellVolume: DetailedPairStatsStringMetrics
    open: DetailedPairStatsStringMetrics
    highest: DetailedPairStatsStringMetrics
    lowest: DetailedPairStatsStringMetrics
    close: DetailedPairStatsStringMetrics
    liquidity: DetailedPairStatsStringMetrics
  }

  type DetailedPairStatsNumberMetrics {
    change: Float
    currentValue: Int
    previousValue: Int
    buckets: [Int]!
  }

  type WindowedDetailedNonCurrencyPairStats {
    transactions: DetailedPairStatsNumberMetrics
    buys: DetailedPairStatsNumberMetrics
    sells: DetailedPairStatsNumberMetrics
    traders: DetailedPairStatsNumberMetrics
    buyers: DetailedPairStatsNumberMetrics
    sellers: DetailedPairStatsNumberMetrics
  }

  type WindowedDetailedTokenStats {
    duration: DetailedTokenStatsDuration!
    start: Int!
    end: Int!
    timestamps: [DetailedPairStatsBucketTimestamp]!
    statsUsd: WindowedDetailedCurrencyPairStats!
    statsNonCurrency: WindowedDetailedNonCurrencyPairStats!
  }

  type DetailedTokenStats {
    tokenId: String!
    tokenAddress: String!
    networkId: Int!
    lastTransactionAt: Int
    statsType: TokenPairStatisticsType!
    stats_min5: WindowedDetailedTokenStats
    stats_hour1: WindowedDetailedTokenStats
    stats_hour4: WindowedDetailedTokenStats
    stats_hour12: WindowedDetailedTokenStats
    stats_day1: WindowedDetailedTokenStats
    bucketCount: Int
    queryTimestamp: Int
  }
  ```
</div>

This is the live-streamed subscription version of our [getDetailedTokenStats](/api-reference/queries/getdetailedtokenstats) query. Subscribe to receive aggregated token statistics across specified time periods.

### Example

<a href="/explore" target="_blank" rel="noopener noreferrer">Test this query in the Explorer →</a>

```graphql theme={null}
subscription {
  onDetailedTokenStatsUpdated(
    tokenId: "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump:1399811149"
  ) {
    networkId
    statsType
    lastTransactionAt
    stats_hour1 {
      duration
      start
      end
      statsUsd {
        volume { currentValue previousValue change }
        buyVolume { currentValue previousValue change }
        sellVolume { currentValue previousValue change }
        close { currentValue previousValue change }
        liquidity { currentValue previousValue change }
      }
      statsNonCurrency {
        transactions { currentValue previousValue change }
        buyers { currentValue previousValue change }
        sellers { currentValue previousValue change }
      }
    }
    stats_day1 {
      duration
      start
      end
      statsUsd {
        volume { currentValue previousValue change }
      }
      statsNonCurrency {
        transactions { currentValue previousValue change }
        traders { currentValue previousValue change }
      }
    }
  }
}
```

```json Example Response expandable theme={null}
{
  "data": {
    "onDetailedTokenStatsUpdated": {
      "networkId": 1399811149,
      "statsType": "UNFILTERED",
      "lastTransactionAt": 1776984285,
      "stats_hour1": {
        "duration": "hour1",
        "start": 1776980685,
        "end": 1776984286,
        "statsUsd": {
          "volume": {
            "currentValue": "265748.10827470712163",
            "previousValue": "244878.07126917266842",
            "change": 0.08522623890888899
          },
          "buyVolume": {
            "currentValue": "144528.01349863471001",
            "previousValue": "189502.71839593273572",
            "change": -0.23733013055428184
          },
          "sellVolume": {
            "currentValue": "121220.09477711560805",
            "previousValue": "55375.35287204386872",
            "change": 1.1890622540540652
          },
          "close": {
            "currentValue": "0.201000590004",
            "previousValue": "0.200065560622",
            "change": 0.004673614884505917
          },
          "liquidity": {
            "currentValue": "5922753.22554",
            "previousValue": "5915693.52645",
            "change": 0.0011933848598537045
          }
        },
        "statsNonCurrency": {
          "transactions": { "currentValue": 2678, "previousValue": 2514, "change": 0.06523468575974542 },
          "buyers": { "currentValue": 216, "previousValue": 216, "change": 0 },
          "sellers": { "currentValue": 207, "previousValue": 195, "change": 0.06153846153846154 }
        }
      },
      "stats_day1": {
        "duration": "day1",
        "start": 1776897885,
        "end": 1776984286,
        "statsUsd": {
          "volume": {
            "currentValue": "4392297.38289152088393",
            "previousValue": "6096041.545027661300558",
            "change": -0.2794836861841645
          }
        },
        "statsNonCurrency": {
          "transactions": { "currentValue": 50259, "previousValue": 53152, "change": -0.05442880794701987 },
          "traders": { "currentValue": 3658, "previousValue": 3550, "change": 0.030422535211267605 }
        }
      }
    }
  }
}
```

### Usage Guidelines

* Subscribe using `tokenId` in the format `tokenAddress:networkId` to stream detailed stats for a specific token.
* Use this subscription to keep token pages, dashboards, or watchlists live without repeatedly polling [getDetailedTokenStats](/api-reference/queries/getdetailedtokenstats).
* Stats cover the same windows supported by `getDetailedTokenStats` (1m, 5m, 1h, 4h, 12h, 24h). Request only the timeframes and fields you need.
* Supports both non-currency stats (buyers, buys, sellers, sells, traders, transactions) and USD stats (buy/sell volume, open/close, highest/lowest, liquidity).

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="How does this differ from onDetailedStatsUpdated?">
    [onDetailedStatsUpdated](/api-reference/subscriptions/ondetailedstatsupdated) streams updates for specific pairs only. `onDetailedTokenStatsUpdated` streams aggregated stats across all pairs for a specified token.
  </Accordion>

  <Accordion title="Can I subscribe to multiple tokens at once?">
    Open a separate subscription per `tokenId`. Each subscription maintains its own stream.
  </Accordion>

  <Accordion title="What does statsType: FILTERED vs UNFILTERED mean?">
    `FILTERED` excludes suspected bot and sandwich attack transactions for cleaner stats. `UNFILTERED` includes all transactions.
  </Accordion>
</AccordionGroup>

### Related Recipes

* [Detailed Token Page](/recipes/detailed-token-page): Build a comprehensive token detail page with price, holders, trades, and real-time updates