> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# DEX Events

> Protocol-agnostic DEX liquidity events for Avalanche

## Overview

The `avalanche.dex.events` table provides a clean, protocol-agnostic schema for DEX liquidity events on Avalanche. This unified approach allows you to analyze liquidity patterns across different DEX protocols using consistent semantics.

<Info>
  **Purpose:** One clean, protocol/chain agnostic schema for DEX liquidity events.

  **Design:**

  * Protocol-agnostic core
  * Event-agnostic semantics
  * Ownership is normalized through LP unit
  * Event-specific bits go in `event_details` (variant)
  * Liquidity specific details goes in `liquidity_details` (variant)

  **Event set (v1):** `initialize_pool | add_liquidity | remove_liquidity | swap_tokens`
</Info>

<Info>
  This table is in active development and currently available for Avalanche only.
</Info>

## Table Columns

<Tabs>
  <Tab title="Event & Transaction Context">
    | Column                     | Type           | Example              | Description                  |
    | -------------------------- | -------------- | -------------------- | ---------------------------- |
    | `chain`                    | STRING         | avalanche            | The blockchain name          |
    | `protocol`                 | STRING         | uniswap\_v3          | The DEX protocol identifier  |
    | `project`                  | STRING         | uniswap              | The project name             |
    | `event_name`               | STRING         | add\_liquidity       | event verb\_noun taxonomy    |
    | `transaction_hash`         | STRING         | 0x…                  | Transaction hash             |
    | `log_index`                | NUMBER         | 12                   | Log index within transaction |
    | `block_timestamp`          | TIMESTAMP\_NTZ | 2025-09-12T12:34:56Z | Block timestamp              |
    | `block_number`             | NUMBER         | 397…                 | Block number                 |
    | `transaction_from_address` | STRING         | 0x…                  | Transaction sender           |
    | `transaction_to_address`   | STRING         | 0x…                  | Transaction recipient        |
  </Tab>

  <Tab title="Pool Details">
    | Column                   | Type    | Example                          | Description                              |
    | ------------------------ | ------- | -------------------------------- | ---------------------------------------- |
    | `liquidity_pool_address` | STRING  | 0x…                              | v2/v3 pool, LBPair                       |
    | `event_details`          | VARIANT | `{ tick:-1, sqrt_price_x96:"…"}` | Protocol-specific details and swap state |
  </Tab>

  <Tab title="LP Unit">
    | Column              | Type    | Example                               | Description                                   |
    | ------------------- | ------- | ------------------------------------- | --------------------------------------------- |
    | `lp_unit`           | STRING  | erc20                                 | Ownership model (erc20/erc721/erc1155/custom) |
    | `id`                | VARIANT | `{pair_address:"0x", bin_id:8389407}` | Normalized identifier per unit                |
    | `event_scope`       | STRING  | position                              | Position-level vs pool-level                  |
    | `owner_address`     | STRING  | 0x…                                   | Credited LP owner (if emitted)                |
    | `sender_address`    | STRING  | 0x…                                   | Raw event actor                               |
    | `recipient_address` | STRING  | 0x…                                   | Raw event actor                               |
  </Tab>

  <Tab title="Token Details">
    | Column                             | Type    | Example  | Description          |
    | ---------------------------------- | ------- | -------- | -------------------- |
    | `amount0_raw_str, amount1_raw_str` | VARCHAR | 1000000  | Raw on-chain amounts |
    | `amount0, amount1`                 | VARCHAR | 1.000000 | Decimalized amounts  |
    | `amount0_usd, amount1_usd`         | FLOAT   | 1.02     | USD values           |
    | `token0_symbol, token1_symbol`     | VARCHAR | USDC     | Token symbols        |
  </Tab>

  <Tab title="Liquidity Placement">
    | Column              | Type    | Example                                                                                          | Description                       |
    | ------------------- | ------- | ------------------------------------------------------------------------------------------------ | --------------------------------- |
    | `liquidity_details` | VARIANT | `{kind:"tick_range", lp_unit:"erc721", tick_spacing:10, tick_lower:-887220, tick_upper:-887110}` | Where on price axis event lives   |
    | `liquidity`         | VARCHAR | 102004304                                                                                        | Only for certain events/protocols |
  </Tab>
</Tabs>

## Protocol Examples

### Uniswap V2 Family

**Protocols:** Uniswap V2, Pangolin V2, Pharaoh, Blackhole

