Check balances

Decrypt and read confidential token balances using the SDK and React hooks.

Confidential balances are stored on-chain as encrypted values. To display a human-readable number, the SDK decrypts them using FHE permits tied to the user's wallet. This guide walks through reading balances, understanding the caching layer, and working with multiple tokens.

Steps

1. Read your own balance

Call balanceOf() on a Token instance. The SDK fetches the encrypted value from the chain, decrypts it, and returns a bigint.

SDK

import { createConfig } from "@zama-fhe/sdk/viem";
import { ZamaSDK } from "@zama-fhe/sdk";
import { web } from "@zama-fhe/sdk/web";
import { sepolia } from "@zama-fhe/sdk/chains";

const config = createConfig({
  chains: [sepolia],
  publicClient,
  walletClient,
  storage,
  relayers: { [sepolia.id]: web() },
});
const sdk = new ZamaSDK(config);
const token = sdk.createToken("0xEncryptedERC20");

const [address] = await walletClient.getAddresses();
const balance = await token.balanceOf(address);
console.log(`Confidential balance: ${balance}`);

2. Understand the first-time wallet signature

The first balanceOf(address) call for a token prompts the user's wallet for an EIP-712 signature. This creates FHE decrypt permits that are cached in your storage backend. Subsequent reads are silent -- no wallet popup.

In React apps, don't trigger this signature on render. Gate useConfidentialBalance behind useHasPermit and let the user click an explicit "Decrypt" button. See Avoid blind-sign wallet popups for the full pattern.

If the user rejects the signature, the SDK throws a SigningRejectedError. See Handle Errors for recovery patterns.

You can pre-authorize multiple tokens with a single signature using sdk.permits.grantPermit():

SDK

await sdk.permits.grantPermit(["0xTokenA", "0xTokenB"]);

const tokenA = sdk.createToken("0xTokenA");
const tokenB = sdk.createToken("0xTokenB");
// All subsequent balanceOf() calls are silent

3. Balance caching

Decrypted balances are automatically cached in your storage backend (IndexedDB, async local storage, etc.). This means:

• No spinner on page reload -- if a balance was previously decrypted, it is returned instantly from cache instead of re-running the 2-5 second FHE decryption.

• Automatic invalidation -- the cache key includes the on-chain encrypted value, so when a transfer, shield, or unshield changes the balance, the old cache entry is naturally bypassed.

• Best-effort -- cache reads and writes never throw. If storage is unavailable, the SDK falls back to a fresh decryption silently.

The cache is keyed by token address + owner address + encrypted value.

4. Work with raw encrypted values

Sometimes you need the encrypted value itself, for example to check whether a balance exists before attempting decryption.

SDK

import { isEncryptedValueZero } from "@zama-fhe/sdk";

const encryptedValue = await token.confidentialBalanceOf(userAddress);

// Check if the encrypted value is zero (account has never shielded)
if (isEncryptedValueZero(encryptedValue)) {
  console.log("No confidential balance yet");
}

// Decrypt an encrypted value you already have
const result = await sdk.decryption.decryptValues([
  { encryptedValue, contractAddress: token.address },
]);
const value = result[encryptedValue] as bigint;

// Decrypt multiple encrypted values at once (must include the contract address per entry)
const decrypted = await sdk.decryption.decryptValues(
  [value1, value2, value3].map((v) => ({ encryptedValue: v, contractAddress: token.address })),
);

5. Distinguish "no balance" from "zero balance"

These are different situations that your UI should handle separately:

• NoCiphertextError -- the account has never shielded tokens. There is no encrypted balance to decrypt. Show something like "No confidential balance" in your UI.

• Balance of 0n -- the account has shielded before but currently holds zero. Show "Balance: 0".

SDK

import { NoCiphertextError } from "@zama-fhe/sdk";

try {
  const [address] = await walletClient.getAddresses();
  const balance = await token.balanceOf(address);
  showBalance(balance); // could be 0n
} catch (error) {
  if (error instanceof NoCiphertextError) {
    showEmptyState("Shield tokens to get started");
  }
}

6. Batch decrypt across multiple tokens

When your app manages a portfolio of confidential tokens, use batch operations to minimize wallet prompts and parallelize decryption.

SDK

import { Token } from "@zama-fhe/sdk";

// One wallet signature covers all tokens
await sdk.permits.grantPermit(addresses);

const tokens = addresses.map((a) => sdk.createToken(a));

// Decrypt all balances in parallel
const { results, errors } = await Token.batchBalancesOf(tokens, userAddress);

// `results` is Map<Address, bigint> for tokens that decrypted successfully,
// `errors` is Map<Address, ZamaError> for tokens that failed — partial failure
// never rejects the whole batch.
for (const [address, balance] of results) {
  console.log(address, balance);
}

7. Read token metadata

Before displaying balances, you typically want the token's name, symbol, and decimals. Use the useMetadata hook:

import { useMetadata } from "@zama-fhe/react-sdk";

const { data: meta } = useMetadata("0xToken");

// meta.name, meta.symbol, meta.decimals

See useMetadata reference for full options.

8. Use the balance hooks in React

The React SDK provides hooks that handle polling, caching, and React Query integration out of the box.

Single token

import { useConfidentialBalance } from "@zama-fhe/react-sdk";
import { useAccount } from "wagmi";

const { address } = useAccount();
const {
  data: balance,
  isLoading,
  error,
} = useConfidentialBalance({ address: "0xToken", account: address }, { refetchInterval: 5_000 });

Multiple tokens

useConfidentialBalance calls token.balanceOf(owner) which reads the on-chain encrypted value and decrypts via the SDK. Cached clear values are served instantly — the relayer is only hit when the encrypted value changes. Pass refetchInterval to poll for updates. Clear values are persisted in storage, so page reloads show the balance instantly.

9. Force a manual refresh

Mutations automatically invalidate balance caches, but if you need manual control (for example, after an external contract interaction), use zamaQueryKeys:

React

import { useQueryClient } from "@tanstack/react-query";
import { zamaQueryKeys } from "@zama-fhe/sdk/query";

const queryClient = useQueryClient();

// Invalidate all balance queries
queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.all });

// Invalidate one token
queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.token("0xToken") });

Next steps

• See Avoid blind-sign wallet popups to gate balance queries behind explicit user action.

• See Token Operations for the full Token API.

• See Hooks for useConfidentialBalance, useConfidentialBalances, and query key details.

• To handle NoCiphertextError and other failures, see Handle Errors.