Suggested
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.

Scalar functionLive RPC RPCProgram CompilerSimulate

Example

Live RPC

-- ETH balance of vitalik.eth in wei
SELECT native_balance(
    $client,
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address -- vitalik.eth
) AS balance;

API reference

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.

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; NULL gives NULL without an RPC call.

 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

Live RPC 

-- ETH balance of vitalik.eth in wei at Ethereum block 4200000
SELECT native_balance(
    $client,
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::address, -- vitalik.eth
    4200000
) AS balance;
native_balance(ADDRESS) # Read Builder

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.

Overload examples

Runs locally 

SELECT native_balance('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS); -- vitalik.eth

Guidance

Historical balances

The two-argument overload reads the CLIENT state; only a live CLIENT resolves latest.

Use the block_number overload for reproducible evidence.

Many providers require archive access for older historical balances.

Evaluation

Only overloads returning READ defer state access until an OBSERVATION consumes the READ during PROGRAM execution.