> ## 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="/cn/graphql/examples/dex-trades">
    查询 DEX 交易数据 — 代币成交、钱包活动与头部交易者。
  </Card>

  <Card title="转账" icon="paper-plane" href="/cn/graphql/examples/transfers">
    跟踪钱包之间的链上代币转账。
  </Card>

  <Card title="池子与流动性" icon="droplet" href="/cn/graphql/examples/pools-liquidity">
    探索 DEX 池子与流动性数据。
  </Card>

  <Card title="OHLC 与统计" icon="chart-candlestick" href="/cn/graphql/examples/ohlc-stats">
    获取 K 线、成交统计、TokenSupplyUpdates 与代币元数据。
  </Card>
</CardGroup>