Balances

The balances query retrieves a paginated list of token/NFT holdings for user and contract addresses. It supports complex filtering across token standards and returns a Balances! object with cursor-based pagination.

Arguments

Pagination Controls

Argument	Type	Default	Description
first	Int	10	Maximum items per page.
skip	Int	0	Offset for legacy pagination.
after	String	-	Cursor for next page (from previous response).

Core Filters

Argument	Type	Description
owner	ID!	Required wallet/contract address to query.
where	BalanceFilter	Filter by balance-specific fields (tokenID, contract).

Related Entity Filters

Argument	Type	Use Case
whereToken	TokenFilter	Filter by token properties (tokenID, name, etc.).
whereContract	ContractFilter	Filter by contract properties (type, name, etc.).

Sorting

Argument	Type	Options
orderBy	BalanceOrderBy	TYPE, CONTRACT, TOKEN_ID, ACCOUNT, VALUE, BLOCK, CONTRACT_TOKEN_ID, CONTRACT_ACCOUNT, CONTRACT_TOKEN_ID_ACCOUNT
orderDirection	OrderDirection	ASC, DESC

Example

Basic Wallet Holdings in Descending Order

query GetWalletBalances($owner: ID!, $orderBy: BalanceOrderBy, $orderDirection: OrderDirection) {
  balances(owner: $owner, first: 20, orderBy: $orderBy, orderDirection: $orderDirection) {
    balances {
      value
      contract {
        name
        type
        id
      }
    }
    count
  }
}

Variables

{
  "owner": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "orderBy": "VALUE",
  "orderDirection": "DESC"
}

Response

This response is an example only and may not reflect current data.

{
  "data": {
    "balances": {
      "balances": [
        {
          "value": "1",
          "contract": {
            "name": null,
            "type": "ERC721",
            "id": "0x376c4c43e092bd48a9cdc8259dec833bbd6d6860"
          }
        },
        {
          "value": "1",
          "contract": {
            "name": "OpenEthereumToken",
            "type": "ERC721",
            "id": "0x80804eccd64b153572dcd0f6f494253a0d013492"
          }
        }
      ],
      "count": 2
    }
  }
}

Response Fields

The query returns a Balances! object containing:

• balances: Array of Balance objects.
• count: Total matching items.

Common Use Cases

1. Wallet dashboards showing all token holdings.
2. Bulk export of a collection's ownership data.
3. Access control based on token quantities.
4. Analytics on token distribution.

Best Practices

• Prefer after over skip for large datasets.
• Combine where and whereContract for precise filtering.
• Always check count before fetching all results.
• Request only needed fields to improve performance.

Related Queries

• balance: For single balance lookups.
• token: To explore token metadata separately.