> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notional.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Nonces and API wallets

<div className="api-reference-page" aria-hidden="true" />

## Background

Signed requests need replay protection: an order or withdrawal signature should not let someone
execute the same action repeatedly. Most signed exchange requests include a `nonce` for this
purpose. Polymarket deposit reports instead sign the transaction hash and have no nonce. Unlike Ethereum's sequential transaction counter, Notional uses timestamp-based nonces
with a rolling window, allowing requests to arrive out of order.

## API wallets

API wallets, also called **agent wallets**, are separate signing keys approved by an account owner.
They can sign eligible actions, such as orders and cancels, on behalf of that account. Withdrawals
and API-wallet approvals require the account owner's signature.

Use the account owner’s address as `user` for account queries and WebSocket subscriptions.

Use [Approve API Wallet](/api-reference/exchange-endpoints/approve-agent) to register a signing key
and [Get API wallets](/api-reference/info-endpoints/extra-agents) to list an account's approvals.
[Get address role](/api-reference/info-endpoints/user-role) accepts an API-wallet address and can
identify the account owner of an active approval. Owner-only actions still require the owner's signature.

## API wallet lifecycle

Approvals are identified by `agentName`:

* Approving a new address with an existing name replaces the previous wallet under that name.
* Omitting the name or using an empty string selects the single unnamed wallet. Approving a new
  unnamed wallet replaces the previous unnamed wallet.
* To revoke a wallet, send `approveAgent` with the zero address as `agentAddress` and the existing
  wallet's name. Use an empty name for the unnamed wallet.

A replaced or revoked key can no longer act for the account. If an approval record has an
`expiresAt` timestamp, it also stops authorizing the key once that time is reached. The
`extraAgents` response can still include expired records.

Generate a fresh wallet when rotating keys. Revoking or replacing an approval does not reset that
signer's nonce history.

## Notional nonces

Notional retains the **20 highest nonces per signer**. A new request's nonce must be unused and,
once the set is full, greater than the smallest retained nonce. This allows some out-of-order
arrival without requiring every request to use exactly the previous nonce plus one.

Nonces are tracked by the address whose private key signs the request. Requests signed directly
by the owner use the owner's nonce set; requests signed by an API wallet use that wallet's set.
Orders, cancels, and other actions signed by the same key share this set.

Use a Unix-millisecond integer within `[T - 2 days, T + 1 day]`, where `T` is the server's current
time when validating the request. Keep the client's clock synchronized.

`expiresAfter` is an optional signed request deadline. See [request deadlines](/api-reference/signing#request-deadlines).

## Suggestions for automated trading

1. **Use a separate API wallet per trading process or frontend session.** This gives each signer
   its own nonce set and avoids collisions between independent clients.
2. **Allocate nonces with a monotonic counter.** For each request, atomically choose
   `max(current Unix milliseconds, previous nonce + 1)`. Concurrent `Date.now()` calls alone can
   produce duplicates. If processes share a signer, coordinate the counter across them and
   preserve it across restarts.
3. **Allocate one nonce per signed request.** A batch of orders or cancels uses one request nonce,
   rather than a separate nonce for each item. Sign and submit the same nonce.
4. **Keep delayed requests within the rolling window.** Once 20 higher nonces have been recorded,
   an older request falls below the retained set and is rejected. The window is measured in
   requests, so it does not guarantee a fixed amount of time for out-of-order arrival.

Retry handling is endpoint-specific. [Cancel requests](/api-reference/exchange-endpoints/cancel)
reject reused nonces, including identical retries. After an uncertain cancel response, check
current order state before signing another cancel with a new nonce.

See [Signing](/api-reference/signing) for signing requirements, formats, and common mistakes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.