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

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

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

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.

## Overload 1: nonce(CLIENT, ADDRESS)

```sql
nonce(CLIENT, ADDRESS)
```

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

### Returns

Account transaction count

Returns the account nonce as UBIGINT. Contract nonces and retained execution state follow the selected CLIENT context.

- `nonce` (UBIGINT)

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

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
SELECT nonce($client, '0x0000000000000000000000000000000000000001'::ADDRESS);
```

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

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

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

- 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 transaction count should be read.
- `block_number` (BIGINT; required; positional) — Explicit historical block height for a repeatable nonce read.

### Returns

Account transaction count

Returns the account nonce as UBIGINT. Contract nonces and retained execution state follow the selected CLIENT context.

- `nonce` (UBIGINT)

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

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
SELECT nonce($client, '0x0000000000000000000000000000000000000001'::ADDRESS, 21000000);
```

## Overload 3: nonce(ADDRESS)

```sql
nonce(ADDRESS)
```

Records one address for a later account-nonce 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 transaction count should be observed.

### Returns

Account-nonce READ

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

- `read` (READ)

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

## 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

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

## Additional examples

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