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

<div data-generated>
  ## 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
  }
  ```
</div>

### Example

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

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>