> ## 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. onDetailedTokenStatsUpdated subscription reference: arguments and payload fields.

## GraphQL

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

enum TokenPairStatisticsType {
  FILTERED
  UNFILTERED
}

enum DetailedTokenStatsDuration {
  day1
  hour12
  hour4
  hour1
  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
}
```

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

### Example

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

```graphql theme={null}
subscription {
  onDetailedTokenStatsUpdated(
    tokenId: "TOKEN_ADDRESS: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](https://docs.codex.io/api-reference/queries/getdetailedtokenstats.md).
* Stats cover the same windows supported by `getDetailedTokenStats` (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

> [accordion] How does this differ from onDetailedStatsUpdated?
>
> [onDetailedStatsUpdated](https://docs.codex.io/api-reference/subscriptions/ondetailedstatsupdated.md) streams updates for specific pairs only. `onDetailedTokenStatsUpdated` streams aggregated stats across all pairs for a specified token.

> [accordion] Can I subscribe to multiple tokens at once?
>
> Open a separate subscription per `tokenId`. Each subscription maintains its own stream.

> [accordion] What does statsType: FILTERED vs UNFILTERED mean?
>
> `FILTERED` excludes suspected bot and sandwich attack transactions for cleaner stats. `UNFILTERED` includes all transactions.

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


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