> ## 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. Reference for the getDetailedTokenStats query in the Codex API: arguments, response fields, and usage.

## GraphQL

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

### Example

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

```graphql theme={null}
{
  getDetailedTokenStats(
    tokenAddress: "TOKEN_ADDRESS"
    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. `buyers`, `sellers` and `traders` are unique wallets across all of the token's pairs, so they are lower than the sum of each pair's counts. Transactions and volume are summed.
* Use `durations` array to request specific time windows: `min5`, `hour1`, `hour4`, `hour12`, `day1`. Note that `min15`, `week1`, and `day30` are not supported for token-level stats — the response has no `stats_min15`, `stats_week1`, or `stats_day30` fields
* 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

> [accordion] 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] 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] 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] 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] 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] 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.


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