balance

The balance query retrieves information about a specific token or NFT balance for a given account.

It returns a Balance object containing the asset type, contract details, account address, balance value, and associated token information.

Schema Definition

balance(
  contract: String!
  tokenId: UInt256
  account: String!
): Balance

Arguments

Argument	Type	Description
contract	String! non-null scalar	The contract address of the token.
tokenId	UInt256 scalar	The specific token ID (required for ERC-721 and ERC-1155 tokens).
account	String! non-null scalar	The account address holding the tokens.

Return Type

Balance object

Common Use Cases

• Display wallet portfolio balances for ERC-20, ERC-721, or ERC-1155 tokens.
• Verify ownership of specific NFTs by checking the balance for a contract/tokenId/account combination.
• Build token tracking dashboards showing current holdings across multiple contracts.
• Validate asset ownership before executing transfers or marketplace operations.
• Check balance changes after transactions to confirm successful transfers.

Example

Query

Check ERC-1155 Balance for an Account

query Balance($contract: String!, $account: String!, $tokenId: UInt256) {
  balance(contract: $contract, account: $account, tokenId: $tokenId) {
    value
  }
}

Variables

{  "contract": "0x76be3b62873462d2142405439777e971754e8e77",
  "account": "0x11117fa34c8f660b9b804b85ebe891d0c05bf9c9",
  "tokenId": 10789
}

Response

{
  "data": {
    "balance": {
      "value": "689"
    }
  }
}

Implementation Notes

note

• The tokenId parameter is optional. Omit it when querying ERC-20 token balances.
• For ERC-721 and ERC-1155 tokens, include the tokenId to query specific NFT ownership.
• The value field returns the balance in the token's smallest unit. For ERC-20 tokens with decimals, convert for display: 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.
• If the balance query returns null, it means the account does not hold any balance for the specified contract/tokenId combination.