Nonces

Nonces prevent replay of signed account and session operations.

o2 supports sequential nonces and, for typed signature flows, parallel nonces.

Sequential Nonces

Sequential nonces are the default flow.

Each trading account maintains an on-chain nonce that increments with every nonce-authorized operation. A signed message can only be used once.

Recommended flow:

1. Fetch the current nonce before signing.
2. Include that nonce in the signing payload.
3. Submit the request.
4. Re-fetch after failures, retries, or concurrent activity.

Do not rely on a local counter in production when other processes may also submit operations.

See Nonce Management.

Parallel Nonces

Parallel nonces allow many account operations or session actions to be in flight concurrently.

Use a parallel_nonce instead of nonce when the typed signature variant supports it. The nonce is a packed u256 sent as a decimal string.

Supported flows include:

• session updates
• session actions
• withdrawals
• owner calls

See Parallel Nonces for the packed layout.

Nonce Window

Parallel nonce generation starts by reading the account's current nonce window:

GET /v1/accounts/window?trade_account_id=0x...&nonce_session_id=0

Then generate positions locally after the highest consumed position.

See Get Parallel Nonce Window.

Nonce WebSocket Updates

Use WebSocket nonce subscriptions to track nonce state:

• subscribe_nonce for sequential nonce updates
• subscribe_nonce_v2 for sequential and parallel nonce state changes

Retry and Concurrency Rules

• Never reuse a consumed nonce.
• Re-fetch sequential nonces after errors or uncertain transaction status.
• Generate parallel nonce positions locally and never hand out the same position twice.
• Use fresh expiries for parallel nonces.
• Treat the contract as the final authority on nonce validity.