# native_balance

Returns an address's native-token balance as exact Wei in live, pinned, or retained execution state. Without a CLIENT, it builds a reusable READ and does not access state.

Canonical HTML: <https://determica.com/docs/functions/native_balance>

- Kind: scalar function
- Category: [Chain reads](/docs/category/chain-reads.md)
- Tags: RPC, Program Compiler, Simulate

Returns an address's native-token balance as exact Wei in live, pinned, or retained execution state. Without a CLIENT, it builds a reusable READ and does not access state.

## Overload 1: native_balance(CLIENT, ADDRESS)

```sql
native_balance(CLIENT, ADDRESS)
```

Reads the CLIENT's current state context; only a live CLIENT necessarily resolves latest state.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: External State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- client_state_context
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Readable EVM state represented by a live, pinned, or execution CLIENT.
- `address` (ADDRESS; required; positional) — Account or contract address whose native balance should be read.

### Returns

Native balance in Wei

Returns a UINT256 raw Wei balance. Historical block reads may require an archive-capable RPC provider.

- `balance` (UINT256)

Native balance in Wei. Returns a UINT256 raw Wei balance. Historical block reads may require an archive-capable RPC provider.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
SELECT native_balance(
    $client, -- client
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address -- address
) AS balance;
```

## Overload 2: native_balance(CLIENT, ADDRESS, BIGINT)

```sql
native_balance(CLIENT, ADDRESS, BIGINT)
```

Returns the Wei balance at an explicit block height for reproducible historical state queries.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client, Pinned Client, Execution Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: External State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- client_state_context
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Readable EVM state represented by a live, pinned, or execution CLIENT.
- `address` (ADDRESS; required; positional) — Account or contract address whose native balance should be read.
- `block_number` (BIGINT; required; positional) — Optional historical block height.

### Returns

Native balance in Wei

Returns a UINT256 raw Wei balance. Historical block reads may require an archive-capable RPC provider.

- `balance` (UINT256)

Native balance in Wei. Returns a UINT256 raw Wei balance. Historical block reads may require an archive-capable RPC provider.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
SELECT native_balance(
    $client, -- client
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address, -- address
    4200000 -- block_number
) AS balance;
```

## Overload 3: native_balance(ADDRESS)

```sql
native_balance(ADDRESS)
```

Records one address for a later native-balance lookup; construction does not access state.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Read Builder
- Execution modes: Read Constructor
- Input shape: Scalar Arguments
- Planning contract: Deferred Execution
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Requirements

- rpc

### Inputs

- `address` (ADDRESS; required; positional) — Account or contract address whose native balance should be observed.

### Returns

Native-balance READ

Returns a READ whose successful EVM_VALUE is an unsigned native balance in Wei.

- `read` (READ)

Native-balance READ. Returns a READ whose successful EVM_VALUE is an unsigned native balance in Wei.

## Guidance

### Historical balances

The two-argument overload reads latest and can change between runs.

Use the block_number overload for reproducible evidence.

Many providers require archive access for older historical balances.

### Evaluation

The READ accesses state only when an OBSERVATION consumes it during PROGRAM execution.

## Additional examples

```sql
SELECT native_balance('0x0000000000000000000000000000000000000001'::ADDRESS);
```

## Related functions

- [storage_at](/docs/functions/storage_at.md) — See Also
- [read_contract](/docs/functions/read_contract.md) — Alternative