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

# Nonce Requirements and Replay Protection on Upside

> Understand the nonce field in POST /exchange requests — how to generate it, uniqueness rules, and how it protects against replay attacks.

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 server recognises and rejects any nonce it has already seen from that signer.

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

```json theme={"system"}
{
  "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.

<Tip>
  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.
</Tip>

## Code Examples

**Python**

```python theme={"system"}
import time

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

**JavaScript / TypeScript**

```javascript theme={"system"}
const nonce = Date.now(); // e.g. 1778572951477
```

**Go**

```go theme={"system"}
import "time"

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

## Rules

| Rule                               | Details                                                                                                                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Must be unique per signer**      | The server rejects any nonce that has already been used by the same signing address.                                                                                                       |
| **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.                                                                 |

## Rapid Succession Requests

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

```python theme={"system"}
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
```

<Warning>
  Do not reuse a nonce under any circumstances — even after a failed request. The server may have partially processed the request before returning an error, and reusing the nonce will cause the retry to be rejected.
</Warning>