余额与持有人

本文介绍用于钱包与持币者分析的 Cube：

BalanceUpdates（DWD）— 钱包维度的逐事件余额变动
TokenHolders（DWS）— 代币当前持币者快照
WalletTokenPnL（DWS）— 钱包按代币的盈亏（PnL）

以下示例均使用 network: sol（Solana）。其他支持的链可改为 eth、bsc 或 polygon。

如何获取钱包的代币余额？

查询钱包当前代币余额。以下查询返回该钱包持有的每种代币的最新一条余额更新事件。

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

在 GraphQL IDE 中打开 — 将上方查询粘贴进去即可交互运行，并享受自动补全与 schema 浏览。

将 WALLET_ADDRESS 替换为要查看的钱包。ownerAddress 选择器按钱包所有者过滤余额更新事件。

关键字段

字段	说明
`BalanceUpdate.Currency.MintAddress`	代币地址
`BalanceUpdate.Account.Owner`	钱包所有者地址
`BalanceUpdate.PostBalance`	更新后的代币余额
`BalanceUpdate.PostBalanceInUSD`	余额的 USD 价值
`Block.Time`	余额更新时间戳

自定义提示

提高 limit：将 count 设为 200 以覆盖更多代币（持仓较多的钱包）
按价值过滤：添加 where: {BalanceUpdate: {PostBalanceInUSD: {gt: 1}}} 排除粉尘余额

如何获取余额变动历史？

跟踪某钱包对特定代币的余额如何随时间变化。

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

关键字段

字段	说明
`BalanceUpdate.PreBalance`	事件前的余额
`BalanceUpdate.PostBalance`	事件后的余额
`BalanceUpdate.PostBalanceInUSD`	更新后余额的 USD 价值
`Block.Time`	余额变动发生时间
`Transaction.Hash`	导致变动的交易

自定义提示

识别累积：对比 PreBalance 与 PostBalance — 当 PostBalance > PreBalance 时表示在累积
时间范围：添加 where: {Block: {Time: {since: "2025-03-01T00:00:00Z"}}} 限定时段
更长历史：将 count 提高到最多 10000 以获取完整余额历史

PostBalance 与 PreBalance 的差值表示该事件的净变动。正增量表示代币流入；负增量表示流出。

如何获取代币头部持币者？

按余额排序获取某代币的头部持币者。

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

关键字段

字段	说明
`Token.Address`	代币地址
`Holder.Address`	持币者钱包地址
`LatestBalance`	当前代币余额
`LatestBalanceUSD`	当前余额的 USD 价值
`FirstSeen`	该持币者首次持有该代币的时间
`LastSeen`	涉及该代币的最近一笔交易时间

自定义提示

巨鲸阈值：添加 where: {LatestBalanceUSD: {gt: 10000}} 仅显示大额持币者
活跃持币者：添加 where: {LastSeen: {after: "2025-03-01T00:00:00Z"}} 过滤近期仍活跃的持币者
持币者数量：使用 count 指标获取持币者总数

TokenHolders Cube 属于 DWS（汇总）层表 — 已预聚合，查询比逐条扫余额更新快得多。适合持币排名与分布分析。

如何获取钱包盈亏（PnL）？

获取钱包按代币的盈亏数据，包含买卖成交额与成交笔数。

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

关键字段

字段	说明
`Wallet.Address`	钱包地址
`Token.Address`	代币地址
`BuyVolumeUSDState`	买入该代币累计花费的 USD
`SellVolumeUSDState`	卖出该代币累计收到的 USD
`BuyCountState`	买入成交笔数
`SellCountState`	卖出成交笔数
`FirstTradeState`	首笔成交时间戳
`LastTradeState`	最近一笔成交时间戳

自定义提示

计算 PnL：SellVolumeUSDState - BuyVolumeUSDState 为各代币已实现盈亏
仍在持仓的代币：筛选 SellCountState < BuyCountState 可找到钱包仍持有的代币
高频交易代币：按 BuyCountState 或 SellCountState 排序可找到交易最频繁的代币

WalletTokenPnL Cube 使用 walletAddress 选择器（不是 ownerAddress）。提供累计交易指标 — 适合组合分析与业绩排行。

多链示例

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

后续步骤

DEX 成交

查询 DEX 交易数据 — 代币成交、钱包活动与头部交易者。

转账

跟踪钱包之间的链上代币转账。

池子与流动性

探索 DEX 池子与流动性数据。

OHLC 与统计

获取 K 线、成交统计、TokenSupplyUpdates 与代币元数据。

快速开始

GraphQL IDE

Schema 与数据模型

查询示例

计费与额度

如何获取钱包的代币余额？

如何获取余额变动历史？

如何获取代币头部持币者？

如何获取钱包盈亏（PnL）？

多链示例

后续步骤

DEX 成交

转账

池子与流动性

OHLC 与统计

​如何获取钱包的代币余额？

​如何获取余额变动历史？

​如何获取代币头部持币者？

​如何获取钱包盈亏（PnL）？

​多链示例

​后续步骤

DEX 成交

转账

池子与流动性

OHLC 与统计

如何获取钱包的代币余额？

如何获取余额变动历史？

如何获取代币头部持币者？

如何获取钱包盈亏（PnL）？

多链示例

后续步骤