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

# Global Fees Paid

> Understand how Codex measures and surfaces fee data across the API.

export const EmbedFrame = ({query, height, caption}) => {
  const encodedQuery = typeof window === "undefined" ? "" : encodeURIComponent(query);
  return <Frame caption={caption}>
      <div style={{
    width: "100%",
    height: height || "100%",
    minHeight: "400px",
    maxHeight: "90vh",
    position: "relative",
    display: "flex",
    flexDirection: "column",
    flex: "1"
  }}>
        <iframe src={"https://explorer.codex.io/embed.html?query=" + encodedQuery} width="100%" className="w-full aspect-video rounded-xl" style={{
    flex: "1",
    height: "100%",
    borderRadius: "12px",
    border: "none",
    display: "block"
  }} />
      </div>
    </Frame>;
};

<div className="gfp-page">
  Global Fees Paid (GFP) is a unified view of every dollar of fees a token, pool, or trader generates, broken into five components, summed into a single total, and combined into a handful of derived metrics. The same five components appear across bar queries, token filters, event feeds, and launchpad subscriptions, so once you understand them here you'll recognize them everywhere they're surfaced.

  <div style={{ marginTop: '1.5rem' }}>
    <Accordion title="Example query to rank tokens by 1-hour total fees, filtered for meaningful fee activity">
      <EmbedFrame
        query={`query filterTokens {
filterTokens(
filters: {totalFees24: {gt: 500, lt: 1000000}, feeToVolumeRatio24: {gt: 0.005}, volume24: {gt: 50000}, network: [1, 1399811149, 8453, 137, 42161, 10, 56, 146]}
limit: 20
rankings: [{attribute: totalFees1, direction: DESC}]
) {
count
results {
token {
symbol
name
networkId
address
}
volume1
totalFees1
poolFees1
baseFees1
priorityFees1
builderTips1
l1DataFees1
feeToVolumeRatio1
}
}
}`}
      />
    </Accordion>
  </div>

  ## What Global Fees Paid measures

  GFP captures the full economic cost of activity on-chain. Not just the trading fee a pool charges, but everything paid to network validators, block builders, and (on rollups) the L1 chain that posts the data. Every field is denominated in **USD** and summed at the start of the query window.

  The five components are the same on every endpoint. What changes is the **shape** of the data: a single scalar per event, an array per bar, a pre-computed value over a time window, or a single-window snapshot. The [endpoint coverage map](#endpoint-coverage) below shows which shape you get where.

  ## Endpoint coverage

  This is the master map. Find the endpoint you're using and follow the link to see the fields it exposes.

  | Endpoint                                                                                | Type returned               | Field set                                                 |
  | --------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------- |
  | [`getTokenEvents`](/api-reference/queries/gettokenevents)                               | `Event` (with `feeData`)    | [Per-transaction fee detail](#per-transaction-fee-detail) |
  | [`getTokenEventsForMaker`](/api-reference/queries/gettokeneventsformaker)               | `Event` (with `feeData`)    | [Per-transaction fee detail](#per-transaction-fee-detail) |
  | [`onEventsCreatedByMaker`](/api-reference/subscriptions/oneventscreatedbymaker)         | `Event` (with `feeData`)    | [Per-transaction fee detail](#per-transaction-fee-detail) |
  | [`getBars`](/api-reference/queries/getbars)                                             | `BarsResponse`              | [Chart queries](#chart-queries)                           |
  | [`getTokenBars`](/api-reference/queries/gettokenbars)                                   | `TokenBarsResponse`         | [Chart queries](#chart-queries)                           |
  | [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated)                           | `IndividualBarData`         | [Chart subscriptions](#chart-subscriptions)               |
  | [`onTokenBarsUpdated`](/api-reference/subscriptions/ontokenbarsupdated)                 | `IndividualBarData`         | [Chart subscriptions](#chart-subscriptions)               |
  | [`filterTokens`](/api-reference/queries/filtertokens)                                   | `TokenFilterResult`         | [Token filtering](#token-filtering)                       |
  | [`onFilterTokensUpdated`](/api-reference/subscriptions/onfiltertokensupdated)           | `TokenFilterResult`         | [Token filtering](#token-filtering)                       |
  | [`onLaunchpadTokenEvent`](/api-reference/subscriptions/onlaunchpadtokenevent)           | `LaunchpadTokenEventOutput` | [Launchpad subscriptions](#launchpad-subscriptions)       |
  | [`onLaunchpadTokenEventBatch`](/api-reference/subscriptions/onlaunchpadtokeneventbatch) | `LaunchpadTokenEventOutput` | [Launchpad subscriptions](#launchpad-subscriptions)       |

  ## The five components

  <Note>
    All five components are USD-denominated everywhere they appear in the schema. Some endpoints additionally expose the underlying native-unit values (wei on EVM, lamports on Solana). See [per-transaction fee detail](#per-transaction-fee-detail) for that.
  </Note>

  | Component      | What it measures                                                                                                                          |
  | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
  | `poolFees`     | DEX/pool fees collected by the pool itself. The "trading fee," typically distributed to liquidity providers and/or the protocol.          |
  | `baseFees`     | Base fees paid to the network as gas. On EVM this is `baseFeePerGas × gasUsed`; on Solana it's roughly `5000 lamports × signature count`. |
  | `priorityFees` | Priority/tip portion of gas, paid to validators. EIP-1559 priority fee on EVM; tip portion of total fee on Solana.                        |
  | `builderTips`  | Direct payments to block builders. The cleanest on-chain MEV signal: ETH transfers to `block.coinbase` on EVM, Jito tips on Solana.       |
  | `l1DataFees`   | Cost of posting rollup data to L1. **L2-only** (Base, Optimism, Arbitrum, etc.). Always `0` on L1s and Solana.                            |

  ## Derived metrics

  Built from the five components, these surface the most common questions developers ask about fee data without making them do the arithmetic.

  | Field                 | Formula                                                                 | What it tells you                                                       |
  | --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
  | `totalFees`           | `poolFees` + `baseFees` + `priorityFees` + `builderTips` + `l1DataFees` | Total economic cost over the window.                                    |
  | `feeToVolumeRatio`    | `totalFees` / `volume`                                                  | Normalized fee burden: how expensive activity is relative to volume.    |
  | `mevToTotalFeesRatio` | `builderTips` / `totalFees`                                             | Share of activity going to block builders. Your MEV-exposure indicator. |
  | `gasPerVolume`        | (`baseFees` + `priorityFees` + `l1DataFees`) / `volume`                 | Pure gas cost per dollar of volume, excluding pool and builder fees.    |
  | `averageCostPerTrade` | `totalFees` / `transactions`                                            | Average user cost per trade in USD.                                     |

  <Tip>
    Ratios are `null` when their divisor is zero (no volume, no transactions, or no total fees). Always handle the null case in client code.
  </Tip>

  ## Classifications

  Two categorical fields summarize the fee profile at a glance, useful for filtering, alerting, or labeling tokens in a UI without surfacing raw numbers.

  **`mevRiskLevel`**, based on `mevToTotalFeesRatio`:

  * `low`: builder tips are less than 3% of total fees
  * `medium`: between 3% and 30%
  * `high`: more than 30%
  * `null`: when `totalFees` is zero

  **`feeRegimeClassification`** describes which fee component dominates:

  * `gas-dominated`: gas (base + priority + L1 data) is more than 50% of fees
  * `mev-dominated`: builder tips are more than 20% of fees
  * `pool-fee-dominated`: pool fees dominate
  * `null`: when fees are zero

  ## Caveats and gotchas

  A few things that are easy to miss and worth flagging up front:

  * **Subscriptions only expose the five raw components.** `IndividualBarData` (used by [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated) and [`onTokenBarsUpdated`](/api-reference/subscriptions/ontokenbarsupdated)) does not include derived metrics or classifications. If you need `totalFees` or any ratio in a streaming context, compute it client-side or pull it from the corresponding query.
  * **Launchpad `feeToVolumeRatio1` is a `Float`, not a `String`.** Everywhere else in the schema, ratio fields are returned as strings (to preserve precision on very small or very large values). On `LaunchpadTokenEventOutput` it's a float. Your parsing layer needs to handle both.
  * **Filter inputs are a subset of result fields.** [`filterTokens`](/api-reference/queries/filtertokens) returns 35 fee fields, but only seven of them are usable as filter inputs. The full list is in the [token filtering](#token-filtering) section.
  * **Component-level filters at shorter windows aren't accepted as filter inputs.** You can filter on `totalFees5m` but not `builderTips5m`. Component-level filters are only available for the 24h window (`poolFees24`).
  * **Native-unit fields are chain-specific.** On `EventFeeData`, fields like `baseFeeNativeUnit` are wei on EVM and lamports on Solana: same field name, different units. The USD-denominated parent fields don't have this ambiguity.

  ## Per-transaction fee detail

  Every event returned by an event-feed endpoint carries a `feeData` object with both the **USD-denominated** GFP components and **native-unit** raw values. This is the most granular fee data the API exposes: one record per swap.

  **USD components** (same definitions as above):
  `poolFees`, `baseFees`, `priorityFees`, `builderTips`, `l1DataFees`, `totalFees`.

  **Pool-fee detail:**

  | Field              | Type      | Meaning                                                                                    |
  | ------------------ | --------- | ------------------------------------------------------------------------------------------ |
  | `poolFeeRateRaw`   | `String`  | Pool fee rate in the protocol's native encoding (e.g. raw uint24 for Uniswap V3).          |
  | `poolFeeBps`       | `Float`   | Pool fee rate normalized to basis points (1 bps = 0.01%).                                  |
  | `poolFeeAmountRaw` | `String`  | Pool fee absolute amount in the fee token's smallest unit, when known per-swap.            |
  | `dynamicFee`       | `Boolean` | `true` when the pool fee is dynamic (Uniswap V4 hooks, AlgebraIntegral plugins).           |
  | `estimatedPoolFee` | `Boolean` | `true` when `poolFeeBps` is a protocol-level estimate rather than an exact per-swap value. |

  **Native-unit gas detail** (wei on EVM, lamports on Solana):

  | Field                   | Type     | Meaning                                                                                                  |
  | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
  | `baseFeeNativeUnit`     | `String` | Base fee portion of gas. On EVM: `baseFeePerGas × gasUsed`. On Solana: `5000 × signatures`.              |
  | `priorityFeeNativeUnit` | `String` | Priority fee. On EVM: `(effectiveGasPrice − baseFeePerGas) × gasUsed`. On Solana: `meta.fee − baseFee`.  |
  | `gasUsed`               | `String` | Gas units (EVM) or compute units (Solana) consumed by the transaction.                                   |
  | `builderTipNativeUnit`  | `String` | Direct payment to the block builder. ETH transfers to `block.coinbase` on EVM, Jito tip on Solana.       |
  | `l1DataFeeNativeUnit`   | `String` | L1 data posting fee (L2 rollups only).                                                                   |
  | `txEventCount`          | `Int`    | Number of DEX events in the transaction. Use this as the divisor for pro-rating tx-level fees per event. |

  **Supplemental fee data:** `EventFeeData.supplementalFeeData` is a union type carrying protocol-specific fields. It currently has two variants, both for Pump.fun cashback:

  * **`PumpCashbackFeeData`** for Pump V1 swaps. Fields: `type` (always `"PumpCashback"`), `cashbackFeeBps`, `cashbackAmountLamports`.
  * **`PumpAmmCashbackFeeData`** for Pump AMM swaps. Same field shape, with `type = "PumpAmmCashback"`.

  <Tip>
    The maker/wallet endpoints ([`getTokenEventsForMaker`](/api-reference/queries/gettokeneventsformaker), [`onEventsCreatedByMaker`](/api-reference/subscriptions/oneventscreatedbymaker)) are the simplest path to per-transaction fee detail for a specific wallet. Useful for trader analytics, MEV exposure tracking, or PnL accounting that includes gas costs.
  </Tip>

  ## Chart queries

  [`getBars`](/api-reference/queries/getbars) and [`getTokenBars`](/api-reference/queries/gettokenbars) return parallel arrays. The value at index `i` corresponds to the bar starting at timestamp `t[i]`. All twelve fields are exposed: the five components, `totalFees`, the four ratios, and both classifications.

  | Field                     | Type       | Notes                                                                            |
  | ------------------------- | ---------- | -------------------------------------------------------------------------------- |
  | `poolFees`                | `[String]` | USD per bar.                                                                     |
  | `baseFees`                | `[String]` | USD per bar.                                                                     |
  | `priorityFees`            | `[String]` | USD per bar.                                                                     |
  | `builderTips`             | `[String]` | USD per bar.                                                                     |
  | `l1DataFees`              | `[String]` | USD per bar. Always `0` outside L2 rollups.                                      |
  | `totalFees`               | `[String]` | USD per bar.                                                                     |
  | `feeToVolumeRatio`        | `[String]` | Null when bar volume is zero.                                                    |
  | `mevToTotalFeesRatio`     | `[String]` | Null when `totalFees` is zero.                                                   |
  | `gasPerVolume`            | `[String]` | Null when volume is zero.                                                        |
  | `averageCostPerTrade`     | `[String]` | Null when no transactions.                                                       |
  | `mevRiskLevel`            | `[String]` | Per-bar enum: `low` / `medium` / `high`, or null.                                |
  | `feeRegimeClassification` | `[String]` | Per-bar enum: `gas-dominated` / `mev-dominated` / `pool-fee-dominated`, or null. |

  ## Chart subscriptions

  [`onBarsUpdated`](/api-reference/subscriptions/onbarsupdated) and [`onTokenBarsUpdated`](/api-reference/subscriptions/ontokenbarsupdated) deliver one bar update at a time, so each fee field is a single scalar rather than an array. **Only the five raw components are exposed here.** Derived metrics and classifications are not.

  | Field          | Type     | Meaning           |
  | -------------- | -------- | ----------------- |
  | `poolFees`     | `String` | USD for this bar. |
  | `baseFees`     | `String` | USD for this bar. |
  | `priorityFees` | `String` | USD for this bar. |
  | `builderTips`  | `String` | USD for this bar. |
  | `l1DataFees`   | `String` | USD for this bar. |

  `IndividualBarData` is nested inside `OnBarsUpdatedResponse.aggregates.{r1, r5, r15, r60, …}.{usd, token}`. Resolution and currency are picked at the wrapper level, then the bar's fields are fetched.

  <Warning>
    If you need `totalFees`, `mevRiskLevel`, or any ratio in a subscription context, compute it client-side from the five components or pull it from [`getBars`](/api-reference/queries/getbars) / [`getTokenBars`](/api-reference/queries/gettokenbars).
  </Warning>

  ## Token filtering

  [`filterTokens`](/api-reference/queries/filtertokens) and [`onFilterTokensUpdated`](/api-reference/subscriptions/onfiltertokensupdated) return per-token results with fees pre-computed across **five rolling windows ending at "now"**: 5 minutes, 1 hour, 4 hours, 12 hours, and 24 hours. Each window suffix gives you a different field name.

  **Seven fields × five windows = 35 fee-related fields per token.** The base names are:

  * `poolFees{w}`, `baseFees{w}`, `priorityFees{w}`, `builderTips{w}`, `l1DataFees{w}`: the five components
  * `totalFees{w}`: the sum
  * `feeToVolumeRatio{w}`: the ratio

  Where `{w}` is one of `5m`, `1`, `4`, `12`, `24`. So the fully-enumerated set includes `poolFees5m`, `poolFees1`, `poolFees4`, `poolFees12`, `poolFees24`, `baseFees5m`, …, `feeToVolumeRatio24`.

  ### Filter inputs

  The `TokenFilters` input accepts a **subset** of the result fields. Only seven inputs are filterable:

  | Filter input         | Type           | Notes                                                       |
  | -------------------- | -------------- | ----------------------------------------------------------- |
  | `totalFees5m`        | `NumberFilter` | `gt` / `lt` / `between` against summed fees over 5 minutes. |
  | `totalFees1`         | `NumberFilter` | …over 1 hour.                                               |
  | `totalFees4`         | `NumberFilter` | …over 4 hours.                                              |
  | `totalFees12`        | `NumberFilter` | …over 12 hours.                                             |
  | `totalFees24`        | `NumberFilter` | …over 24 hours.                                             |
  | `poolFees24`         | `NumberFilter` | The only component-level filter: 24h pool fees.             |
  | `feeToVolumeRatio24` | `NumberFilter` | 24h ratio filter.                                           |

  Component-level filters at shorter windows (e.g. `builderTips24`, `baseFees1`) are **not** accepted as filter inputs.

  ### Ranking attributes

  All 35 result fields are usable as `ranking.attribute` values for sorting:

  ```
  poolFees5m, poolFees1, poolFees4, poolFees12, poolFees24,
  baseFees5m, baseFees1, baseFees4, baseFees12, baseFees24,
  priorityFees5m, priorityFees1, priorityFees4, priorityFees12, priorityFees24,
  builderTips5m, builderTips1, builderTips4, builderTips12, builderTips24,
  l1DataFees5m, l1DataFees1, l1DataFees4, l1DataFees12, l1DataFees24,
  totalFees5m, totalFees1, totalFees4, totalFees12, totalFees24,
  feeToVolumeRatio5m, feeToVolumeRatio1, feeToVolumeRatio4, feeToVolumeRatio12, feeToVolumeRatio24
  ```

  ## Launchpad subscriptions

  [`onLaunchpadTokenEvent`](/api-reference/subscriptions/onlaunchpadtokenevent) and [`onLaunchpadTokenEventBatch`](/api-reference/subscriptions/onlaunchpadtokeneventbatch) deliver real-time updates on launchpad tokens (Pump.fun, Bonk, MeteoraDBC, Pump Mayhem, etc.). Fee fields populate on `eventType: "Updated"` events; other event types (`Deployed`, `Created`, `Migrated`, `Completed`, and the `Unconfirmed*` variants) carry the field shape but values may be null.

  **Only the 1-hour window is exposed:**

  | Field               | Type     | Notes                                                                                                    |
  | ------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
  | `poolFees1`         | `String` | USD over the last hour.                                                                                  |
  | `baseFees1`         | `String` | USD over the last hour.                                                                                  |
  | `priorityFees1`     | `String` | USD over the last hour.                                                                                  |
  | `builderTips1`      | `String` | USD over the last hour.                                                                                  |
  | `l1DataFees1`       | `String` | USD over the last hour. Always `0` for non-L2 launchpad networks (most of them).                         |
  | `totalFees1`        | `String` | Sum of the five components, USD.                                                                         |
  | `feeToVolumeRatio1` | `Float`  | `totalFees1 / volume1`. **Note: this is a `Float`, unlike the `String` ratios elsewhere in the schema.** |

  <Tip>
    [`onLaunchpadTokenEventBatch`](/api-reference/subscriptions/onlaunchpadtokeneventbatch) is the more efficient choice when you don't need event-by-event delivery. It returns batched arrays in a single message.
  </Tip>
</div>