Portfolio Data
Access complete onchain portfolio data with a single query. The portfolio query provides comprehensive access to balances across tokens, apps, and NFTs, along with detailed portfolio totals and breakdowns.
Overview
The portfolioV2 query takes an array of addresses as input, with optional parameters for an array of networks. It returns a complete view of onchain holdings including:
New portfolioV2 Query
The new portfolioV2 endpoint eliminates the need for separate balance computation jobs and provides enhanced functionality. The original portfolio query will continue to work but we recommend migrating to portfolioV2.
Portfolio Fields
tokenBalances
Access native token holdings across different networks with real-time computation built in.
Try it nowExample Variables
{
"addresses": ["0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"],
"first": 5
}
Example Query
query TokenBalances($addresses: [Address!]!, $first: Int) {
portfolioV2(addresses: $addresses) {
tokenBalances {
totalBalanceUSD
byToken(first: $first) {
totalCount
edges {
node {
symbol
tokenAddress
balance
balanceUSD
price
imgUrlV2
name
network {
name
}
}
}
}
}
}
}
Example Response
{
"data": {
"portfolioV2": {
"tokenBalances": {
"totalBalanceUSD": 292328.8286857288,
"byToken": {
"totalCount": 1223,
"edges": [
{
"node": {
"symbol": "ETH",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"balance": 17.286417826281596,
"balanceUSD": 45317.035788310255,
"price": 2621.54,
"imgUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
"name": "Ethereum",
"network": {
"name": "Base"
}
}
},
{
"node": {
"symbol": "SYNDOG",
"tokenAddress": "0x3d1d651761d535df881740ab50ba4bd8a2ec2c00",
"balance": 30000000,
"balanceUSD": 38615.1,
"price": 0.00128717,
"imgUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x3d1d651761d535df881740ab50ba4bd8a2ec2c00.png",
"name": "Synthesizer Dog",
"network": {
"name": "Base"
}
}
},
{
"node": {
"symbol": "BKIT",
"tokenAddress": "0x262a9f4e84efa2816d87a68606bb4c1ea3874bf1",
"balance": 28980487535.238518,
"balanceUSD": 28654.60195290476,
"price": 9.88755e-7,
"imgUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x262a9f4e84efa2816d87a68606bb4c1ea3874bf1.png",
"name": "Bangkit",
"network": {
"name": "Base"
}
}
},
{
"node": {
"symbol": "ERA",
"tokenAddress": "0xb82d1d9dd2ca8cfbdecdfbfef0aaebb07eb29312",
"balance": 50408655.54694379,
"balanceUSD": 13756.164212247695,
"price": 0.0002728929002963999,
"imgUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0xb82d1d9dd2ca8cfbdecdfbfef0aaebb07eb29312.png",
"name": "BASE ERA",
"network": {
"name": "Base"
}
}
},
{
"node": {
"symbol": "BNKR",
"tokenAddress": "0x22af33fe49fd1fa80c7149773dde5890d3c76f3b",
"balance": 55169518.28804873,
"balanceUSD": 10414.901662417838,
"price": 0.00018878,
"imgUrlV2": "https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x22af33fe49fd1fa80c7149773dde5890d3c76f3b.png",
"name": "BankrCoin",
"network": {
"name": "Base"
}
}
}
]
}
}
}
}
}
Key Features
- Real-time Computation: No separate computation jobs needed
- Flexible Querying: View balances by token, account, or network
- Detailed Token Data: Complete token metadata and balances
- Account-level Breakdown: See individual wallet contributions to total balances
Available Fields
Token Balance Root Fields
| Field | Description | Type |
|---|---|---|
totalBalanceUSD | Total portfolio value in USD | Float! |
byToken | Token-centric view of balances | PortfolioV2TokenBalanceByTokenConnection! |
byAccount | Account-centric view of balances | PortfolioV2TokenBalancesByAccountConnection! |
byNetwork | Network-centric view of balances | PortfolioV2TokenBalancesByNetworkConnection! |
Token Balance Node Fields
| Field | Description | Type |
|---|---|---|
tokenAddress | Token contract address | String! |
networkId | Network identifier | ID! |
name | Token name | String! |
symbol | Token symbol | String! |
decimals | Token decimal places | Float! |
price | Current token price | Float! |
balance | Total balance across all accounts | Float! |
balanceUSD | USD value of total balance | Float! |
balanceRaw | Raw balance amount (pre-decimal adjustment) | String! |
network | Detailed network information | NetworkObject! |
imgUrl | Token icon URL (deprecated) | String! |
imgUrlV2 | Token icon URL (null if not found) | String |
Account Balance Fields
| Field | Description | Type |
|---|---|---|
accountAddress | Wallet address | Address! |
balance | Token balance for this account | Float! |
balanceUSD | USD value for this account | Float! |
balanceRaw | Raw balance for this account | String! |
account | Detailed account information | Account! |
Filtering Options
The byToken query accepts several filtering parameters:
byToken(
first: Int = 25,
after: String,
filters: {
minBalanceUSD: Float
symbolLike: String
tokenAddress: String
includeTokensWithMissingPrices: Boolean
}
)
Similar filtering options are available for byAccount and byNetwork queries.
tip
When working with raw balances, remember to adjust for token decimals. For example, a balanceRaw of "1000000000000000000" with 18 decimals represents 1.0 tokens.
appBalances
View positions within onchain applications like lending protocols, DEXes, etc.
Try it nowKey Features
- Real-time Computation: No separate computation jobs needed
- Flexible Querying: View app positions by app, account, meta-type, network, or token
- Detailed Position Data: Complete position metadata and underlying assets
- Account-level Breakdown: See individual wallet contributions to positions
Key Fields
totalBalanceUSD: Total value of all app positionsbyApp: View positions grouped by applicationbyAccount: View positions grouped by wallet addressbyMetaType: View positions grouped by their classification (SUPPLIED, BORROWED, etc.)byNetwork: View positions grouped by blockchain networkbyToken: View positions grouped by underlying token
Position balances come in two types that require GraphQL fragments to access their specific fields:
-
AppTokenPositionBalance(for fungible tokens like LP tokens):type: "app-token"balance: Token balancebalanceUSD: USD valueprice: Token pricesymbol: Token symboltokens: Array of underlying tokens
-
ContractPositionBalance(for positions like a lending position):type: "contract-position"balanceUSD: Position USD valuetokens: Array of underlying tokens with their meta-typesdisplayProps: Formatted data for UI rendering
Example Variables
{
"addresses": ["0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"],
"first": 5
}
Example App Balance Query
query PortfolioV2($addresses: [Address!]!, $first: Int = 10) {
portfolioV2(addresses: $addresses) {
appBalances {
# Total value of all app positions
totalBalanceUSD
# Group positions by application
byApp(first: $first) {
totalCount
edges {
node {
# App metadata
balanceUSD
app {
displayName
imgUrl
description
slug
url
category {
name
}
}
network {
name
slug
chainId
evmCompatible
}
# Position details with underlying assets
balances(first: 10) {
edges {
node {
# App token positions (e.g. LP tokens)
... on AppTokenPositionBalance {
type
key
address
network
symbol
decimals
balance
balanceUSD
price
appId
groupId
groupLabel
supply
pricePerShare
# Underlying tokens in this position
tokens {
... on BaseTokenPositionBalance {
type
address
network
balance
balanceUSD
price
symbol
decimals
}
... on AppTokenPositionBalance {
type
address
network
balance
balanceUSD
price
symbol
decimals
}
}
# Detailed display properties
displayProps {
label
secondaryLabel {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
tertiaryLabel {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
images
balanceDisplayMode
statsItems {
label
value {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
}
}
}
# Contract positions (e.g. lending, farming positions)
... on ContractPositionBalance {
type
key
address
network
appId
groupId
groupLabel
balanceUSD
# Underlying tokens with meta-types (SUPPLIED, BORROWED, etc.)
tokens {
metaType
token {
... on BaseTokenPositionBalance {
type
address
network
balance
balanceUSD
price
symbol
decimals
}
... on AppTokenPositionBalance {
type
address
network
balance
balanceUSD
price
symbol
decimals
}
... on NonFungiblePositionBalance {
type
address
network
balance
balanceUSD
price
symbol
decimals
}
}
}
# Detailed display properties
displayProps {
label
secondaryLabel {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
tertiaryLabel {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
images
balanceDisplayMode
statsItems {
label
value {
type
... on DisplayItemDollar { valueDollar }
... on DisplayItemNumber { valueNumber }
... on DisplayItemPercentage { valuePct }
... on DisplayItemString { valueString }
... on DisplayItemTranslation { valueTranslation }
}
}
}
}
}
}
}
}
}
}
}
}
}
Example Response
{
"data": {
"portfolioV2": {
"appBalances": {
"totalBalanceUSD": 1788.726036163165,
"byApp": {
"totalCount": 15,
"edges": [
{
"node": {
"balanceUSD": 77.4990347567012,
"app": {
"displayName": "Morpho",
"imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Fmorpho.png",
"description": "Earn yield, borrow assets, curate markets and vaults.",
"slug": "morpho",
"url": "https://morpho.org/",
"category": {
"name": "DeFi"
}
},
"network": {
"name": "Base",
"slug": "base",
"chainId": 8453,
"evmCompatible": true
},
"balances": {
"edges": [
{
"node": {
"type": "app-token",
"key": null,
"address": "0x23479229e52ab6aad312d0b03df9f33b46753b5e",
"network": "BASE_MAINNET",
"symbol": "ionicUSDC",
"decimals": 18,
"balance": "37.03453811510863",
"balanceUSD": 37.373950883832,
"price": 1.009164769562798,
"appId": "morpho",
"groupId": "ionic-usdc",
"groupLabel": "Deposits",
"supply": 4729734.515683056,
"pricePerShare": [
1.009279827463129
],
"hasMissingUnderlyingTokenPrice": false,
"tokens": [
{
"type": "base-token",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"network": "BASE_MAINNET",
"balance": "37.378212",
"balanceUSD": 37.373950883832,
"price": 0.999886,
"symbol": "USDC",
"decimals": 6,
"priceSource": "COINGECKO"
}
],
"displayProps": {
"label": "Ionic Ecosystem USDC",
"secondaryLabel": {
"type": "dollar",
"valueDollar": 1.009164769562798
},
"tertiaryLabel": null,
"images": [
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.png"
],
"balanceDisplayMode": null,
"statsItems": [
{
"label": "Liquidity",
"value": {
"type": "dollar",
"valueDollar": 4773081.442612504
}
},
{
"label": "Share",
"value": {
"type": "pct",
"valuePct": 0.000783015156396367
}
}
]
}
}
},
{
"node": {
"type": "app-token",
"key": null,
"address": "0xc1256ae5ff1cf2719d4937adb3bbccab2e00a2ca",
"network": "BASE_MAINNET",
"symbol": "mwUSDC",
"decimals": 18,
"balance": "9.8334883099357",
"balanceUSD": 10.035656804686,
"price": 1.0205591979581237,
"appId": "morpho",
"groupId": "deposit",
"groupLabel": "Deposits",
"supply": 30778350.670850106,
"pricePerShare": [
1.0206755549713904
],
"tokens": [
{
"type": "base-token",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"network": "BASE_MAINNET",
"balance": "10.036801",
"balanceUSD": 10.035656804686,
"price": 0.999886,
"symbol": "USDC",
"decimals": 6,
}
],
"displayProps": {
"label": "Moonwell Flagship USDC",
"secondaryLabel": {
"type": "dollar",
"valueDollar": 1.0205591979581237
},
"tertiaryLabel": null,
"images": [
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.png"
],
"balanceDisplayMode": null,
"statsItems": [
{
"label": "Liquidity",
"value": {
"type": "dollar",
"valueDollar": 31410908.9721456
}
},
{
"label": "Share",
"value": {
"type": "pct",
"valuePct": 0.00003194936731697227
}
}
]
}
}
},
{
"node": {
"type": "app-token",
"key": null,
"address": "0xb7890cee6cf4792cdcc13489d36d9d42726ab863",
"network": "BASE_MAINNET",
"symbol": "uUSDC",
"decimals": 18,
"balance": "4.927314071231953",
"balanceUSD": 10.00525427097,
"price": 2.0305696056282287,
"appId": "morpho",
"groupId": "deposit",
"groupLabel": "Deposits",
"supply": 239855.8997112561,
"pricePerShare": [
2.0308011169555615
],
"tokens": [
{
"type": "base-token",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"network": "BASE_MAINNET",
"balance": "10.006395",
"balanceUSD": 10.00525427097,
"price": 0.999886,
"symbol": "USDC",
"decimals": 6,
}
],
"displayProps": {
"label": "Universal USDC",
"secondaryLabel": {
"type": "dollar",
"valueDollar": 2.0305696056282287
},
"tertiaryLabel": null,
"images": [
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.png"
],
"balanceDisplayMode": null,
"statsItems": [
{
"label": "Liquidity",
"value": {
"type": "dollar",
"valueDollar": 487044.09968428925
}
},
{
"label": "Share",
"value": {
"type": "pct",
"valuePct": 0.002054280956675889
}
}
]
}
}
}
]
}
}
},
{
"node": {
"id": "UG9ydGZvbGlvVjJBcHBCYWxhbmNlQnlBcHBPYmplY3QtMzM4MDk2OjE2",
"appId": "QXBwT2JqZWN0LTMzODA5Ng==",
"networkId": "TmV0d29ya09iamVjdC0xNg==",
"balanceUSD": 72.26435780954017,
"app": {
"displayName": "Uniswap V4",
"imgUrl": "https://storage.googleapis.com/zapper-fi-assets/apps%2Funiswap.png",
"description": "Swap tokens and earn fees through pooled market making.",
"slug": "uniswap",
"createdAt": 1738640323555,
"url": "https://uniswap.org/",
"category": {
"name": "DEX"
}
},
"network": {
"name": "Base",
"slug": "base",
"chainId": 8453,
"evmCompatible": true
},
"balances": {
"edges": [
{
"node": {
"type": "contract-position",
"key": "0x7c5f5a4bbd8fd63184577525326123b519429bdc:9671",
"address": "0x7c5f5a4bbd8fd63184577525326123b519429bdc",
"network": "BASE_MAINNET",
"appId": "uniswap",
"groupId": "v4-concentrated-liquidity",
"groupLabel": null,
"balanceUSD": 72.27701976728757,
"tokens": [
{
"metaType": "SUPPLIED",
"token": {
"type": "base-token",
"address": "0x0000000000000000000000000000000000000000",
"network": "BASE_MAINNET",
"balance": "0.017165606100749787",
"balanceUSD": 38.337493009353565,
"price": 2233.39,
"symbol": "ETH",
"decimals": 18
}
},
{
"metaType": "SUPPLIED",
"token": {
"type": "base-token",
"address": "0x20dd04c17afd5c9a8b3f2cdacaa8ee7907385bef",
"network": "BASE_MAINNET",
"balance": "678483.7719562778",
"balanceUSD": 33.204995799540235,
"price": 0.00004894,
"symbol": "NATIVE",
"decimals": 18
}
},
{
"metaType": "CLAIMABLE",
"token": {
"type": "base-token",
"address": "0x0000000000000000000000000000000000000000",
"network": "BASE_MAINNET",
"balance": "0.000179541498427967",
"balanceUSD": 0.40098618717403717,
"price": 2233.39,
"symbol": "ETH",
"decimals": 18
}
},
{
"metaType": "CLAIMABLE",
"token": {
"type": "base-token",
"address": "0x20dd04c17afd5c9a8b3f2cdacaa8ee7907385bef",
"network": "BASE_MAINNET",
"balance": "6815.381512458605",
"balanceUSD": 0.33354477121972415,
"price": 0.00004894,
"symbol": "NATIVE",
"decimals": 18
}
}
],
"displayProps": {
"label": "ETH / NATIVE (Token ID: 9671)",
"secondaryLabel": null,
"tertiaryLabel": null,
"images": [
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x20dd04c17afd5c9a8b3f2cdacaa8ee7907385bef.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x0000000000000000000000000000000000000000.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x20dd04c17afd5c9a8b3f2cdacaa8ee7907385bef.png"
],
"balanceDisplayMode": null,
"statsItems": null
}
}
}
]
}
}
}
]
}
}
}
}
}
App Balances by Network
View all app positions grouped by network:
query AppBalancesByNetwork($addresses: [Address!]!) {
portfolioV2(addresses: $addresses) {
appBalances {
byNetwork(first: 10) {
totalCount
edges {
node {
network {
name
slug
chainId
}
balanceUSD
}
}
}
}
}
}
note
Smart accounts like Maker's DSProxy are automatically included in balance responses as part of an "implicit" bundle.
Main Fields
| Field | Description | Type |
|---|---|---|
totalBalanceUSD | Total value of all app positions in USD | Float! |
byApp | Positions grouped by application | Connection! |
byAccount | Positions grouped by wallet address | Connection! |
byMetaType | Positions grouped by classification | Connection! |
byNetwork | Positions grouped by blockchain network | Connection! |
byToken | Positions grouped by underlying token | Connection! |
App Position Fields
| Field | Description | Type |
|---|---|---|
appId | Application identifier | ID! |
balanceUSD | Total value in this app | Float! |
app | App metadata (name, description, etc.) | App! |
network | Network information | NetworkObject! |
accountBalances | Breakdown by wallet address | Connection! |
balances | Detailed position information | Connection! |
Position Types
AppTokenPositionBalance (For LP tokens, yield tokens, etc.)
| Field | Description | Type |
|---|---|---|
type | Position type ("app-token") | String! |
address | Token contract address | String! |
balance | Token balance | String! |
balanceUSD | USD value of position | Float! |
price | Token price | Float! |
symbol | Token symbol | String! |
tokens | Underlying tokens | [AbstractToken!]! |
displayProps | UI display properties | DisplayProps |
ContractPositionBalance (For lending, staking positions, etc.)
| Field | Description | Type |
|---|---|---|
type | Position type ("contract-position") | String! |
address | Contract address | String! |
balanceUSD | USD value of position | Float! |
tokens | Underlying tokens with meta-types | [TokenWithMetaType!]! |
displayProps | UI display properties | DisplayProps |
Meta-Type Values
The metaType field indicates the role of tokens within positions:
| Value | Description |
|---|---|
SUPPLIED | Tokens supplied to a protocol |
BORROWED | Tokens borrowed from a protocol |
CLAIMABLE | Tokens that can be claimed as rewards |
VESTING | Tokens that are currently vesting |
LOCKED | Tokens that are locked in a protocol |
Best Practices
-
Use fragments for position types: Since app positions can be either
AppTokenPositionBalanceorContractPositionBalance, always use fragments to properly access all fields. -
Filter low-value positions: Use the
minBalanceUSDfilter to exclude dust or low-value positions from results:byApp(first: 10, filters: { minBalanceUSD: 10 }) -
Include proxy accounts: Set
includeProxyAccounts: trueto see positions held in smart contract wallets:portfolioV2(addresses: $addresses, includeProxyAccounts: true) -
Handle token decimals: Remember to adjust token balances based on their decimals field.
nftBalances
nftBalances surfaces NFT balance totals with breakdowns by chain. For granular data on specific NFT holdings, use nftUsersTokens or nftUsersCollections. Here you will find fields such as estimated values, traits, media, holders, activity, and marketplace data.
Key Fields
network: NFT's networkbalanceUSD: Estimated total value in USD
Example Variables
{
"addresses": ["0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"],
"first": 5
}
Example Query
query Portfolio($addresses: [Address!]!) {
portfolioV2(addresses: $addresses) {
nftBalances {
totalBalanceUSD
byNetwork {
totalCount
edges {
node {
network {
name
id
}
balanceUSD
}
}
}
}
}
}
Example Response
{
"data": {
"portfolioV2": {
"nftBalances": {
"totalBalanceUSD": 164.6907089747224,
"byNetwork": {
"totalCount": 5,
"edges": [
{
"node": {
"network": {
"name": "Ethereum",
"id": 1
},
"balanceUSD": 86.0075239
}
},
{
"node": {
"network": {
"name": "Optimism",
"id": 11
},
"balanceUSD": 34.99443875
}
},
{
"node": {
"network": {
"name": "Base",
"id": 16
},
"balanceUSD": 31.913208716
}
},
{
"node": {
"network": {
"name": "Story",
"id": 54
},
"balanceUSD": 10.79102505872242
}
},
{
"node": {
"network": {
"name": "Abstract",
"id": 51
},
"balanceUSD": 0.98451255
}
},
]
}
}
}
}
}
4. Portfolio Totals
Get aggregated portfolio values and breakdowns with portfolioV2. Unlike the deprecated portfolio query, portfolioV2 does not have a dedicated totals field. Instead, you can calculate totals by using the totalBalanceUSD fields from different sections:
Key Fields
tokenBalances.totalBalanceUSD: Total value of token balancesappBalances.totalBalanceUSD: Total value of app positionsbyNetwork: Network breakdowns available in bothtokenBalancesandappBalancesbyAccount: Account breakdowns available in both sectionsbyToken: Token-specific breakdowns (inappBalances)byMetaType: Type-specific breakdowns (inappBalances, includes CLAIMABLE tokens)
Example Variables
{
"addresses": ["0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"],
"first": 5
}
Example Query
query PortfolioV2Totals($addresses: [Address!]!) {
portfolioV2(addresses: $addresses) {
# Token balances total
tokenBalances {
totalBalanceUSD
# Network breakdown for tokens
byNetwork(first: 10) {
edges {
node {
network {
name
slug
chainId
}
balanceUSD
}
}
}
}
# App balances total
appBalances {
totalBalanceUSD
# Network breakdown for app positions
byNetwork(first: 10) {
edges {
node {
network {
name
slug
chainId
}
balanceUSD
}
}
}
}
}
}
Getting Overall Portfolio Value
To get the equivalent of the previous totals.total value, sum the totalBalanceUSD from both tokenBalances and appBalances.
For the equivalent of totals.totalWithNFT, you would need to include NFT balances, which are separate queries through the nftUsersCollections endpoint.
Example Response
{
"data": {
"portfolioV2": {
"tokenBalances": {
"totalBalanceUSD": 191519.4268333953,
"byNetwork": {
"edges": [
{
"node": {
"network": {
"name": "Base",
"slug": "base",
"chainId": 8453
},
"balanceUSD": 187210.46140590182
}
},
{
"node": {
"network": {
"name": "Ethereum",
"slug": "ethereum",
"chainId": 1
},
"balanceUSD": 712.0326101880804
}
},
{
"node": {
"network": {
"name": "Degen",
"slug": "degen",
"chainId": 666666666
},
"balanceUSD": 664.0659714357656
}
},
}
]
}
},
"appBalances": {
"totalBalanceUSD": 2354.7695934482635,
"byNetwork": {
"edges": [
{
"node": {
"network": {
"name": "Base",
"slug": "base",
"chainId": 8453
},
"balanceUSD": 2337.336868521915
}
},
{
"node": {
"network": {
"name": "Ethereum",
"slug": "ethereum",
"chainId": 1
},
"balanceUSD": 16.6343219463486
}
},
]
}
}
}
}
}
5. Claimables
In portfolioV2, claimable tokens are now part of app positions with a metaType of "CLAIMABLE". You can access them through the app balances with token filters.
Key Fields
metaType: Used to identify "CLAIMABLE" tokens within positionstokens: Contains claimable tokens with their balance, value, and metadatabalanceUSD: Value of each claimable token
Example Variables
{
"addresses": ["0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"],
"first": 5
}
Example Query
query ClaimablesV2($addresses: [Address!]!) {
portfolioV2(addresses: $addresses) {
appBalances {
# Get app balances and look for claimable tokens
byApp(first: 10) {
edges {
node {
app {
displayName
slug
}
network {
name
slug
}
balances(first: 10) {
edges {
node {
... on ContractPositionBalance {
address
balanceUSD
tokens {
# Look for CLAIMABLE meta-type
metaType
token {
... on BaseTokenPositionBalance {
address
network
balance
balanceUSD
symbol
price
decimals
}
}
}
displayProps {
label
images
}
}
}
}
}
}
}
}
}
}
}
Example Response
{
"data": {
"portfolioV2": {
"appBalances": {
"byApp": {
"edges": [
{
"node": {
"app": {
"displayName": "Uniswap V3",
"slug": "uniswap-v3"
},
"network": {
"name": "Base",
"slug": "base"
},
"balances": {
"edges": [
{
"node": {
"address": "0x03a520b32c04bf3beef7beb72e919cf822ed34f1",
"balanceUSD": 290.2802431386432,
"tokens": [
{
"metaType": "SUPPLIED",
"token": {
"address": "0x00000000000007c8612ba63df8ddefd9e6077c97",
"network": "BASE_MAINNET",
"balance": "29351.972884702704",
"balanceUSD": 238.5238178121461,
"symbol": "⌘",
"price": 0.00812633,
"decimals": 18
}
},
{
"metaType": "SUPPLIED",
"token": {
"address": "0x4200000000000000000000000000000000000006",
"network": "BASE_MAINNET",
"balance": "0",
"balanceUSD": 0,
"symbol": "WETH",
"price": 1872.93,
"decimals": 18
}
},
{
"metaType": "CLAIMABLE",
"token": {
"address": "0x00000000000007c8612ba63df8ddefd9e6077c97",
"network": "BASE_MAINNET",
"balance": "1069.849937435888",
"balanceUSD": 8.693953642083379,
"symbol": "⌘",
"price": 0.00812633,
"decimals": 18
}
},
{
"metaType": "CLAIMABLE",
"token": {
"address": "0x4200000000000000000000000000000000000006",
"network": "BASE_MAINNET",
"balance": "0.022992034771408265",
"balanceUSD": 43.06247168441369,
"symbol": "WETH",
"price": 1872.93,
"decimals": 18
}
}
],
"displayProps": {
"label": "⌘ / WETH (Token ID: 1568607)",
"images": [
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x00000000000007c8612ba63df8ddefd9e6077c97.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x4200000000000000000000000000000000000006.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x00000000000007c8612ba63df8ddefd9e6077c97.png",
"https://storage.googleapis.com/zapper-fi-assets/tokens/base/0x4200000000000000000000000000000000000006.png"
]
}
}
}
]
}
}
},
]
}
}
}
}
}
- Use the
byAppquery to see claimable tokens in the context of their specific apps, filtering for tokens withmetaType: "CLAIMABLE"
For applications building on top of this data, you'll typically want to:
- Extract all tokens with
metaType: "CLAIMABLE"from the app balances - Present the user with a view of what they can claim, grouped by app or by token
Best Practices
- Always specify required fields to minimize response size
- Use network filters when you only need specific chains
- Consider caching responses based on the
updatedAttimestamp - Handle NFT valuations appropriately based on your use case
Remember that the portfolio query is highly flexible - you can request as much or as little data as needed for your specific use case.