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

# 池與流動性

> DEX 池與流動性資料的查詢範例

本文介紹用於 DEX 池子與流動性分析的 Cube：

* **DEXPoolEvents**（DWD）— 流動性新增/移除事件，含逐事件儲備與價格
* **DEXPools**（DWS）— 池子**快照**（當前流動性與價格，定期重新整理）
* **TokenSupplyUpdates**（DWD）— 代幣供應量、市值與 FDV 更新

<Note>
  示例使用 **Solana** 與 **EVM** [鏈分組](/zh-Hant/graphql/schema/chain-groups)：`Solana { ... }` 用於 Solana，`EVM(network: eth | bsc | polygon) { ... }` 用於 EVM 鏈（含 Polygon）。
</Note>

***

## 如何獲取某代幣的流動性池？

在快照中查詢將某代幣列為 **token A** 的 DEX 池子。若資產僅作為 token B 出現，需用 `tokenB` 再查一次（或使用 `where`）；需要**事件級**行與完整交易對上下文時，請用 **DEXPoolEvents**。

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

<Tip>
  [在 GraphQL IDE 中開啟](https://ide.chainstream.io) — 將上方查詢貼上進去即可互動執行，並享受自動補全與 schema 瀏覽。
</Tip>

<Tip>
  將 `TOKEN_ADDRESS` 替換為代幣 mint（Solana）或合約地址（EVM）。再用 `tokenB: {is: "TOKEN_ADDRESS"}` 查詢一次，可包含該代幣作為報價側的池子。
</Tip>

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                    | 說明             |
    | :-------------------- | :------------- |
    | `Pool.Address`        | 流動性池 / 市場地址    |
    | `Pool.ProgramAddress` | DEX 程式或工廠合約地址  |
    | `Pool.TokenAAddress`  | 基礎側代幣地址        |
    | `Pool.TokenBAddress`  | 報價側代幣地址        |
    | `Pool.LiquidityUSD`   | 池子總流動性（USD，快照） |
    | `Pool.LastUpdated`    | 該快照行上次更新時間     |
  </Accordion>

  <Accordion title="自定義提示">
    * **按流動性過濾**：新增 `where: {Pool: {LiquidityUSD: {gt: 10000}}}` 篩選超過某 USD 深度的池子
    * **指定 DEX**：新增 `where: {Pool: {ProgramAddress: {is: "DEX_PROGRAM_OR_FACTORY_ADDRESS"}}}`
    * **更多池子**：提高 `count` 以發現該代幣的更多池子
    * **逐事件儲備**：對 **DEXPoolEvents** 使用 `tokenAddress` / `poolAddress` 與 `orderBy: {descending: Block_Time}` 檢視加/減流動性歷史
  </Accordion>
</AccordionGroup>

***

## 如何獲取某個池子的詳情？

按地址讀取單個池子的**最新快照**。**DEXPools** 不按行暴露區塊時間線 — 歷史儲備序列請用 **DEXPoolEvents**。

```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="關鍵欄位">
    | 欄位                                          | 說明           |
    | :------------------------------------------ | :----------- |
    | `Pool.TokenAAddress` / `Pool.TokenBAddress` | 交易對代幣地址      |
    | `Pool.LiquidityUSD`                         | 總流動性（USD，快照） |
    | `Pool.LastUpdated`                          | 該池快照上次重新整理時間 |
  </Accordion>

  <Accordion title="自定義提示">
    * **儲備歷史**：查詢 **DEXPoolEvents**，`poolAddress: {is: "POOL_ADDRESS"}` 且 `orderBy: {descending: Block_Time}`
    * **事件時間範圍**：在 **DEXPoolEvents** 上新增 `where: {Block: {Time: {since: "2025-03-01T00:00:00Z"}}}` 限定加/減流動性時段
  </Accordion>
</AccordionGroup>

<Info>
  `poolAddress` 選擇器按 `Pool.Address` 過濾。**DEXPools**（快照）與 **DEXPoolEvents**（事件）均支援。
</Info>

***

## 如何對池子排序或讀取快照流動性？

**DEXPools**（DWS）儲存**當前狀態**行（通常每隔數分鐘重新整理）。可用其按 `LiquidityUSD` 對池子排序，並在不掃原始事件的情況下對比各 DEX 程式。

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

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                                          | 說明          |
    | :------------------------------------------ | :---------- |
    | `Pool.Address`                              | 池子地址        |
    | `Pool.ProgramAddress`                       | DEX 程式 / 工廠 |
    | `Pool.TokenAAddress` / `Pool.TokenBAddress` | 交易對代幣       |
    | `Pool.LiquidityUSD`                         | 快照流動性（USD）  |
    | `Pool.LastUpdated`                          | 快照新鮮度       |
  </Accordion>

  <Accordion title="自定義提示">
    * **按流動性排序**：客戶端按 `LiquidityUSD` 排序，或在 schema 支援時對池快照使用 `orderBy`
    * **活躍池子**：優先選擇 `LastUpdated` 較新的池子
    * **對比 DEX**：按 `Pool.ProgramAddress` 分組或過濾
  </Accordion>
</AccordionGroup>

<Tip>
  **DEXPoolEvents**（DWD）適合儲備與每筆流動性事件的**時間序列**。**DEXPools**（DWS）針對**最新**池子狀態與發現做了最佳化。
</Tip>

***

## 如何獲取代幣供應量與市值？

使用 **TokenSupplyUpdates** 獲取與供應事件關聯的供應量、市值、價格與 FDV。

```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="關鍵欄位">
    | 欄位                                       | 說明           |
    | :--------------------------------------- | :----------- |
    | `TokenSupplyUpdate.Currency.MintAddress` | 代幣地址         |
    | `TokenSupplyUpdate.Currency.Decimals`    | 代幣小數位        |
    | `TokenSupplyUpdate.PostBalance`          | 事件後的當前供應量    |
    | `TokenSupplyUpdate.MarketCapInUSD`       | 市值（USD）      |
    | `TokenSupplyUpdate.PriceInUSD`           | 供應事件發生時的代幣價格 |
    | `TokenSupplyUpdate.FDVInUSD`             | 完全稀釋估值（FDV）  |
    | `TokenSupplyUpdate.TotalSupply`          | 代幣總供應量       |
  </Accordion>

  <Accordion title="自定義提示">
    * **供應歷史**：提高 `count` 檢視供應量如何隨時間變化（鑄造/銷燬事件）
    * **市值歷史**：查詢多條供應更新以繪製市值曲線
    * **與價格結合**：將 `PriceInUSD` 與 `TotalSupply` 聯用以核對市值計算
  </Accordion>
</AccordionGroup>

<Info>
  本頁透過 **TokenSupplyUpdates** 提供與供應相關的市值、價格與 FDV。更多代幣指標與彙總見 [OHLC 與統計](/zh-Hant/graphql/examples/ohlc-stats)。
</Info>

***

## 多鏈示例

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

***

## 後續步驟

<CardGroup cols={2}>
  <Card title="DEX 成交" icon="arrow-right-arrow-left" href="/zh-Hant/graphql/examples/dex-trades">
    查詢 DEX 交易資料 — 代幣成交、錢包活動與頭部交易者。
  </Card>

  <Card title="轉賬" icon="paper-plane" href="/zh-Hant/graphql/examples/transfers">
    跟蹤錢包之間的鏈上代幣轉賬。
  </Card>

  <Card title="餘額與持幣者" icon="wallet" href="/zh-Hant/graphql/examples/balance-holders">
    查詢錢包餘額、餘額歷史與頭部持幣者。
  </Card>

  <Card title="OHLC 與統計" icon="chart-candlestick" href="/zh-Hant/graphql/examples/ohlc-stats">
    獲取 K 線、成交統計、市值與代幣後設資料。
  </Card>
</CardGroup>