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

# 餘額與持有人

> 錢包餘額、餘額歷史與代幣持有人的查詢範例

本文介紹用於錢包與持幣者分析的 Cube：

* **BalanceUpdates**（DWD）— 錢包維度的逐事件餘額變動
* **TokenHolders**（DWS）— 代幣當前持幣者快照
* **WalletTokenPnL**（DWS）— 錢包按代幣的盈虧（PnL）

<Note>
  以下示例均使用 `network: sol`（Solana）。其他支援的鏈可改為 `eth`、`bsc` 或 `polygon`。
</Note>

***

## 如何獲取錢包的代幣餘額？

查詢錢包當前代幣餘額。以下查詢返回該錢包持有的每種代幣的最新一條餘額更新事件。

```graphql theme={null}
query {
  Solana {
    BalanceUpdates(
      limit: {count: 50}
      ownerAddress: {is: "WALLET_ADDRESS"}
    ) {
      BalanceUpdate {
        Currency { MintAddress }
        Account { Owner }
        PostBalance
        PostBalanceInUSD
      }
      Block { Time }
    }
  }
}
```

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

<Tip>
  將 `WALLET_ADDRESS` 替換為要檢視的錢包。`ownerAddress` 選擇器按錢包所有者過濾餘額更新事件。
</Tip>

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                                   | 說明         |
    | :----------------------------------- | :--------- |
    | `BalanceUpdate.Currency.MintAddress` | 代幣地址       |
    | `BalanceUpdate.Account.Owner`        | 錢包所有者地址    |
    | `BalanceUpdate.PostBalance`          | 更新後的代幣餘額   |
    | `BalanceUpdate.PostBalanceInUSD`     | 餘額的 USD 價值 |
    | `Block.Time`                         | 餘額更新時間戳    |
  </Accordion>

  <Accordion title="自定義提示">
    * **提高 limit**：將 `count` 設為 `200` 以覆蓋更多代幣（持倉較多的錢包）
    * **按價值過濾**：新增 `where: {BalanceUpdate: {PostBalanceInUSD: {gt: 1}}}` 排除粉塵餘額
  </Accordion>
</AccordionGroup>

***

## 如何獲取餘額變動歷史？

跟蹤某錢包對特定代幣的餘額如何隨時間變化。

```graphql theme={null}
query {
  Solana {
    BalanceUpdates(
      limit: {count: 20}
      ownerAddress: {is: "WALLET_ADDRESS"}
      tokenAddress: {is: "TOKEN_ADDRESS"}
      orderBy: {descending: Block_Time}
    ) {
      BalanceUpdate {
        PreBalance
        PostBalance
        PostBalanceInUSD
      }
      Block { Time }
      Transaction { Hash }
    }
  }
}
```

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                               | 說明            |
    | :------------------------------- | :------------ |
    | `BalanceUpdate.PreBalance`       | 事件前的餘額        |
    | `BalanceUpdate.PostBalance`      | 事件後的餘額        |
    | `BalanceUpdate.PostBalanceInUSD` | 更新後餘額的 USD 價值 |
    | `Block.Time`                     | 餘額變動發生時間      |
    | `Transaction.Hash`               | 導致變動的交易       |
  </Accordion>

  <Accordion title="自定義提示">
    * **識別累積**：對比 `PreBalance` 與 `PostBalance` — 當 `PostBalance > PreBalance` 時表示在累積
    * **時間範圍**：新增 `where: {Block: {Time: {since: "2025-03-01T00:00:00Z"}}}` 限定時段
    * **更長曆史**：將 `count` 提高到最多 `10000` 以獲取完整餘額歷史
  </Accordion>
</AccordionGroup>

<Info>
  `PostBalance` 與 `PreBalance` 的差值表示該事件的淨變動。正增量表示代幣流入；負增量表示流出。
</Info>

***

## 如何獲取代幣頭部持幣者？

按餘額排序獲取某代幣的頭部持幣者。

