Skip to main content

​
Endpoint

POST /exchange

​
Request Body

ParameterTypeDescription
action*objectSee below
action.type*stringMust be "twapOrder"
action.asset*string8-char HL_Perp or HL_SpotPair AssetId hex string
action.isBuy*booleantrue for buy, false for sell
action.sz*stringTotal TWAP size
action.reduceOnly*booleanReduce-only execution for perps; must be false for spot
action.durationMinutes*numberTotal schedule duration in minutes
action.numSlices*numberNumber of TWAP suborders to schedule
action.randomize*booleanWhether to randomize suborder timing within the schedule
nonce*numberReplay-protection nonce
expiresAfternumberOptional expiration timestamp in ms
signature*objectEIP-712 signature

​
Response

{
  "status": "ok",
  "response": {
    "type": "twapOrder",
    "data": {
      "status": "pending",
      "twapOrderId": "0x1a2b3c..."
    }
  }
}

​
Response Fields

FieldTypeDescription
response.data.status"pending" | "rejected"pending means the TWAP was accepted into the event pipeline
response.data.twapOrderIdstring | undefinedDeterministic TWAP id, present on accepted requests
response.data.errorstring | undefinedRejection 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.