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

# Pools & Liquidity

> Query examples for DEX pools and liquidity data

This page covers Cubes for DEX pool and liquidity analysis:

* **DEXPoolEvents** (DWD) — liquidity add/remove events with per-event reserves and prices
* **DEXPools** (DWS) — pool **snapshots** (current liquidity and prices, refreshed periodically)
* **TokenSupplyUpdates** (DWD) — token supply, market cap, and FDV updates

<Note>
  Examples use the **Solana** and **EVM** [Chain Groups](/en/graphql/schema/chain-groups): `Solana { ... }` for Solana, `EVM(network: eth | bsc | polygon) { ... }` for EVM chains (including Polygon).
</Note>

***

## How do I get liquidity pools for a token?

Find DEX pools that list a token as **token A** in the snapshot. Pools where the asset appears only as token B need a second query with `tokenB` (or a `where` clause); for **event-level** rows with full pair context, use **DEXPoolEvents**.

```graphql theme={null}
query {
  Solana {
    DEXPools(
      limit: {count: 10}
      tokenA: {is: "TOKEN_ADDRESS"}
    ) {
      Pool {
        Address
        ProgramAddress
        TokenAAddress
        TokenBAddress
        LiquidityUSD
        PriceAtoB
        PriceBtoA
        LastUpdated
      }
    }
  }
}
```

