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

# getTokenEvents

> Returns transactions for a pair. Reference for the getTokenEvents query in the Codex API: arguments, response fields, and usage.

## GraphQL

```
type Query {
  getTokenEvents(
    limit: Int
    query: EventsQueryInput!
    cursor: String
    direction: RankingDirection
  ): EventConnection
}

enum EventCommitmentLevel {
  Processed
  Confirmed
}

enum EventType {
  Burn
  Mint
  Swap
  Sync
  Collect
  CollectProtocol
  PoolBalanceChanged
  LiquidityLock
}

type BurnEventData {
  amount0: String
  amount1: String
  amount0Shifted: String
  amount1Shifted: String
  tickLower: String
  tickUpper: String
  type: EventType!
}

type MintEventData {
  amount0: String
  amount1: String
  amount0Shifted: String
  amount1Shifted: String
  tickLower: String
  tickUpper: String
  type: EventType!
}

type SwapEventData {
  amount0: String
  amount0In: String
  amount0Out: String
  amount1: String
  amount1In: String
  amount1Out: String
  amountNonLiquidityToken: String
  priceBaseToken: String
  priceBaseTokenTotal: String
  priceUsd: String
  priceUsdTotal: String
  tick: String
  type: EventType!
}

type PoolBalanceChangedEventData {
  amount0: String
  amount1: String
  amount0Shifted: String
  amount1Shifted: String
  token0: String
  token1: String
  sender: String
  protocolFeeAmount0: String
  protocolFeeAmount1: String
  liquidity0: String
  liquidity1: String
  type: EventType!
}

union EventData = BurnEventData | MintEventData | SwapEventData | PoolBalanceChangedEventData

enum QuoteToken {
  token0
  token1
}

enum EventDisplayType {
  Burn
  Mint
  Buy
  Sell
  Sync
  Collect
  CollectProtocol
}

enum SandwichLabelForEventType {
  sandwiched
  frontrun
  backrun
}

type SandwichLabelForEvent {
  label: String!
  sandwichType: SandwichLabelForEventType!
  token0DrainedAmount: String!
  token1DrainedAmount: String!
}

type WashtradeLabelForEvent {
  label: String!
}

type LabelsForEvent {
  sandwich: SandwichLabelForEvent
  washtrade: WashtradeLabelForEvent
}

type PumpCashbackFeeData {
  type: String!
  cashbackFeeBps: Int!
  cashbackAmountLamports: String!
}

type PumpAmmCashbackFeeData {
  type: String!
  cashbackFeeBps: Int!
  cashbackAmountLamports: String!
}

type LiftHarvestFeeData {
  type: String!
  positionId: String!
  quoteAddress: String!
  creatorAddress: String
  quoteToCreator: String!
  quoteToTreasury: String!
  baseBurned: String!
}

type TollyCollectionFeeData {
  type: String!
  positionId: String!
  projectToken: String!
  quoteCollectedRaw: String!
  tokenBurnedRaw: String!
  tollyBuybackRaw: String!
  projectBuybackRaw: String!
  projectBuybackAccruedRaw: String!
  holderRewardsRaw: String!
  protocolRaw: String!
  creatorPaidRaw: String!
  creatorAccruedRaw: String!
}

union SupplementalFeeData = PumpCashbackFeeData | PumpAmmCashbackFeeData | LiftHarvestFeeData | TollyCollectionFeeData

type EventFeeData {
  poolFeeRateRaw: String
  poolFeeBps: Float
  poolFeeAmountRaw: String
  dynamicFee: Boolean
  estimatedPoolFee: Boolean
  baseFeeNativeUnit: String
  priorityFeeNativeUnit: String
  gasUsed: String
  poolFeeCurrencyIndex: Int
  protocolFeeCurrencyIndex: Int
  builderTipNativeUnit: String
  l1DataFeeNativeUnit: String
  txEventCount: Int
  supplementalFeeData: SupplementalFeeData
}

type TradeSource {
  id: String!
  displayName: String
}

type CurrencyUnits {
  currency0: String!
  currency1: String!
  decimals0: Int!
  decimals1: Int!
}

type Event {
  address: String!
  commitmentLevel: EventCommitmentLevel!
  baseTokenPrice: String
  blockHash: String!
  blockNumber: Int!
  data: EventData
  eventType: EventType!
  id: String!
  liquidityToken: String
  logIndex: Int!
  maker: String
  networkId: Int!
  quoteToken: QuoteToken
  timestamp: Int!
  token0Address: String
  token1Address: String
  token0SwapValueUsd: String
  token1SwapValueUsd: String
  token0ValueBase: String
  token1ValueBase: String
  token0PoolValueUsd: String
  token1PoolValueUsd: String
  transactionHash: String!
  transactionIndex: Int!
  supplementalIndex: Int
  eventDisplayType: EventDisplayType
  labels: LabelsForEvent
  feeData: EventFeeData
  walletAge: Int
  walletLabels: [String!]
  tradeSource: TradeSource
  currencyUnits: CurrencyUnits
}

type EventConnection {
  items: [Event]
  cursor: String
}

input NumberFilter {
  gte: Float
  gt: Float
  lte: Float
  lt: Float
}

input EventQueryTimestampInput {
  from: Int!
  to: Int!
}

enum SymbolType {
  TOKEN
  POOL
}

input EventsQueryInput {
  address: String!
  quoteToken: QuoteToken
  amountNonLiquidityToken: NumberFilter
  eventDisplayType: [EventDisplayType]
  eventType: EventType
  maker: String
  networkId: Int!
  timestamp: EventQueryTimestampInput
  priceBaseToken: NumberFilter
  priceBaseTokenTotal: NumberFilter
  priceUsd: NumberFilter
  priceUsdTotal: NumberFilter
  symbolType: SymbolType
  crossPools: Boolean
  transactionHash: String
}

enum RankingDirection {
  ASC
  DESC
}
```

