View this page as Markdown

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

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

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.

Evaluation

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

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 

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

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

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 READ whose successful EVM_VALUE is an unsigned native balance in Wei.

Examples

Named parameters · RPC required 

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

Related functions

Category and tags

Category
Chain reads
Tag
RPC
Tag
Simulate