<!-- tempo-docs-context -->
> Source: [/docs/zones/balances](https://tempo.com/developers/docs/zones/balances.md)
> Section: [Zones](https://tempo.com/developers/docs/zones.md). Connect to a Zone and work with private balances, deposits, and withdrawals. Zones is live on Mainnet; see the introduction to set up a Zone. Earlier testnet sandbox guides describe a separate integration.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

<span id="private-balances-and-activity" />

# Balances and Activity

Read a private account's token balances and transfer history from a Zone.

## Overview

Balance and activity reads go through the [account-scoped, redacted Zone RPC](https://tempo.com/developers/docs/zones/connect), which scopes results to the authenticated account.

The examples use the authenticated `zone` client from [Connect to a Zone](https://tempo.com/developers/docs/zones/connect#check-the-connection) and `zoneConfig` from [Client Setup](https://tempo.com/developers/docs/zones/examples). With a hosted provider, use its read API instead.

<span id="read-a-token-balance" />

## Read Balances

Use the Zone token's `balanceOf` through `eth_call`. The Zone RPC executes the call as the authenticated account. Execution-level privacy restricts which balances it can read. Don't substitute `eth_getBalance` for a token balance query.

Set `ZONE_ACCOUNT` to the authenticated account, `ZONE_TOKEN` to the enabled token, and `ZONE_TOKEN_DECIMALS` to its configured precision.

:::code-group
```ts [Viem]
const account = process.env.ZONE_ACCOUNT as `0x${string}`
const token = process.env.ZONE_TOKEN as `0x${string}`
const decimals = Number(process.env.ZONE_TOKEN_DECIMALS)
const balance = await zone.token.getBalance({ account, token, decimals })
console.log(balance.formatted)
```

```ts [Wagmi]
import { Actions } from '@wagmi/core/tempo'
const balance = await Actions.token.getBalance(zoneConfig, { account, token, decimals })
console.log(balance.formatted)
```

```python [Python]
account, token = os.environ["ZONE_ACCOUNT"], os.environ["ZONE_TOKEN"]
data = "0x70a08231" + account[2:].rjust(64, "0")
response = zone.post(zone_rpc_url, json={
    "jsonrpc": "2.0", "id": 1, "method": "eth_call",
    "params": [{"to": token, "data": data}, "latest"],
})
response.raise_for_status()
print(int(response.json()["result"], 16))
```

```bash [CLI]
cast erc20 balance "$ZONE_TOKEN" "$ZONE_ACCOUNT" \
  --rpc-url "$ZONE_RPC_URL" \
  --rpc-headers "X-Authorization-Token: $ZONE_AUTH_TOKEN"
```
:::

Viem and Wagmi return a formatted decimal string. Python and Cast return integer base units, which you format with `ZONE_TOKEN_DECIMALS`. The Python example encodes `balanceOf(address)` with selector `0x70a08231` and the account as a 32-byte word. Check raw JSON-RPC responses for `error` before you read `result`.

Some restricted reads about another account return an empty, zero, or `null` value, so they don't expose that account's data. [Method access control](https://tempo.com/developers/docs/protocol/zones/rpc#method-access-control) lists which reads do this.

<span id="read-account-activity" />

## Read Activity

Use account-scoped `eth_getLogs` filters or log subscriptions for supported token events. Filters must name the authenticated account in an indexed topic. The Zone RPC rejects broad filters, as [event filtering](https://tempo.com/developers/docs/protocol/zones/rpc#event-filtering) describes.

Continue with the same `zone`, `account`, and `token`. Set `ZONE_FROM_BLOCK` to the first Zone block you need to reconcile. These examples read incoming transfers:

:::code-group
```ts [Viem]
import { parseAbiItem } from 'viem'
const incoming = await zone.getLogs({
  address: token,
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 amount)'),
  args: { to: account },
  fromBlock: BigInt(process.env.ZONE_FROM_BLOCK!),
  toBlock: 'latest',
})
```

```ts [Wagmi]
import { getPublicClient } from '@wagmi/core'
import { Abis } from 'viem/tempo'
const incoming = await getPublicClient(zoneConfig)!.getContractEvents({
  address: token, abi: Abis.tip20, eventName: 'Transfer',
  args: { to: account },
  fromBlock: BigInt(process.env.ZONE_FROM_BLOCK!),
  toBlock: 'latest',
})
```

```python [Python]
transfer = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
query = {"address": token, "topics": [transfer, None, "0x" + account[2:].rjust(64, "0")],
         "fromBlock": hex(int(os.environ["ZONE_FROM_BLOCK"])), "toBlock": "latest"}
response = zone.post(zone_rpc_url, json={
    "jsonrpc": "2.0", "id": 1, "method": "eth_getLogs", "params": [query]
})
response.raise_for_status()
print(response.json())
```

```bash [CLI]
cast logs 'Transfer(address indexed from, address indexed to, uint256 amount)' \
  '' "$ZONE_ACCOUNT" --address "$ZONE_TOKEN" \
  --from-block "$ZONE_FROM_BLOCK" --to-block latest \
  --rpc-url "$ZONE_RPC_URL" \
  --rpc-headers "X-Authorization-Token: $ZONE_AUTH_TOKEN"
```
:::

For outgoing transfers, use `args: { from: account }` in Viem and Wagmi. In Cast, swap the arguments to `"$ZONE_ACCOUNT" ''`. In Python, put the account in `topics[1]` instead of `topics[2]`.

Query incoming and outgoing transfers separately and deduplicate shared events. Save the last processed block, and use bounded ranges for repeated history reads.

Transaction and receipt reads are scoped to the sender. To verify an incoming deposit, use the recipient's permitted token events and balance reads. Don't rely on access to the sender's receipt.

## Preserve the Privacy Boundary

Tie cached responses and saved history to the authenticated customer, as [Privacy](https://tempo.com/developers/docs/zones/privacy#keep-application-access-scoped) describes. Show a withdrawal as pending until Tempo delivers it, as [Withdraw From a Zone](https://tempo.com/developers/docs/zones/withdraw) describes.

## Related

[Withdraw From a Zone](https://tempo.com/developers/docs/zones/withdraw): Use for returning funds to Tempo and tracking delivery.

[RPC Reference](https://tempo.com/developers/docs/protocol/zones/rpc): Covers method access control, event filtering, and response redaction.

[Client Setup](https://tempo.com/developers/docs/zones/examples): Use for setting up the Wagmi client in these examples.

[Connect to a Zone](https://tempo.com/developers/docs/zones/connect): Use for authenticating the Zone RPC client.
