balances

The balances query retrieves a paginated list of token and NFT balances with comprehensive filtering, sorting, and pagination capabilities.

It returns a BalanceList object containing an array of Balance objects with detailed balance data including asset types, contract details, balance values, and associated token information.

Schema Definition

balances(
  first: Int = 10
  skip: Int = 0
  where: BalanceFilter
  orderBy: BalanceOrderBy
  orderDirection: Ordering
): BalanceList!

Arguments

Argument	Type	Description
first	Int = 10 scalar	Maximum number of balances to retrieve per page. Maximum value is 100.
skip	Int = 0 scalar	Number of balances to bypass before assembling the page. Set to the first value from the previous page for offset pagination.
where	BalanceFilter input	Specifies subsets of balance data to be retrieved.
orderBy	BalanceOrderBy enum	Sets how the list of balances is ordered.
orderDirection	Ordering enum	Sets the direction in which the list of balances is ordered.

Return Type

BalanceList object

Common Use Cases

• Build wallet dashboards showing all ERC-20, ERC-721, and ERC-1155 holdings in one view.
• Create portfolio value calculators by fetching all balances and enriching with price data.
• Monitor NFT collections by combining ContractFilter parameters with TokenFilter parameters.
• Analyze token distribution and whale wallets by ordering balances by value (orderBy: VALUE) with descending order.
• Track token ownership and holdings for specific smart contracts by filtering on the address field in ContractFilter.

Example

Query

Display Complete Wallet Portfolio

query WalletPortfolio($account: String!, $first: Int!, $skip: Int!) {
  balances(
    first: $first
    skip: $skip
    where: { account: $account }
    orderBy: VALUE
    orderDirection: DESC
  ) {
    numEntries
    cursor
    entries {
      type
      account
      value
      contract {
        address
        name
        symbol
      }
      token {
        tokenId
        name
        metadata {
          name
          description
          image
        }
      }
    }
  }
}

Variables

{
  "account": "0x2fc61ca1cf50983b7533653d95ace66e71759398",
  "first": 10,
  "skip": 0
}

Response

Implementation Notes

note

• The default first value is 10 transactions. OneSource enforces a maximum first value of 100. Adjust based on your UI needs.
• Use skip for offset-based pagination. To get the next page, use a skip value equal to the previous first value.
• Use orderBy and orderDirection to ensure consistent ordering when paginating through large result sets.
• The token field in returned Balance objects will be null for ERC-20 balances and populated for NFTs (ERC-721/ERC-1155).
• For ERC-20 tokens, the value field is in the token's smallest unit (e.g., wei for 18-decimal tokens). Convert to human-readable amounts: value / 10^decimals.
• For ERC-721 tokens, the value will typically be 1 (owned) or null (not owned).
• For ERC-1155 tokens, the value represents the quantity of that specific token ID held by the account.
• Use nested filtering via ContractFilter and TokenFilter for more specific queries (e.g., filtering by contract type or token attributes).