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

# Events

> Fetch onchain token events like swaps, mints, and burns with the Codex API, with filtering, sorting, and real-time updates over WebSockets.

In this recipe we'll show you how to use the Codex api to fetch a list of swaps for a token, complete with filtering, sorting, and realtime updates.

This data powers the transactions tables view on [Defined.fi](https://www.defined.fi/token/base/0x940181a94a35a4569e4529a3cdfb74e38fd98631/0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d).

![Swap](https://mintcdn.com/codex-dfdf2708/sIg_rUgIrhUCd0wd/images/swap-list.png?fit=max\&auto=format\&n=sIg_rUgIrhUCd0wd\&q=85\&s=46131d7c83e9240f827bdc7cdf49a61c)

## Queries

To get a list of swaps for a token, you can use the [`getTokenEvents`](https://docs.codex.io/api-reference/queries/gettokenevents) query.

For example, for the WBNB token on the BNB chain (networkId 56), you can use the following query:

> [accordion] Swaps
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query Events {
>   getTokenEvents(
>     query: {
>       address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c"
>       networkId: 56
>     }
>   ) {
>     items {
>       id
>       token0Address
>       token1Address
>       token0SwapValueUsd
>       token1SwapValueUsd
>       transactionHash
>     }
>   }
> }
> ```

To get more (paginate), you can use the `cursor` argument to get the next page of results.

Modify the query to include the cursor like this:

> [accordion] Paginated
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query PaginatedEvents {
>   getTokenEvents(
>     cursor: "eyJpdiI6ImNhYmI1Y2UzMmUyYjRmYzRhOGU4NWM5Njc1NzFjZGEzIiwiY29udGVudCI6ImU4ZGNiNTI3YTRiZDJmYTRlNDNjNzE0ZTM3MGU1MDdjZjE5YjhiNTM4ZWE0NjUxM2MxMzlmYjA0OTQ4YTZjNTA1MmVmM2M1ZTdiNTNhOWIyZDczY2Q2NjYxYjM2MTllZTQ1ZDE2ZTJkMDJmYjllZTU2N2YwOTQ3OWNhYmY1NzRjZDNhZTJlM2IwMDQ3ZjZkZGQzODE1Mzk0YTNkMWExMzBiZTNkZTQ4MGUyOWQyNjRiYmFlNjMwMjQ1NzgwOGFhM2RhZDU1YmY0ZjNhZGFlNWYyNDM2NGJhMjY1OWZlZjI0MzQifQ=="
>     query: {
>       address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c"
>       networkId: 56
>     }
>   ) {
>     cursor
>     items {
>       id
>       token0Address
>       token1Address
>       token0SwapValueUsd
>       token1SwapValueUsd
>       transactionHash
>       timestamp
>       blockNumber
>     }
>   }
> }
> ```

Now you know how to use a paginated cursor to fetch more results.

This pattern is used in many places in the Codex API, see [`getTokenEventsForMaker`](https://docs.codex.io/api-reference/queries/gettokeneventsformaker), [holders](https://docs.codex.io/api-reference/queries/holders.md) for an example.

## Realtime Updates

To get realtime updates, you can use the [`onTokenEventsCreated`](https://docs.codex.io/api-reference/subscriptions/ontokeneventscreated) subscription.

> [accordion] Subscription
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> subscription TokenEventsCreated {
>   onTokenEventsCreated(
>     input: {
>       tokenAddress: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c"
>       networkId: 56
>     }
>   ) {
>     events {
>       id
>       token0Address
>       token1Address
>       token0SwapValueUsd
>       token1SwapValueUsd
>       transactionHash
>       timestamp
>       blockNumber
>     }
>   }
> }
> ```

Now you've got all you need to build a fully functional swap list view.

## Trade source

Each swap can carry a `tradeSource` object identifying the app the trade was placed through — a trading terminal, wallet, or interface such as Axiom, Phantom, or Fomo — as distinct from the exchange it settled on. It's the same signal that powers "traded via Fomo" style labeling in trade feeds.

> [accordion] Swaps with trade source
>
> [Test this query in the Explorer →](https://docs.codex.io/explore.md)
>
> ```graphql theme={null} theme={null}
> query EventsWithTradeSource {
>   getTokenEvents(
>     query: {
>       address: "So11111111111111111111111111111111111111112"
>       networkId: 1399811149
>     }
>   ) {
>     items {
>       transactionHash
>       eventDisplayType
>       maker
>       tradeSource {
>         id
>         displayName
>       }
>     }
>   }
> }
> ```

The `tradeSource` object has two fields:

* `id` — a stable identifier for the app, safe to key on (e.g. `fomo`, `axiom`, `phantom`).
* `displayName` — a human-readable name for the app (e.g. `Fomo`, `Axiom`, `Phantom`). Null if the identifier has no registry entry yet.

`tradeSource` is available on every operation that returns events, including the [`onTokenEventsCreated`](https://docs.codex.io/api-reference/subscriptions/ontokeneventscreated) subscription, so live trade feeds carry the same attribution.

> [!NOTE]
>
> On events, `tradeSource` is populated for swaps on **Solana and EVM networks**, and is `null` for the majority of events since most on-chain trades carry no identifying signal. Check for a non-null `tradeSource` before reading its fields, and filter it out when you only want attributed trades.
>
> Trade source is also tracked at the wallet level, where it is **not** limited to Solana — see [Filter by Trade Source](https://docs.codex.io/recipes/wallets/discover-traders.md#filter-by-trade-source) for filtering wallets by the apps they trade through.

See more event queries in the [api reference](https://docs.codex.io/api-reference/introduction.md), like [getTokenEventsForMaker](https://docs.codex.io/api-reference/queries/gettokeneventsformaker.md), [getEventLabels](https://docs.codex.io/api-reference/queries/geteventlabels.md) for an example.

And more subscriptions like

<ul>
  <li>[getTokenEvents](https://docs.codex.io/api-reference/queries/gettokenevents.md)</li>
  <li>[onTokenEventsCreated](https://docs.codex.io/api-reference/subscriptions/ontokeneventscreated.md)</li>
  <li>[onEventsCreatedByMaker](https://docs.codex.io/api-reference/subscriptions/oneventscreatedbymaker.md)</li>
  <li>[onEventsCreated](https://docs.codex.io/api-reference/subscriptions/oneventscreated.md)</li>
  <li>[onUnconfirmedEventsCreated](https://docs.codex.io/api-reference/subscriptions/onunconfirmedeventscreated)</li>
  <li>[onUnconfirmedEventsCreatedByMaker](https://docs.codex.io/api-reference/subscriptions/onunconfirmedeventscreatedbymaker)</li>
</ul>


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