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.

Example

Local

1
SELECT native_balance('0x0000000000000000000000000000000000000001'::ADDRESS);
Notebook ready in readonly mode.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

native_balance(CLIENT, ADDRESS) # Immediate Read · RPC required

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

Inputs

Name Type Use
client CLIENT

Readable EVM state represented by a live, pinned, or execution CLIENT.

 required positional
address ADDRESS

Account or contract address whose native balance should be read.

 required positional

Returns

Name Type
balance UINT256

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

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.

Additional overloads

native_balance(CLIENT, ADDRESS, BIGINT) # Immediate Read · RPC required

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

Inputs

Name Type Use
client CLIENT

Readable EVM state represented by a live, pinned, or execution CLIENT.

 required positional
address ADDRESS

Account or contract address whose native balance should be read.

 required positional
block_number BIGINT

Optional historical block height.

 required positional

Returns

Name Type
balance UINT256

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

Overload examples

Named parameters · RPC required

1
SELECT native_balance(
2
$client, -- client
3
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address, -- address
4
4200000 -- block_number
5
) AS balance;
native_balance(ADDRESS) # Read Builder · RPC required

Builds a reusable native-balance READ; no client is resolved and no state is accessed.

Inputs

Name Type Use
address ADDRESS

Account or contract address whose native balance should be observed.

 required positional

Returns

Name Type
read READ

Native-balance READ. Returns a canonical READ specification for a later native-balance observation.

Examples

Named parameters · RPC required

1
SELECT native_balance(
2
$client, -- client
3
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address -- address
4
) AS balance;
Notebook ready in readonly mode.

Related functions

Category and tags

Category
Chain reads
Tag
RPC
Tag
Simulate