getTokenEvents

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

​

Returns

EventConnection · EventConnection

See EventConnection

Show Properties

items · [Event]

A list of transactions for a token’s top pair. See Event

cursor · String

A cursor for use in pagination. If non-null, more results are available; pages may be empty due to filtering.

​

Arguments

limit · Int

The maximum number of transactions to return.

query · EventsQueryInput! · required

The query filters to apply to the results. See EventsQueryInput

Show Properties

address · String! · required

The pair contract address to filter by. If you pass a token address in here, it will instead find the top pair for that token and use that.

quoteToken · QuoteToken

The token of interest. Can be token0 or token1. See QuoteToken

amountNonLiquidityToken · NumberFilter

The amount of quoteToken involved in the swap. See NumberFilter

eventDisplayType · [EventDisplayType]

The list of event display types to filter by. See EventDisplayType

eventType · EventType

The specific event type to filter by. See EventType

maker · String

The specific wallet address to filter by.

networkId · Int! · required

The network ID to filter by.

timestamp · EventQueryTimestampInput

The time range to filter by. See EventQueryTimestampInput

priceBaseToken · NumberFilter

The price per quoteToken at the time of the swap in the network’s base token. See NumberFilter

priceBaseTokenTotal · NumberFilter

The total amount of quoteToken involved in the swap in the network’s base token (amountNonLiquidityToken x priceBaseToken). See NumberFilter

priceUsd · NumberFilter

The price per quoteToken at the time of the swap in USD. See NumberFilter

priceUsdTotal · NumberFilter

The total amount of quoteToken involved in the swap in USD (amountNonLiquidityToken x priceUsd). See NumberFilter

symbolType · SymbolType

Specify the type of symbol you want to fetch values for (TOKEN | POOL) See SymbolType

crossPools · Boolean

When true, return the token’s latest events across ALL of its pools instead of only its top pool. Requires symbolType: TOKEN, rejects quoteToken, and issues cursors that are not interchangeable with top-pool cursors. Slower. Available on the DEFINED plan only. Defaults to false.

transactionHash · String

Only return events from this transaction (exact match; EVM hashes are matched case-insensitively). Applied inside the pair and time range scan, so pass the block timestamp as timestamp { from, to } (an equal from and to is inclusive) to keep the scan small.

cursor · String

The cursor to use for pagination.

direction · RankingDirection

The order to receive the token events. Can be DESC (default) or ASC. See RankingDirection

Show Properties

ASC · enum

DESC · enum

​

Example

Test this query in the Explorer →

{
  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

​

Troubleshooting Tips

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.

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.

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.

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.

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.

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.

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.

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.

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: Build a comprehensive token detail page with price, holders, trades, and real-time updates
• Events: Build a token swap list with filtering, pagination, and real-time updates