Balances

The Balances object provides a paginated, cursor-based list of token/NFT holdings (Balance objects) for a given user or contract address. It enables efficient traversal of large balance datasets while tracking pagination state via cursor and remaining fields.

type Balances implements Plural {
  count: UInt64!
  remaining: UInt64!
  cursor: String
  balances: [Balance!]!
}

Fields

Balances.count ● UInt64! non-null scalar

Balances.remaining ● UInt64! non-null scalar

Balances.cursor ● String scalar

Balances.balances ● [Balance!]! non-null object

Interfaces

Plural interface

Returned By

balances query

Member Of

Token object

Field Descriptions

Field Name	Type	Description
count	UInt64!	Total balances matching the query.
remaining	UInt64!	Count of balances not yet returned in the current query.
cursor	String	Pagination key for fetching the next batch (null if no more results).
balances	[Balance!]!	List of individual token balances.

Example Query

query GetBalances($owner: String!, $cursor: String) {
  balances(owner: $owner, first: 10, after: $cursor) {
    balances { owner, value, contract { id } }
    remaining
    cursor
  }
}

Use Cases

• Displaying all owned NFTs/tokens.
• Calculating holdings across a collection.
• Paginated UIs (lazy-loading balances in chunks).