TWAP Order

Endpoint

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

{
  "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:

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:

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

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.

API OVERVIEW

READ ENDPOINTS

EXCHANGE ENDPOINTS

WEBSOCKET API

Endpoint

Request Body

Response

Response Fields

Example Request

Notes

​Endpoint

​Request Body

​Response

​Response Fields

​Example Request

​Notes

Endpoint

Request Body

Response

Response Fields

Example Request

Notes