Skip to main content

​
Endpoint

POST /exchange

​
Request Body

ParameterTypeDescription
action*objectSee below
action.type*stringMust be "order"
action.orders*arrayOne or more order specs
action.orders[].a*string8-char AssetId hex string
action.orders[].b*booleantrue for buy, false for sell
action.orders[].p*stringPrice, or "0" for market
action.orders[].s*stringOrder size
action.orders[].rbooleanReduce-only
action.orders[].t*objectLimit or trigger config
action.orders[].cnumberOptional client id
action.orders[].isPositionTpslbooleanOptional position TP/SL flag
action.grouping*string"na", "normalTpsl", or "positionTpsl"
nonce*numberReplay-protection nonce
expiresAfternumberOptional expiration timestamp in ms
signature*objectEIP-712 signature

​
Response

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": {
      "statuses": [
        { "resting": { "oid": "0x1a2b3c..." } },
        { "filled": { "oid": "0x4d5e6f...", "totalSz": "0.1", "avgPx": "50000.0" } },
        {
          "filled": { "oid": "0x7a8b9c...", "totalSz": "0.05", "avgPx": "50010.0" },
          "resting": { "oid": "0x7a8b9c..." }
        },
        { "pending": { "cloid": "0xabcdef..." } }
      ]
    }
  },
  "metadata": {
    "results": [
      { "orderId": "0x1a2b3c...", "status": "accepted", "venueOid": 12345 },
      {
        "orderId": "0x4d5e6f...",
        "status": "filled",
        "venueOid": 12346,
        "totalSz": "0.1",
        "avgPx": "50000.0"
      },
      {
        "orderId": "0x7a8b9c...",
        "status": "partialFill",
        "venueOid": 12347,
        "totalSz": "0.05",
        "avgPx": "50010.0"
      },
      { "orderId": "0xabcdef...", "status": "pending" }
    ]
  }
}

​
Status Variants

Response statusMeaning
resting.oidAccepted by Notional. For standard orders this means resting on the book; for TP/SL child orders it can still represent a locally accepted child awaiting parent fill
filledFully filled immediately
filled + restingPartially filled, remainder resting
pending.cloidSubmitted but venue confirmation timed out
errorValidation, reducer, or venue failure

​
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
    }
  }'

​
Notes

  • Maximum batch size is 20 orders. - action.orders[].a is always an 8-character AssetId hex string. - Supported markets include perpetuals and supported spot-pair sell orders. - metadata.results[].orderId is the internal Notional order id used by cancel and modify.