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

# getDetailedTokenStats

> Returns bucketed stats for a given token.

<div data-generated>
  ## GraphQL

  ```
  type Query {
    getDetailedTokenStats(
      tokenAddress: String!
      networkId: Int!
      timestamp: Int
      durations: [DetailedTokenStatsDuration]
      bucketCount: Int
      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>

### Example

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

```graphql theme={null}
{
  getDetailedTokenStats(
    tokenAddress: "0x6982508145454ce325ddbe47a25d4ec3d2311933"
    networkId: 1
    durations: [hour1, day1]
  ) {
    tokenAddress
    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
        }
      }
    }
  }
}
```

### Usage Guidelines

* Query using `tokenAddress` and `networkId` — this aggregates stats across all pairs for the token
* Use `durations` array to request specific time windows: `min5`, `min15`, `hour1`, `hour4`, `hour12`, `day1`, `week1`, `day30`
* Stats are returned in separate fields like `stats_hour1`, `stats_day1`, etc. based on requested durations
* `statsUsd` contains USD-denominated metrics: volume, buyVolume, sellVolume, open, highest, lowest, close, liquidity
* `statsNonCurrency` contains count metrics: transactions, buys, sells, traders, buyers, sellers
* Each metric includes `currentValue`, `previousValue`, and `change` (percent change in decimal format, e.g. -0.52 = -52%)
* Use `buckets` array within each metric for granular time-series data within the duration window
* Use `timestamps` array to map bucket indices to their corresponding time ranges

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="What is the difference between getDetailedTokenStats and getDetailedPairStats?">
    `getDetailedTokenStats` aggregates stats across **all pairs** for a given token, giving you a holistic view of the token's activity. `getDetailedPairStats` returns stats for a **specific pair**, which is useful when you care about a token's activity within a single liquidity pool.
  </Accordion>

  <Accordion title="What's the difference between FILTERED and UNFILTERED statsType?">
    `FILTERED` stats exclude suspected bot and MEV activity to show organic trading. `UNFILTERED` (the default) includes all transactions. Use the `statsType` parameter to choose which type you want.
  </Accordion>

  <Accordion title="How do I use the buckets array for charting?">
    Each metric includes a `buckets` array with values for sub-intervals within the duration. For example, `stats_hour1` might contain 12 buckets of 5 minutes each. Use the `timestamps` array at the same level to map each bucket index to its start/end time range, which gives you the x-axis for your chart.
  </Accordion>

  <Accordion title="Why is change showing as null?">
    The `change` field requires both `currentValue` and `previousValue` to calculate. For very new tokens or time windows with no previous data, `change` may be null.
  </Accordion>

  <Accordion title="How do I get historical stats?">
    Use the `timestamp` parameter to query stats as of a specific point in time. By default, stats are returned for the current time.
  </Accordion>

  <Accordion title="How does bucketCount work?">
    The `bucketCount` parameter controls how many sub-intervals the duration is divided into. For example, requesting `stats_hour1` with `bucketCount: 12` gives you twelve 5-minute buckets. This affects the length of the `buckets` array within each metric.
  </Accordion>
</AccordionGroup>