> ## 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** [Chain Groups](/ko/graphql/schema/chain-groups)를 사용합니다: Solana는 `Solana { ... }`, EVM 체인(Polygon 포함)은 `EVM(network: eth | bsc | 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) — 위 쿼리를 붙여넣어 자동 완성과 스키마 탐색으로 대화형 실행할 수 있습니다.
</Tip>

<Tip>
  `TOKEN_ADDRESS`를 토큰 mint(Solana) 또는 컨트랙트 주소(EVM)로 바꿉니다. 토큰이 quote 측인 풀까지 포함하려면 `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`로 정렬하거나, 스키마에 풀 스냅샷 `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`를 늘려 시간에 따른 공급 변화(mint/burn) 확인
    * **시가총액 이력**: 여러 공급 업데이트를 조회해 시가총액 차트
    * **가격과 함께**: 시가총액 검증에 `PriceInUSD`와 `TotalSupply` 병행
  </Accordion>
</AccordionGroup>

<Info>
  이 페이지의 **TokenSupplyUpdates**는 공급과 연계된 시가총액·가격·FDV용입니다. 추가 토큰 메트릭·요약은 [OHLC & Statistics](/ko/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="/ko/graphql/examples/dex-trades">
    DEX 거래 데이터 — 토큰 거래, 지갑 활동, 상위 트레이더를 조회합니다.
  </Card>

  <Card title="전송" icon="paper-plane" href="/ko/graphql/examples/transfers">
    지갑 간 온체인 토큰 전송을 추적합니다.
  </Card>

  <Card title="잔액 및 홀더" icon="wallet" href="/ko/graphql/examples/balance-holders">
    지갑 잔액, 잔액 이력, 상위 홀더를 조회합니다.
  </Card>

  <Card title="OHLC 및 통계" icon="chart-candlestick" href="/ko/graphql/examples/ohlc-stats">
    캔들 데이터, 거래 통계, 시가총액, 토큰 메타데이터를 가져옵니다.
  </Card>
</CardGroup>