Overview
Query wallets that have interacted with one or more tokens, with powerful filtering, ranking, and pagination on per-token activity. Ideal for building top-trader lists, holder PnL leaderboards, and smart-money detection for a token.- Filter by per-token buys, sells, volume, realized profit, and balances
- Filter by windowed stats:
1d,1w,30d,1y - Scope by
tokenIds, specificwallets, or anetworkId - Include / exclude wallets by label (e.g.
insider,sniper,bot) - Sort by any supported attribute; paginate with
limit/offset - Free-text search on wallet addresses / identity via
phrase
Returns
See TokenWalletFilterConnection and TokenWalletFilterResult for full type details.
Show View fields (TokenWalletFilterConnection)
Show View fields (TokenWalletFilterConnection)
List of matching token-wallet rows.
Show TokenWalletFilterResult
Show TokenWalletFilterResult
Wallet address.
Token contract address.
Network ID.
First transaction timestamp on this token (unix seconds).
Last transaction timestamp on this token (unix seconds).
Wallet labels (e.g.
sniper, bundler, insider, bot).Token amount bought in last 24h.
Filtered token amount sold in last 24h.
Total token amount sold in last 24h (includes unfiltered swaps).
USD amount bought in last 24h.
Filtered USD amount sold in last 24h.
Total USD amount sold in last 24h.
Realized profit in USD over last 24h.
Realized profit % over last 24h.
Buy count in last 24h.
Filtered sell count in last 24h.
Total sell count in last 24h.
Token amount bought in last 7 days.
Filtered token amount sold in last 7 days.
Total token amount sold in last 7 days.
USD amount bought in last 7 days.
Filtered USD amount sold in last 7 days.
Total USD amount sold in last 7 days.
Realized profit in USD over last 7 days.
Realized profit % over last 7 days.
Buy count in last 7 days.
Filtered sell count in last 7 days.
Total sell count in last 7 days.
Token amount bought in last 30 days.
Filtered token amount sold in last 30 days.
Total token amount sold in last 30 days.
USD amount bought in last 30 days.
Filtered USD amount sold in last 30 days.
Total USD amount sold in last 30 days.
Realized profit in USD over last 30 days.
Realized profit % over last 30 days.
Buy count in last 30 days.
Filtered sell count in last 30 days.
Total sell count in last 30 days.
Token amount bought in last 1 year.
Filtered token amount sold in last 1 year.
Total token amount sold in last 1 year.
USD amount bought in last 1 year.
Filtered USD amount sold in last 1 year.
Total USD amount sold in last 1 year.
Realized profit in USD over last 1 year.
Realized profit % over last 1 year.
Buy count in last 1 year.
Filtered sell count in last 1 year.
Total sell count in last 1 year.
Cumulative USD cost basis of tokens still held.
Cumulative amount of tokens purchased (indexed swaps).
Indexed on-chain token balance.
Live on-chain token balance (fresh query).
Live token balance in USD.
Full token metadata. See EnhancedToken.
Scammer score (0-100).
Bot score (0-100).
Backfill state of the wallet’s aggregates. See WalletAggregateBackfillState.
Number of results returned.
Current pagination offset.
Arguments
See FilterTokenWalletsInput for full details.
Show FilterTokenWalletsInput
Show FilterTokenWalletsInput
Array of token selectors in
"address:networkId" format.Restrict to specific wallet addresses.
Restrict to a specific network.
Per-token numeric filters. Each field accepts a NumberFilter with
gt, gte, lt, lte. See WalletTokenFiltersV2 for all supported fields.Free-text search against wallet address or identity fields.
Sorting criteria. See WalletTokenRanking and WalletTokenRankingAttribute for all sortable fields.
Exclude wallets tagged with any of these labels (e.g.
bot, sniper).Require wallets tagged with at least one of these labels.
Maximum number of results to return (default: 25, max: 200).
Pagination offset (default: 0).
Example
{
filterTokenWallets(input: {
tokenIds: ["0x6982508145454ce325ddbe47a25d4ec3d2311933:1"]
filtersV2: {
realizedProfitUsd30d: { gte: 10000 }
buys30d: { gte: 3 }
}
rankings: [{ attribute: realizedProfitUsd30d, direction: DESC }]
excludeLabels: ["bot"]
limit: 10
}) {
results {
address
tokenAddress
networkId
labels
realizedProfitUsd30d
realizedProfitPercentage30d
buys30d
sells30d
tokenBalance
tokenBalanceLiveUsd
token { name symbol address networkId }
}
count
offset
}
}