| Event             | unit\_type | id (VARIANT)          | liquidity\_details (VARIANT)          | event\_details (VARIANT)                                               | Source                                     |
| ----------------- | ---------- | --------------------- | ------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------ |
| initialize\_pool  | erc20      | `{pair_address:"0x"}` | `{kind:"pool_wide", lp_unit:"erc20"}` | `{scope:"pool", lp_factory_address:"0x…", source_event:"PairCreated"}` | Factory `PairCreated` or Pool first `Sync` |
| add\_liquidity    | erc20      | `{pair_address:"0x"}` | `{kind:"pool_wide", lp_unit:"erc20"}` | `{scope:"pool", lp_factory_address:"0x…", source_event:"Mint"}`        | Pool `Mint`                                |
| remove\_liquidity | erc20      | `{pair_address:"0x"}` | `{kind:"pool_wide", lp_unit:"erc20"}` | `{scope:"pool", lp_factory_address:"0x…", source_event:"Burn"}`        | Pool `Burn`                                |

### Uniswap V3 Family (CLMM)

**Protocols:** Uniswap V3, Pangolin V3

| Event             | unit\_type | id (VARIANT)                                | liquidity\_details (VARIANT)                                                   | event\_details (VARIANT)                                                                           | Source            |
| ----------------- | ---------- | ------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------- |
| initialize\_pool  | erc721     | —                                           | `{kind:"tick_range", tick_spacing:10}`                                         | `{scope:"pool", lp_factory_address:"0x…", source_event:"Initialize", tick:-1, sqrt_price_x96:"…"}` | Pool `Initialize` |
| add\_liquidity    | erc721     | `{position_manager:"0xPM", token_id:12345}` | `{kind:"tick_range", tick_spacing:10, tick_lower:-887220, tick_upper:-887110}` | `{scope:"position", lp_factory_address:"0x…", source_event:"Mint"}`                                | Pool `Mint`       |
| remove\_liquidity | erc721     | `{position_manager:"0xPM", token_id:12345}` | `{kind:"tick_range", tick_spacing:10, tick_lower:-887220, tick_upper:-887110}` | `{scope:"position", lp_factory_address:"0x…", source_event:"Burn"}`                                | Pool `Burn`       |
| swap\_tokens      | erc721     | `{position_manager:"0xPM", token_id:12345}` | `{kind:"tick_range", tick_spacing:10 }`                                        | `{scope:"pool", lp_factory_address:"0x…", source_event:"Swap", tick:-1, sqrt_price_x96:"…"}`       | Pool `Swap`       |

### Trader Joe Liquidity Book (LB)

**Protocols:** Trader Joe LB v2/2.1/2.2

| Event             | unit\_type | id (VARIANT)                            | liquidity\_details (VARIANT)                    | event\_details (VARIANT)                                                                             | Source                     |
| ----------------- | ---------- | --------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------- |
| initialize\_pool  | erc1155    | —                                       | `{kind:"bin", bin_step_bps:25, bin_id:8389407}` | `{scope:"pool", lb_factory_address:"0x…", source_event:"LBPairCreated", interface_id:"0x…"}`         | Factory `LBPairCreated`    |
| add\_liquidity    | erc1155    | `{pair_address:"0xLB", bin_id:8389407}` | `{kind:"bin", bin_step_bps:25, bin_id:8389407}` | `{scope:"position", lb_factory_address:"0x…", source_event:"DepositedToBins", interface_id:"0x…"}`   | LBPair `DepositedToBins`   |
| remove\_liquidity | erc1155    | `{pair_address:"0xLB", bin_id:8389407}` | `{kind:"bin", bin_step_bps:25, bin_id:8389407}` | `{scope:"position", lb_factory_address:"0x…", source_event:"WithdrawnFromBins", interface_id:"0x…"}` | LBPair `WithdrawnFromBins` |

## Notes

* **Protocol Coverage**: Currently supports Uniswap V2/V3, Blackhole, Pangolin V2/V3, Pharaoh, Trader Joe LB, and other major Avalanche DEX protocols
* **USD Values**: USD amounts are calculated using token prices at the time of the event
* **Event Scope**: `position` for individual positions, `pool` for pool-wide events

## Use Cases

* Track liquidity provision and removal patterns across protocols
* Monitor individual LP positions and their performance
* Compare liquidity patterns between different DEX protocols
* Analyze concentration and distribution of liquidity
* Build comprehensive DEX analytics dashboards