> For the complete documentation index, see [llms.txt](https://docs.gammaswap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gammaswap.com/developers/concepts/nonces.md).

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

```ts
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:

```ts
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.

```ts
nonce: 113377280000000000n
```

```ts
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

{% hint style="warning" %}
Creating a new SDK client for every request also creates separate local nonce state unless a shared `NonceManager` is supplied.
{% endhint %}

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

```ts
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:

```ts
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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gammaswap.com/developers/concepts/nonces.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.