> ## 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）— ウォレットのトークンごとの損益

<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) — 上記クエリを貼り付けて、オートコンプリートとスキーマ探索付きで対話的に実行できます。
</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="カスタマイズのヒント">
    * **件数の増加**: 保有数の多いウォレット向けに `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（Summary）レイヤーのテーブルです — 事前集約されており、個別の残高更新を走査するよりはるかに高速にクエリできます。ホルダーランキングと分布分析に使ってください。
</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 は `ownerAddress` ではなく `walletAddress` セレクターを使います。累積的なトレーディング指標を提供し、ポートフォリオ分析やパフォーマンスランキングに適しています。
</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="/jp/graphql/examples/dex-trades">
    DEX のトレーディングデータ — トークン取引、ウォレット活動、トップトレーダーをクエリします。
  </Card>

  <Card title="送金（Transfers）" icon="paper-plane" href="/jp/graphql/examples/transfers">
    ウォレット間のオンチェーン送金を追跡します。
  </Card>

  <Card title="プールと流動性" icon="droplet" href="/jp/graphql/examples/pools-liquidity">
    DEX プールと流動性データを探索します。
  </Card>

  <Card title="OHLC と統計" icon="chart-candlestick" href="/jp/graphql/examples/ohlc-stats">
    ローソク足、取引統計、TokenSupplyUpdates、トークンメタデータを取得します。
  </Card>
</CardGroup>