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

# TWAP Order

## Endpoint

```text theme={null}
POST /exchange
```

## Request Body

| Parameter                  | Type    | Description                                               |
| -------------------------- | ------- | --------------------------------------------------------- |
| `action`\*                 | object  | See below                                                 |
| `action.type`\*            | string  | Must be `"twapOrder"`                                     |
| `action.asset`\*           | string  | 8-char `HL_Perp` or `HL_SpotPair` AssetId hex string      |
| `action.isBuy`\*           | boolean | `true` for buy, `false` for sell                          |
| `action.sz`\*              | string  | Total TWAP size                                           |
| `action.reduceOnly`\*      | boolean | Reduce-only execution for perps; must be `false` for spot |
| `action.durationMinutes`\* | number  | Total schedule duration in minutes                        |
| `action.numSlices`\*       | number  | Number of TWAP suborders to schedule                      |
| `action.randomize`\*       | boolean | Whether to randomize suborder timing within the schedule  |
| `nonce`\*                  | number  | Replay-protection nonce                                   |
| `expiresAfter`             | number  | Optional expiration timestamp in ms                       |
| `signature`\*              | object  | EIP-712 signature                                         |

## Response

```json theme={null}
{
  "status": "ok",
  "response": {
    "type": "twapOrder",
    "data": {
      "status": "pending",
      "twapOrderId": "0x1a2b3c..."
    }
  }
}
```

### Response Fields

| Field                       | Type                        | Description                                                       |
| --------------------------- | --------------------------- | ----------------------------------------------------------------- |
| `response.data.status`      | `"pending"` \| `"rejected"` | `pending` means the TWAP was accepted into the event pipeline     |
| `response.data.twapOrderId` | string \| undefined         | Deterministic TWAP id, present on accepted requests               |
| `response.data.error`       | string \| undefined         | Rejection reason when the request reaches handler logic but fails |

## Example Request

Perp TWAP:

```bash theme={null}
curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "twapOrder",
      "asset": "00020000",
      "isBuy": true,
      "sz": "0.25",
      "reduceOnly": false,
      "durationMinutes": 30,
      "numSlices": 7,
      "randomize": true
    },
    "nonce": 1701234567890,
    "signature": {
      "r": "0x1234...",
      "s": "0x5678...",
      "v": 27
    }
  }'
```

Spot TWAPs use an `HL_SpotPair` asset id, not the raw `HL_Spot` token asset id:

```bash theme={null}
curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "twapOrder",
      "asset": "000304c5",
      "isBuy": false,
      "sz": "1.5",
      "reduceOnly": false,
      "durationMinutes": 30,
      "numSlices": 7,
      "randomize": true
    },
    "nonce": 1701234567890,
    "signature": {
      "r": "0x1234...",
      "s": "0x5678...",
      "v": 27
    }
  }'
```

## Notes

<Note>
  * `twapOrderId` is deterministic from the signed request transaction id. - Schedules must satisfy
    the current suborder interval bounds enforced by Notional: minimum 10 seconds and maximum 10
    minutes between suborders. - Perp TWAPs validate current mark price, first-suborder margin, and
    minimum suborder notional before acceptance. - Spot TWAPs validate the spot pair's base token
    price, first-suborder source balance, and minimum suborder notional before acceptance. Spot buys
    use the existing protocol spot-prefund flow for each slice. - Reduce-only TWAPs are perp-only and
    are checked against the remaining closable size after existing reduce-only orders and active TWAP
    reservations. - Accepted TWAPs begin with `response.data.status: "pending"` and then progress
    through `twapListActive`, `twapListHistory`, and WebSocket `twapUpdates`.
</Note>