Nonce

Every POST /exchange request includes a nonce — an integer that the server uses to prevent replay attacks. Because the nonce is embedded in the signed message, an attacker who intercepts a valid signed request cannot resubmit it: the chain records the nonces each signing address has used and rejects a repeat. That same property is what makes re-sending an identical signed request after a timeout safe — see Timeouts and retries.

What Is the Nonce?

The nonce is an int64 (64-bit signed integer) included at the top level of every POST /exchange envelope alongside action and signature. It is part of the signed message, so any tampering with the nonce value will invalidate the signature.

{
  "action": { "type": "order", "..." },
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "nonce": 1778572951477
}

Recommended Value

Use the current Unix timestamp in milliseconds. This is a natural choice because it is:

Monotonically increasing — subsequent requests naturally have higher nonces.
Unique — millisecond resolution makes accidental collisions unlikely in normal usage.
Self-documenting — you can decode the approximate time of any request from its nonce.

Millisecond timestamps are sufficient for most use cases. If you need to fire more than one request per millisecond, increment the nonce by 1 for each additional request within the same millisecond.

Code Examples

import time
nonce = int(time.time() * 1000)   # e.g. 1778572951477

const nonce = Date.now();          // e.g. 1778572951477

import "time"
nonce := time.Now().UnixMilli()    // e.g. 1778572951477

Rules

Rule	Details
Unique per signing address	A nonce already used by that address is rejected with `nonce already used`. The scope is the signing address — an agent wallet keeps its own sequence, independent of its master.
Strictly increasing	Each request from an address must carry a higher nonce than the previous one it accepted.
Within the time window	The nonce is compared against the chain’s clock as a millisecond timestamp. More than 2 days old → `nonce too old`; more than 1 day in the future → `nonce too far in the future`.
Included in the signed message	The nonce is bound into the EIP-712 signature — as a big-endian 8-byte suffix in the Agent-path `actionHash`, or as the final `uint64` field of a typed struct — making it tamper-evident.
int64	Valid range: 1 – 9,223,372,036,854,775,807. A Unix millisecond timestamp fits comfortably within this range for centuries.

A Unix millisecond timestamp satisfies all of these by construction, which is why it is the recommended source.

Rejections

Message	Meaning
`nonce already used`	This exact nonce was accepted before from this address.
`nonce too old`	Below the accepted window — either more than two days behind the chain clock, or below the range still retained for this address.
`nonce too far in the future`	More than one day ahead of the chain clock. A client clock running fast is the usual cause.

Sign requests from one address in sequence, not in parallel. Because each nonce must exceed the last one accepted, two requests signed concurrently can arrive out of order and the lower one is rejected. Assign nonces from a single serialised point per signing address. To parallelise, give each worker its own agent wallet — separate addresses have separate nonce sequences.

Rapid Succession Requests

If you need to submit multiple requests faster than one per millisecond, read the current timestamp once and increment:

import time

base_nonce = int(time.time() * 1000)

for i, action in enumerate(batch_of_actions):
    nonce = base_nonce + i  # guaranteed unique
    # ... sign and send with this nonce

Timeouts and retries

This is where a client is most likely to execute an action twice. A timeout or a lost response tells you nothing about whether the request was applied.

Never re-sign a timed-out request with a fresh nonce before reconciling. A new nonce makes it a new, valid request — if the original did land, you have now executed it twice. This is the single most common way an automated client double-trades.

The safe procedure:

Re-send the identical signed payload

Byte for byte — the same action, the same nonce, the same signature. If the original was applied, this one is rejected as nonce already used and nothing happens twice. Retrying the same bytes is always safe; it is the only retry that is.

Treat the rejection as inconclusive

nonce already used means “this nonce was consumed”, not “your order rested”. It does not tell you the outcome of the original request.

Reconcile by querying

Establish what actually happened from the read side, never by inference.

Action	Reconcile with
`order`	`userOrders`, then `orderHistory` if it may already have terminated; correlate on the `c` (client order ID) you assigned
`cancel` family	`userOrders` — absence of the order is the confirmation
`registerAccount`	`accountByAddress` — a non-`"0"` `accountId` means it succeeded
Collateral moves	`userAccount` — compare balances before and after

Only then decide

Issue a new signed request with a fresh nonce only once the query shows the original did not take effect.

Always set the client order ID c on orders you may need to reconcile. Without it, matching a submitted order to what you find in userOrders after a lost response is guesswork.

The alpha test invitation code is single-use and consumed during registration. If a registerAccount response is lost, check accountByAddress before requesting another code — the original may have succeeded and spent the code.

Overview

Authentication

Request Format

Reference

SDKs

What Is the Nonce?

Recommended Value

Code Examples

Rules

Rejections

Rapid Succession Requests

Timeouts and retries

​What Is the Nonce?

​Recommended Value

​Code Examples

​Rules

​Rejections

​Rapid Succession Requests

​Timeouts and retries

What Is the Nonce?

Recommended Value

Code Examples

Rules

Rejections

Rapid Succession Requests

Timeouts and retries