Suggested
View this page as Markdown

nonce

Returns an address's transaction count 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

-- Transaction count of vitalik.eth
SELECT nonce($client, '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS);

API reference

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

Reads the account nonce from 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 transaction count should be read.

 required positional

Returns

Name Type
nonce UBIGINT

Account transaction count. Returns the account nonce as UBIGINT. Contract nonces and retained execution state follow the selected CLIENT context. An RPC failure raises.

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

Reads the account nonce at an explicit block height; older heights may require archive access.

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 transaction count should be read.

 required positional
block_number BIGINT

Explicit historical block height for a repeatable nonce read. NULL gives NULL without a read.

 required positional

Returns

Name Type
nonce UBIGINT

Account transaction count. Returns the account nonce as UBIGINT. Contract nonces and retained execution state follow the selected CLIENT context. An RPC failure raises.

Overload examples

Live RPC 

-- Transaction count of vitalik.eth at Ethereum block 21000000
SELECT nonce($client, '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS, 21000000);
nonce(ADDRESS) # Read Builder

Records one address for a later account-nonce lookup; construction does not access state.

Inputs

Name Type Use
address ADDRESS

Account or contract address whose transaction count should be observed.

 required positional

Returns

Name Type
read READ

Account-nonce READ. Returns a READ whose successful EVM_VALUE is an unsigned account nonce.

Overload examples

Runs locally 

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

Guidance

Nonce semantics

nonce returns the account transaction count used by EVM account state; it is not a pending-transaction queue length.

  • Use an explicit block number or pinned CLIENT for repeatable evidence.
  • Historical block reads may require archive-capable RPC access.
  • Use the READ overload when scheduling an observation inside a simulation program.

Evaluation

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