Place Order

Submit trading orders

Endpoint

POST /exchange

Description

Place market or limit orders for perpetual markets. Supports single or batch orders with signature verification.

Request Body

Parameter	Type	Description
action*	object	See below
action.type*	string	Must be "order"
action.orders*	array	See below
action.orders[].a*	string	Asset ID as 8-char hex string (4 bytes), e.g., "01000000"
action.orders[].b*	boolean	true = buy, false = sell
action.orders[].p	string	Limit price (required for limit orders), e.g., "50000.0"
action.orders[].s*	string	Order size, e.g., "0.1" for 0.1 BTC
action.orders[].r	boolean	Reduce-only flag (default: false)
action.orders[].t*	object	Order type configuration, e.g., {"limit":{"tif":"Gtc"}}
action.orders[].t.limit.tif	string	Time-in-force: "Gtc", "Alo", "Ioc"
action.orders[].t.trigger.isMarket	boolean	true for stop-market, false for stop-limit
action.orders[].t.trigger.triggerPx	string	Trigger price for stop orders
action.orders[].t.trigger.tpsl	string	"tp" (take profit) or "sl" (stop loss)
action.orders[].c	number	Optional client order id (cloid)
action.orders[].isPositionTpsl	boolean	Optional flag for position TP/SL orders
action.grouping	string	Order grouping: "na", "normalTpsl", "positionTpsl"
nonce*	number	Timestamp in milliseconds for replay protection, e.g., 1701234567890
expiresAfter	number	Optional expiration timestamp (ms)
signature*	object	See below
signature.r*	string	First 32 bytes of signature (hex string), e.g., "0x1234..."
signature.s*	string	Second 32 bytes of signature (hex string), e.g., "0x5678..."
signature.v*	number	Recovery ID (27 or 28)

Response

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        { "resting": { "oid": "0x1a2b3c4d5e6f7890..." } }
      ]
    }
  },
  "metadata": [
    {
      "orderId": "0x1a2b3c4d5e6f7890...",
      "status": "committed"
    }
  ]
}

Response Fields

Field	Type	Description
status	string	”ok” on success
response.data.statuses	array	Status for each order
statuses[].resting.oid	string	Order ID (128-bit hex string, if accepted)
statuses[].error	string	Error message (if rejected)
metadata	array	Additional processing details for each order
metadata[].orderId	string	Internal order ID
metadata[].status	string	”committed” or “rejected”
metadata[].error	string	Error details (if rejected)

Example Request

curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "order",
      "orders": [{
        "a": "01000000",
        "b": true,
        "p": "50000.0",
        "s": "0.1",
        "r": false,
        "t": { "limit": { "tif": "Ioc" } }
      }],
      "grouping": "na"
    },
    "nonce": 1701234567890,
    "signature": {
      "r": "0x1234...",
      "s": "0x5678...",
      "v": 27
    }
  }'

Error Responses

{
  "status": "ok",
  "response": {
    "data": {
      "statuses": [
        { "error": "Insufficient margin" }
      ]
    }
  }
}

Notes

• Order IDs (oid) are 128-bit hex strings derived from signature + index
• Time-in-force options: "Gtc" (Good-til-cancel), "Alo" (Add-liquidity-only), "Ioc" (Immediate-or-cancel)
• Maximum 20 orders per request
• Orders are idempotent based on signature
• action.orders[].a is a 4-byte AssetId encoded as 8 hex characters