<Tip>
  [Open in GraphQL IDE](https://ide.chainstream.io) — paste the query above to run it interactively with auto-complete and schema exploration.
</Tip>

<Tip>
  Replace `TOKEN_ADDRESS` with the token mint (Solana) or contract address (EVM). Repeat with `tokenB: {is: "TOKEN_ADDRESS"}` to include pools where the token is the quote side.
</Tip>

<AccordionGroup>
  <Accordion title="Key fields">
    | Field                 | Description                             |
    | :-------------------- | :-------------------------------------- |
    | `Pool.Address`        | Liquidity pool / market address         |
    | `Pool.ProgramAddress` | DEX program or factory address          |
    | `Pool.TokenAAddress`  | Base-side token address                 |
    | `Pool.TokenBAddress`  | Quote-side token address                |
    | `Pool.LiquidityUSD`   | Total pool liquidity in USD (snapshot)  |
    | `Pool.LastUpdated`    | When this snapshot row was last updated |
  </Accordion>

  <Accordion title="Customization tips">
    * **Filter by liquidity**: Add `where: {Pool: {LiquidityUSD: {gt: 10000}}}` for pools above a USD depth threshold
    * **Specific DEX**: Add `where: {Pool: {ProgramAddress: {is: "DEX_PROGRAM_OR_FACTORY_ADDRESS"}}}`
    * **More pools**: Increase `count` to discover additional pools for the token
    * **Per-event reserves**: Use **DEXPoolEvents** with `tokenAddress` / `poolAddress` and `orderBy: {descending: Block_Time}` for add/remove history
  </Accordion>
</AccordionGroup>

***

## How do I get details of a specific pool?

Read the **latest snapshot** for one pool by address. **DEXPools** does not expose a block timeline per row — use **DEXPoolEvents** for historical reserve series.

```graphql theme={null}
query {
  Solana {
    DEXPools(
      limit: {count: 1}
      poolAddress: {is: "POOL_ADDRESS"}
    ) {
      Pool {
        Address
        TokenAAddress
        TokenBAddress
        ProgramAddress
        LiquidityUSD
        PriceAtoB
        PriceBtoA
        LastUpdated
      }
    }
  }
}
```

<AccordionGroup>
  <Accordion title="Key fields">
    | Field                                       | Description                         |
    | :------------------------------------------ | :---------------------------------- |
    | `Pool.TokenAAddress` / `Pool.TokenBAddress` | Pair token addresses                |
    | `Pool.LiquidityUSD`                         | Total liquidity in USD (snapshot)   |
    | `Pool.LastUpdated`                          | Last snapshot refresh for this pool |
  </Accordion>

  <Accordion title="Customization tips">
    * **Reserve history**: Query **DEXPoolEvents** with `poolAddress: {is: "POOL_ADDRESS"}` and `orderBy: {descending: Block_Time}`
    * **Time range on events**: On **DEXPoolEvents**, add `where: {Block: {Time: {since: "2025-03-01T00:00:00Z"}}}` to scope add/removes
  </Accordion>
</AccordionGroup>

<Info>
  The `poolAddress` selector filters by `Pool.Address`. It is available on **DEXPools** (snapshot) and **DEXPoolEvents** (events).
</Info>

***

## How do I rank pools or read snapshot liquidity?

**DEXPools** (DWS) stores **current-state** rows (typically refreshed every few minutes). Use it to rank pools by `LiquidityUSD` and compare DEX programs without scanning raw events.

```graphql theme={null}
query {
  Solana {
    DEXPools(
      limit: {count: 20}
      tokenA: {is: "TOKEN_ADDRESS"}
    ) {
      Pool {
        Address
        ProgramAddress
        TokenAAddress
        TokenBAddress
        LiquidityUSD
        LastUpdated
      }
    }
  }
}
```

<AccordionGroup>
  <Accordion title="Key fields">
    | Field                                       | Description               |
    | :------------------------------------------ | :------------------------ |
    | `Pool.Address`                              | Pool address              |
    | `Pool.ProgramAddress`                       | DEX program / factory     |
    | `Pool.TokenAAddress` / `Pool.TokenBAddress` | Pair tokens               |
    | `Pool.LiquidityUSD`                         | Snapshot liquidity in USD |
    | `Pool.LastUpdated`                          | How fresh the snapshot is |
  </Accordion>

  <Accordion title="Customization tips">
    * **Rank by liquidity**: Sort client-side by `LiquidityUSD`, or use `orderBy` if your schema exposes a pool snapshot ordering
    * **Active pools**: Prefer pools with recent `LastUpdated`
    * **Compare DEXes**: Group or filter by `Pool.ProgramAddress`
  </Accordion>
</AccordionGroup>

<Tip>
  **DEXPoolEvents** (DWD) is the right Cube for **time series** of reserves and every liquidity event. **DEXPools** (DWS) is optimized for **latest** pool state and discovery.
</Tip>

***

## How do I get token supply and market cap?

Use **TokenSupplyUpdates** for supply, market cap, price, and FDV tied to supply events.

```graphql theme={null}
query {
  Solana {
    TokenSupplyUpdates(
      limit: {count: 1}
      tokenAddress: {is: "TOKEN_ADDRESS"}
      orderBy: {descending: Block_Time}
    ) {
      TokenSupplyUpdate {
        Currency { MintAddress, Decimals }
        PostBalance
        MarketCapInUSD
        PriceInUSD
        FDVInUSD
        TotalSupply
      }
      Block { Time }
    }
  }
}
```

<AccordionGroup>
  <Accordion title="Key fields">
    | Field                                    | Description                                 |
    | :--------------------------------------- | :------------------------------------------ |
    | `TokenSupplyUpdate.Currency.MintAddress` | Token address                               |
    | `TokenSupplyUpdate.Currency.Decimals`    | Token decimals                              |
    | `TokenSupplyUpdate.PostBalance`          | Current supply after the event              |
    | `TokenSupplyUpdate.MarketCapInUSD`       | Market capitalization in USD                |
    | `TokenSupplyUpdate.PriceInUSD`           | Token price at the time of the supply event |
    | `TokenSupplyUpdate.FDVInUSD`             | Fully diluted valuation                     |
    | `TokenSupplyUpdate.TotalSupply`          | Total token supply                          |
  </Accordion>

  <Accordion title="Customization tips">
    * **Supply history**: Increase `count` to see how supply changed over time (mint/burn events)
    * **Market cap history**: Query multiple supply updates to chart market cap over time
    * **Combined with price**: Use `PriceInUSD` alongside `TotalSupply` to verify market cap calculations
  </Accordion>
</AccordionGroup>

<Info>
  This page uses **TokenSupplyUpdates** for supply-linked market cap, price, and FDV. For additional token metrics and summaries, see [OHLC & Statistics](/en/graphql/examples/ohlc-stats).
</Info>

***

## Multi-Chain Examples

<Tabs>
  <Tab title="Solana">
    ```graphql theme={null}
    query {
      Solana {
        DEXPools(
          limit: {count: 5}
          tokenA: {is: "TOKEN_ADDRESS"}
        ) {
          Pool { Address, LiquidityUSD, LastUpdated }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Ethereum">
    ```graphql theme={null}
    query {
      EVM(network: eth) {
        DEXPools(
          limit: {count: 5}
          tokenA: {is: "TOKEN_ADDRESS"}
        ) {
          Pool { Address, LiquidityUSD, LastUpdated }
        }
      }
    }
    ```
  </Tab>

  <Tab title="BSC">
    ```graphql theme={null}
    query {
      EVM(network: bsc) {
        DEXPools(
          limit: {count: 5}
          tokenA: {is: "TOKEN_ADDRESS"}
        ) {
          Pool { Address, LiquidityUSD, LastUpdated }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Polygon">
    ```graphql theme={null}
    query {
      EVM(network: polygon) {
        DEXPools(
          limit: {count: 5}
          tokenA: {is: "TOKEN_ADDRESS"}
        ) {
          Pool { Address, LiquidityUSD, LastUpdated }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="DEX Trades" icon="arrow-right-arrow-left" href="/en/graphql/examples/dex-trades">
    Query DEX trading data — token trades, wallet activity, and top traders.
  </Card>

  <Card title="Transfers" icon="paper-plane" href="/en/graphql/examples/transfers">
    Track on-chain token transfers between wallets.
  </Card>

  <Card title="Balances & Holders" icon="wallet" href="/en/graphql/examples/balance-holders">
    Look up wallet balances, balance history, and top holders.
  </Card>

  <Card title="OHLC & Statistics" icon="chart-candlestick" href="/en/graphql/examples/ohlc-stats">
    Fetch candlestick data, trade stats, market cap, and token metadata.
  </Card>
</CardGroup>