Balance

The Balance object represents a user's or contract's holdings of a specific token/NFT. This object provides crucial ownership details, including the token amount held, associated smart contract information, and token metadata where applicable.

type Balance {
  owner: String!
  contractType: ContractType!
  contract: Contract!
  token: Token
  value: String!
}

Fields

Balance.owner ● String! non-null scalar

Balance.contractType ● ContractType! non-null enum

Balance.contract ● Contract! non-null object

Balance.token ● Token object

Balance.value ● String! non-null scalar

Returned By

balance query

Member Of

Balances object

Field Descriptions

Field Name	Type	Description
owner	String!	The address of the owner of the balance.
contractType	ContractType!	The type of contract (ERC-721, ERC-1155, ERC-20).
contract	Contract!	The contract object.
token	Token	The token object (if applicable).
value	String!	The balance value.

Example Query

query GetBalance($owner: ID!, $contract: ID!) {
  balance(owner: $owner, contract: $contract) {
    value
    token {
      name
    }
    contractType
    owner
    contract {
      decimals
    }
  }
}

Understanding the value Field

The value field returns ERC-20 token balances exactly as stored on the Ethereum blockchain - as a raw, unformatted integer string representing the smallest unit of the token. This preserves full precision without decimal approximation.

You will need to convert the value to its decimal format using the token's decimals.

// Requires knowing the token's decimals
const formatted = value / (10 ** tokenDecimals);

The ether.js and web3.js libraries can also help with these conversions.

Use Cases

• Checking ownership of specific NFTs.
• Calculating total holdings of a particular token.
• Building portfolio dashboards.

Implementation Notes

• The value field returns strings to support arbitrary precision.
• For ERC-20 tokens, token will be null.
• Use with the Balances type for paginated results.
• Combine with the Tokens type to get complete metadata when displaying NFT collections.