### Example

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

```graphql theme={null}
{
  getTokenEvents(
    query: {address: "So11111111111111111111111111111111111111112", networkId: 1399811149}
    limit: 10
  ) {
    items {
      eventDisplayType
      timestamp
      maker
      transactionHash
      token0SwapValueUsd
      token1SwapValueUsd
      data {
        ... on SwapEventData {
          priceUsd
          priceUsdTotal
        }
      }
    }
    cursor
  }
}
```

### Usage Guidelines

* Pass a token address or pair address to the `address` field; if you pass a token address, it will automatically find the top pair for that token
* Use `eventDisplayType` filter to get only `Buy` or `Sell` events (splits swaps into directional trades)
* Use `eventType: Swap` to filter for only swap transactions, excluding liquidity events
* Use `maker` filter to get transactions for a specific wallet address
* Use `timestamp` filter with `from` and `to` for historical event lookups. `timestamp.from` and `to` are compared to a sub-second event time, but the returned `timestamp` is rounded to the second, so events in the same second as a bound can be left out. Pad both bounds by 1 to 2 seconds and dedupe on `transactionHash` + `logIndex`.
* Use `priceUsdTotal` filter to find large trades (e.g., `priceUsdTotal: {gte: 10000}`)
* Results are ordered by most recent first by default; use `direction: ASC` for oldest first
* Response limit: 200 events per request (default 10).
* Each event can include a `tradeSource` identifying the app the trade was placed through (swaps on Solana and EVM networks; null for most events, since most trades carry no identifying signal) — see [Trade source](https://docs.codex.io/recipes/events.md#trade-source)

### Troubleshooting Tips

> [accordion] How do I determine if a swap was a buy or sell?
>
> Use `eventDisplayType` instead of `eventType`. While `eventType` returns `Swap` for all swaps, `eventDisplayType` splits them into `Buy` or `Sell` based on the direction of the trade relative to the quote token.

> [accordion] Why do Buy and Sell look reversed for my token?
>
> `eventDisplayType`, `amountNonLiquidityToken`, and the price fields all describe the `quoteToken` side of the pair (`token0` or `token1`). `Buy` means that token left the pool to the trader. The same swap reads `Sell` from the other side.
>
> Passing a token address picks that token's top pair, but it does not set `quoteToken` to your token. The pair's default side is used instead. For example, passing USDC on Ethereum returns its top USDC/WETH pair from WETH's side, so USDC sells show as `Buy`.
>
> To be sure, pass `quoteToken: token0` or `quoteToken: token1` explicitly, and check the pair's `token0` and `token1` addresses (from `pairMetadata` or `filterPairs`) to pick the right one. Every event also returns the `quoteToken` that was used.

> [accordion] Why am I getting Mint/Burn events when I only want swaps?
>
> Add `eventType: Swap` to your query filters to exclude liquidity add/remove events. Alternatively, use `eventDisplayType: [Buy, Sell]` to get only buy and sell events.

> [accordion] How do I get events for a specific time range?
>
> Use the `timestamp` filter with `from` and `to` unix timestamps. For example: `timestamp: {from: 1704067200, to: 1704153600}` for a 24-hour window.

> [accordion] What's the difference between priceUsd and priceUsdTotal?
>
> `priceUsd` is the price per token at the time of the swap. `priceUsdTotal` is the total USD value of the swap (`amountNonLiquidityToken` x `priceUsd`). Use `priceUsdTotal` for filtering by trade size.

> [accordion] What are token0SwapValueUsd and token1SwapValueUsd?
>
> They are the USD price of one unit of `token0` and `token1` at the time of the swap, not the USD value of each side of the trade. On a USDC/WETH swap, `token0SwapValueUsd` reads about `1` and `token1SwapValueUsd` reads the price of one WETH, whatever the trade size. For the trade's size in USD, use `priceUsdTotal`.

> [accordion] What are priceBaseToken and priceBaseTokenTotal?
>
> They're the same two values denominated in the network's base token (e.g. ETH on Ethereum, SOL on Solana, BNB on BNB Chain) instead of USD:
>
> * **`priceBaseToken`**: the price per `quoteToken` at the time of the swap, in the network's base token.
> * **`priceBaseTokenTotal`**: the total size of the swap in the network's base token (`amountNonLiquidityToken` x `priceBaseToken`).
>
> Both are available as filter inputs (with `gt`/`gte`/`lt`/`lte`) and as response fields on `SwapEventData`. Use the base-token variants when you want values that are stable relative to the chain's native asset (e.g. "swaps over 10 SOL"); use `priceUsd`/`priceUsdTotal` when you want dollar terms.
>
> The base token is always the network's native token, not the pair's quote token. A Pump.fun token can trade against a quote token other than SOL, but `priceBaseToken` is still in SOL. Don't multiply it by the quote token's USD price; use `priceUsd`, or `marketCap` from the token, instead.

> [accordion] How can I identify sandwich attacks or wash trades?
>
> Check the `labels` field on events. It contains `sandwich` labels (with types `sandwiched`, `frontrun`, `backrun`) and `washtrade` labels when detected.

> [accordion] I'm missing transaction data for a specific block — how can I find it?
>
> `getTokenEvents` looks at the **top pair** when filtering for events, not all pairs. If the missing transactions occurred on a different pair, use `listPairsWithMetadataForToken` to find the correct pool (filter by volume) and pass that pair address to `getTokenEvents`.

### Related Recipes

* [Detailed Token Page](https://docs.codex.io/recipes/detailed-token-page.md): Build a comprehensive token detail page with price, holders, trades, and real-time updates
* [Events](https://docs.codex.io/recipes/events.md): Build a token swap list with filtering, pagination, and real-time updates


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