Nonces

Every signed exchange action includes a nonce. Nonces protect signed actions from being submitted more than once.

The SDK generates a nonce automatically when an action’s nonce field is omitted.

await exchange.placeOrder({
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
  // nonce is generated automatically
});

Nonce format

NonceManager generates unsigned 64-bit values using:

[48-bit timestamp in milliseconds][16-bit counter]

The upper 48 bits contain a logical timestamp in milliseconds. The lower 16 bits contain a counter.

Generation behavior

When the physical clock advances:

1. The timestamp is updated.

2. The counter resets to 0.

When another nonce is requested in the same millisecond:

1. The previous logical timestamp is retained.

2. The counter is incremented.

If the system clock moves backward:

1. The previous logical timestamp is retained.

2. The counter continues to increment.

This keeps nonces monotonically increasing within one NonceManager instance.

Per-millisecond capacity

The 16-bit counter ranges from 0 through 65,535.

This allows up to 65,536 nonces in one logical millisecond.

If more nonces are requested before the physical clock advances, the SDK:

1. Advances its logical timestamp by one millisecond.

2. Resets the counter to 0.

3. Continues generating monotonically increasing values.

The SDK does not throw or block in this situation.

Under extremely high throughput, the logical timestamp can move ahead of the wall clock.

Explicit nonces

Applications can provide their own nonce:

await exchange.placeOrder({
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
  nonce: 113377280000000000n,
});

A nonce can be a bigint or canonical unsigned decimal string.

nonce: 113377280000000000n

nonce: "113377280000000000"

Multiple processes

Nonce uniqueness is local to one NonceManager instance.

It does not coordinate across:

• Browser tabs

• Node.js processes

• Application servers

• Devices

• Separate SDK clients

If several processes sign actions using the same address, use one of the following approaches:

• Reuse a shared NonceManager

• Use a centralized nonce service

• Use a shared atomic counter

• Pass coordinated explicit nonces

• Use a separate agent wallet for each independent signing process

Creating a new SDK client for every request also creates separate local nonce state unless a shared NonceManager is supplied.

Nonces and request status

NonceManager only generates the next local value.

It does not track whether an action is:

• Pending

• Accepted

• Rejected

• Filled

• Cancelled

• Already submitted

Applications should track request status separately.

Cancel and replace nonces

Cancel-and-replace uses two signed actions:

• A nonce for the cancel-replace action

• A nonce for the replacement order

await exchange.cancelReplaceOrder({
  assetId,
  epoch,
  cancelOrderHash,
  side: false,
  price: "99.8",
  size: "10.25",
  nonce: cancelReplaceNonce,
  replacementNonce,
});

When omitted, the SDK generates both values.

Agent approval nonce

approvalNonce is different from an action nonce.

• nonce identifies the signed action.

• approvalNonce identifies the active agent approval.

Agent actions accept both:

await agentClient.placeAgentOrder({
  sender: masterAddress,
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
  nonce: actionNonce,
  approvalNonce,
});

When approvalNonce is omitted, agent order, cancel, cancel-replace, and claim methods fetch it through InfoClient.