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

# onDetailedStatsUpdated

> Live-streamed bucketed stats for a given token within a pair. onDetailedStatsUpdated subscription reference: arguments and payload fields.

## GraphQL

```
type Subscription {
  # Requires a Growth or Enterprise plan.
  onDetailedStatsUpdated(
    pairId: String
    tokenOfInterest: TokenOfInterest
    statsType: TokenPairStatisticsType
  ): DetailedStats
}

enum TokenOfInterest {
  token0
  token1
}

enum TokenPairStatisticsType {
  FILTERED
  UNFILTERED
}

enum DetailedStatsWindowSize {
  day1
  hour12
  hour4
  hour1
  min5
}

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

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

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

type WindowedDetailedStats {
  windowSize: DetailedStatsWindowSize!
  timestamp: Int!
  endTimestamp: Int!
  buckets: [DetailedStatsBucketTimestamp]!
  transactions: DetailedStatsNumberMetrics!
  volume: DetailedStatsStringMetrics!
  buys: DetailedStatsNumberMetrics!
  sells: DetailedStatsNumberMetrics!
  buyers: DetailedStatsNumberMetrics!
  sellers: DetailedStatsNumberMetrics!
  traders: DetailedStatsNumberMetrics
  buyVolume: DetailedStatsStringMetrics
  sellVolume: DetailedStatsStringMetrics
}

type DetailedStats {
  pairId: String!
  tokenOfInterest: TokenOfInterest!
  statsType: TokenPairStatisticsType!
  stats_min5: WindowedDetailedStats
  stats_hour1: WindowedDetailedStats
  stats_hour4: WindowedDetailedStats
  stats_hour12: WindowedDetailedStats
  stats_day1: WindowedDetailedStats
}
```

### Example

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

```graphql theme={null}
subscription {
  onDetailedStatsUpdated(
    pairId: "BGm1tav58oGcsQJehL9WXBFXF7D27vZsKefj4xJKD5Y:1399811149"
    tokenOfInterest: token0
  ) {
    pairId
    tokenOfInterest
    statsType
    stats_min5 {
      windowSize
      timestamp
      endTimestamp
      transactions {
        change
        currentValue
        previousValue
      }
      volume {
        change
        currentValue
        previousValue
      }
      buys {
        change
        currentValue
        previousValue
      }
      sells {
        change
        currentValue
        previousValue
      }
      buyers {
        change
        currentValue
        previousValue
      }
      sellers {
        change
        currentValue
        previousValue
      }
    }
    stats_hour1 {
      windowSize
      timestamp
      endTimestamp
      transactions {
        change
        currentValue
        previousValue
      }
      volume {
        change
        currentValue
        previousValue
      }
    }
  }
}
```

```json Example Response theme={null}
{
  "data": {
    "onDetailedStatsUpdated": {
      "pairId": "BGm1tav58oGcsQJehL9WXBFXF7D27vZsKefj4xJKD5Y:1399811149",
      "tokenOfInterest": "token0",
      "statsType": "UNFILTERED",
      "stats_min5": {
        "windowSize": "min5",
        "timestamp": 1769561431,
        "endTimestamp": 1769561732,
        "transactions": {
          "change": -0.38095238095238093,
          "currentValue": 13,
          "previousValue": 21
        },
        "volume": {
          "change": -0.984327,
          "currentValue": "533",
          "previousValue": "34008"
        },
        "buys": {
          "change": -0.631578947368421,
          "currentValue": 7,
          "previousValue": 19
        },
        "sells": {
          "change": 2,
          "currentValue": 6,
          "previousValue": 2
        },
        "buyers": {
          "change": -0.46153846153846156,
          "currentValue": 7,
          "previousValue": 13
        },
        "sellers": {
          "change": 0.5,
          "currentValue": 3,
          "previousValue": 2
        }
      },
      "stats_hour1": {
        "windowSize": "hour1",
        "timestamp": 1769558131,
        "endTimestamp": 1769561732,
        "transactions": {
          "change": 0.5,
          "currentValue": 150,
          "previousValue": 100
        },
        "volume": {
          "change": 0.465108,
          "currentValue": "172014",
          "previousValue": "117407"
        }
      }
    }
  }
}
```

### Usage Guidelines

* Subscribe using `pairId` (format `pairAddress:networkId`) and `tokenOfInterest` (`token0` or `token1`)
* Stats are provided across multiple time windows: `stats_min5`, `stats_hour1`, `stats_hour4`, `stats_hour12`, `stats_day1`
* Each metric includes `currentValue`, `previousValue`, and `change` (percent change as a decimal) for easy comparison
* Use `buckets` on any metric for granular breakdowns within the window (e.g., per-minute data within the 5-minute window)
* Available metrics: `transactions`, `volume`, `buys`, `sells`, `buyers`, `sellers`, `traders`, `buyVolume`, `sellVolume`
* Updates are streamed in real-time as trading activity changes the stats

### Troubleshooting Tips

> [accordion] What's the difference between tokenOfInterest and quoteToken?
>
> They serve the same purpose — selecting which token in the pair to focus on — but are used in different subscriptions. `onDetailedStatsUpdated` uses `tokenOfInterest`, while `onBarsUpdated` and `onEventsCreated` use `quoteToken`. Both accept `token0` or `token1`.

> [accordion] What does the change field represent?
>
> `change` is the percent change between `currentValue` and `previousValue`, expressed as a decimal. For example, `0.25` means a 25% increase, and `-0.5` means a 50% decrease.

> [accordion] How do buckets work?
>
> Each window is divided into equal time buckets. For example, `stats_min5` has 5 one-minute buckets, and `stats_hour1` has 12 five-minute buckets. The `buckets` field on the parent returns the start/end timestamps for each bucket, and the `buckets` field on each metric returns the aggregated values per bucket.

> [accordion] When should I use this vs onBarsUpdated?
>
> Use `onDetailedStatsUpdated` for trading activity stats (transaction counts, buyer/seller counts, volume breakdowns with change percentages). Use `onBarsUpdated` for OHLCV price candlestick data. They complement each other — stats for activity, bars for price.


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