```graphql theme={null}
query {
  Solana {
    TokenHolders(
      limit: {count: 100}
      tokenAddress: {is: "TOKEN_ADDRESS"}
    ) {
      Token { Address }
      Holder { Address }
      LatestBalance
      LatestBalanceUSD
      FirstSeen
      LastSeen
    }
  }
}
```

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                 | 說明             |
    | :----------------- | :------------- |
    | `Token.Address`    | 代幣地址           |
    | `Holder.Address`   | 持幣者錢包地址        |
    | `LatestBalance`    | 當前代幣餘額         |
    | `LatestBalanceUSD` | 當前餘額的 USD 價值   |
    | `FirstSeen`        | 該持幣者首次持有該代幣的時間 |
    | `LastSeen`         | 涉及該代幣的最近一筆交易時間 |
  </Accordion>

  <Accordion title="自定義提示">
    * **巨鯨閾值**：新增 `where: {LatestBalanceUSD: {gt: 10000}}` 僅顯示大額持幣者
    * **活躍持幣者**：新增 `where: {LastSeen: {after: "2025-03-01T00:00:00Z"}}` 過濾近期仍活躍的持幣者
    * **持幣者數量**：使用 `count` 指標獲取持幣者總數
  </Accordion>
</AccordionGroup>

<Tip>
  **TokenHolders** Cube 屬於 DWS（彙總）層表 — 已預聚合，查詢比逐條掃餘額更新快得多。適合持幣排名與分佈分析。
</Tip>

***

## 如何獲取錢包盈虧（PnL）？

獲取錢包按代幣的盈虧資料，包含買賣成交額與成交筆數。

```graphql theme={null}
query {
  Solana {
    WalletTokenPnL(
      limit: {count: 20}
      walletAddress: {is: "WALLET_ADDRESS"}
    ) {
      Wallet { Address }
      Token { Address }
      BuyVolumeUSDState
      SellVolumeUSDState
      BuyCountState
      SellCountState
      FirstTradeState
      LastTradeState
    }
  }
}
```

<AccordionGroup>
  <Accordion title="關鍵欄位">
    | 欄位                   | 說明             |
    | :------------------- | :------------- |
    | `Wallet.Address`     | 錢包地址           |
    | `Token.Address`      | 代幣地址           |
    | `BuyVolumeUSDState`  | 買入該代幣累計花費的 USD |
    | `SellVolumeUSDState` | 賣出該代幣累計收到的 USD |
    | `BuyCountState`      | 買入成交筆數         |
    | `SellCountState`     | 賣出成交筆數         |
    | `FirstTradeState`    | 首筆成交時間戳        |
    | `LastTradeState`     | 最近一筆成交時間戳      |
  </Accordion>

  <Accordion title="自定義提示">
    * **計算 PnL**：`SellVolumeUSDState - BuyVolumeUSDState` 為各代幣已實現盈虧
    * **仍在持倉的代幣**：篩選 `SellCountState < BuyCountState` 可找到錢包仍持有的代幣
    * **高頻交易代幣**：按 `BuyCountState` 或 `SellCountState` 排序可找到交易最頻繁的代幣
  </Accordion>
</AccordionGroup>

<Info>
  **WalletTokenPnL** Cube 使用 `walletAddress` 選擇器（不是 `ownerAddress`）。提供累計交易指標 — 適合組合分析與業績排行。
</Info>

***

## 多鏈示例

<Tabs>
  <Tab title="Solana">
    ```graphql theme={null}
    query {
      Solana {
        BalanceUpdates(
          limit: {count: 10}
          ownerAddress: {is: "WALLET_ADDRESS"}
        ) {
          BalanceUpdate {
            Currency { MintAddress }
            PostBalance
            PostBalanceInUSD
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Ethereum">
    ```graphql theme={null}
    query {
      EVM(network: eth) {
        BalanceUpdates(
          limit: {count: 10}
          ownerAddress: {is: "WALLET_ADDRESS"}
        ) {
          BalanceUpdate {
            Currency { MintAddress }
            PostBalance
            PostBalanceInUSD
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="BSC">
    ```graphql theme={null}
    query {
      EVM(network: bsc) {
        BalanceUpdates(
          limit: {count: 10}
          ownerAddress: {is: "WALLET_ADDRESS"}
        ) {
          BalanceUpdate {
            Currency { MintAddress }
            PostBalance
            PostBalanceInUSD
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Polygon">
    ```graphql theme={null}
    query {
      EVM(network: polygon) {
        BalanceUpdates(
          limit: {count: 10}
          ownerAddress: {is: "WALLET_ADDRESS"}
        ) {
          BalanceUpdate {
            Currency { MintAddress }
            PostBalance
            PostBalanceInUSD
          }
        }
      }
    }
    ```
  </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="droplet" href="/zh-Hant/graphql/examples/pools-liquidity">
    探索 DEX 池子與流動性資料。
  </Card>

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