Balances & Holders

This page covers four Cubes for wallet and holder analytics:

BalanceUpdates (DWD) — per-event balance changes for a wallet
TokenHolders (DWS) — current holder snapshots for a token
WalletTokenPnL (DWS) — per-token profit & loss for a wallet

All examples below use network: sol (Solana). Replace with eth, bsc, or polygon for other supported chains.

How do I get a wallet’s token balances?

Get current token balances for a wallet. This query returns the latest balance update event for each token the wallet holds.

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

Open in GraphQL IDE — paste the query above to run it interactively with auto-complete and schema exploration.

Replace WALLET_ADDRESS with the wallet you want to inspect. The ownerAddress selector filters balance update events by wallet owner.

Key fields

Field	Description
`BalanceUpdate.Currency.MintAddress`	Token address
`BalanceUpdate.Account.Owner`	Wallet owner address
`BalanceUpdate.PostBalance`	Token balance after the update
`BalanceUpdate.PostBalanceInUSD`	Balance value in USD
`Block.Time`	Timestamp of the balance update

Customization tips

Increase limit: Set count: 200 to retrieve more tokens (wallets with many holdings)
Filter by value: Add where: {BalanceUpdate: {PostBalanceInUSD: {gt: 1}}} to exclude dust balances

How do I get balance change history?

Track how a wallet’s balance for a specific token changes over time.

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

Key fields

Field	Description
`BalanceUpdate.PreBalance`	Balance before the event
`BalanceUpdate.PostBalance`	Balance after the event
`BalanceUpdate.PostBalanceInUSD`	Post-balance value in USD
`Block.Time`	When the balance changed
`Transaction.Hash`	Transaction that caused the change

Customization tips

Detect accumulation: Compare PreBalance and PostBalance — when PostBalance > PreBalance, the wallet is accumulating
Time range: Add where: {Block: {Time: {since: "2025-03-01T00:00:00Z"}}} to scope to a specific period
Larger history: Increase count to up to 10000 for comprehensive balance history

The difference between PostBalance and PreBalance shows the net change per event. A positive delta means tokens flowed in; a negative delta means tokens flowed out.

How do I get a token’s top holders?

Get the top holders for a token, ranked by balance.

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

Key fields

Field	Description
`Token.Address`	Token address
`Holder.Address`	Holder wallet address
`LatestBalance`	Current token balance
`LatestBalanceUSD`	Current balance in USD
`FirstSeen`	When this holder first acquired the token
`LastSeen`	Most recent transaction involving this token

Customization tips

Whale threshold: Add where: {LatestBalanceUSD: {gt: 10000}} to only show large holders
Active holders: Add where: {LastSeen: {after: "2025-03-01T00:00:00Z"}} to filter to recently active holders
Holder count: Use count metric to get the total number of holders

The TokenHolders Cube is a DWS (Summary) layer table — it’s pre-aggregated and much faster to query than scanning individual balance updates. Use it for holder rankings and distribution analysis.

How do I get wallet profit and loss?

Get per-token profit and loss data for a wallet, including buy/sell volumes and trade counts.

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

Key fields

Field	Description
`Wallet.Address`	Wallet address
`Token.Address`	Token address
`BuyVolumeUSDState`	Total USD spent buying this token
`SellVolumeUSDState`	Total USD received selling this token
`BuyCountState`	Number of buy trades
`SellCountState`	Number of sell trades
`FirstTradeState`	Timestamp of the first trade
`LastTradeState`	Timestamp of the most recent trade

Customization tips

Calculate PnL: SellVolumeUSDState - BuyVolumeUSDState gives the realized PnL for each token
Active positions: Filter for tokens where SellCountState < BuyCountState to find tokens the wallet is still holding
High-activity tokens: Sort by BuyCountState or SellCountState to find the most frequently traded tokens

The WalletTokenPnL Cube uses the walletAddress selector (not ownerAddress). It provides cumulative trading metrics — ideal for portfolio analysis and performance leaderboards.

Multi-Chain Examples

Solana
Ethereum
BSC
Polygon

query {
  Solana {
    BalanceUpdates(
      limit: {count: 10}
      ownerAddress: {is: "WALLET_ADDRESS"}
    ) {
      BalanceUpdate {
        Currency { MintAddress }
        PostBalance
        PostBalanceInUSD
      }
    }
  }
}

query {
  EVM(network: eth) {
    BalanceUpdates(
      limit: {count: 10}
      ownerAddress: {is: "WALLET_ADDRESS"}
    ) {
      BalanceUpdate {
        Currency { MintAddress }
        PostBalance
        PostBalanceInUSD
      }
    }
  }
}

query {
  EVM(network: bsc) {
    BalanceUpdates(
      limit: {count: 10}
      ownerAddress: {is: "WALLET_ADDRESS"}
    ) {
      BalanceUpdate {
        Currency { MintAddress }
        PostBalance
        PostBalanceInUSD
      }
    }
  }
}

query {
  EVM(network: polygon) {
    BalanceUpdates(
      limit: {count: 10}
      ownerAddress: {is: "WALLET_ADDRESS"}
    ) {
      BalanceUpdate {
        Currency { MintAddress }
        PostBalance
        PostBalanceInUSD
      }
    }
  }
}

Next Steps

DEX Trades

Query DEX trading data — token trades, wallet activity, and top traders.

Transfers

Track on-chain token transfers between wallets.

Pools & Liquidity

Explore DEX pool and liquidity data.

OHLC & Statistics

Fetch candlestick data, trade stats, TokenSupplyUpdates, and token metadata.

Getting Started

GraphQL IDE

Schema & Data Model

Query Examples

Billing & Credits

How do I get a wallet’s token balances?

How do I get balance change history?

How do I get a token’s top holders?

How do I get wallet profit and loss?

Multi-Chain Examples

Next Steps

DEX Trades

Transfers

Pools & Liquidity

OHLC & Statistics

​How do I get a wallet’s token balances?

​How do I get balance change history?

​How do I get a token’s top holders?

​How do I get wallet profit and loss?

​Multi-Chain Examples

​Next Steps

DEX Trades

Transfers

Pools & Liquidity

OHLC & Statistics

How do I get a wallet’s token balances?

How do I get balance change history?

How do I get a token’s top holders?

How do I get wallet profit and loss?

Multi-Chain Examples

Next Steps