> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Get Balance \[address.getBalance]

Returns the balance of an address in wei.

## Usage

This example returns the balance of an address in wei.

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const balance = await client.address.getBalance({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
// @log: 10000000000000000000n
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
}).extend(publicActions())
```
:::

### Standalone Action

Call `Actions.address.getBalance` directly by passing the Client as the first argument.

:::code-group
```ts twoslash [example.ts]
import { Actions } from 'viem'
import { client } from './viem.config'

const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
// @log: 10000000000000000000n
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
})
```
:::

## Recipes

### Read a Canonical Historical Balance

Use `requireCanonical` with a block hash when the balance must come from the canonical chain.

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const balance = await client.address.getBalance({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', // [!code focus]
  requireCanonical: true, // [!code focus]
})
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
}).extend(publicActions())
```
:::

## Return Value

`bigint`

The balance of the address, in wei.

## Parameters

### address

* **Type:** `Address`

The address to check the balance of.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', // [!code focus]
})
```

### blockHash

* **Type:** `Hex`

The balance at a block identified by its hash.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', // [!code focus]
})
```

### blockNumber

* **Type:** `bigint`

The balance at a given block number.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockNumber: 42069n, // [!code focus]
})
```

### blockTag

* **Type:** `'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`
* **Default:** `client.blockTag ?? 'latest'`

The balance at a given block tag.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockTag: 'safe', // [!code focus]
})
```

### requireCanonical

* **Type:** `boolean`
* **Default:** `false`

Requires [`blockHash`](#blockhash) to identify a block in the canonical chain.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const balance = await Actions.address.getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  requireCanonical: true, // [!code focus]
})
```

## Errors

| Error | Description |
| --- | --- |
| `BlockParameter.RequireCanonicalError` | `requireCanonical` was provided without a `blockHash`. |