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

# Place Order

## Endpoint

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

## Request Body

| Parameter             | Type    | Description                                                                                                             |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `action`\*            | object  | See below                                                                                                               |
| `action.type`\*       | string  | Must be `"order"`                                                                                                       |
| `action.orders`\*     | array   | One or more order specs                                                                                                 |
| `action.orders[].a`\* | string  | 8-char AssetId hex string                                                                                               |
| `action.orders[].b`\* | boolean | `true` for buy, `false` for sell                                                                                        |
| `action.orders[].p`\* | string  | Price, or `"0"` for market                                                                                              |
| `action.orders[].s`\* | string  | Order size; use `"0"` only for tracked full-position `positionTpsl` trigger orders                                      |
| `action.orders[].r`   | boolean | Reduce-only                                                                                                             |
| `action.orders[].t`\* | object  | Limit or trigger config                                                                                                 |
| `action.orders[].c`   | number  | Optional client id                                                                                                      |
| `action.grouping`\*   | string  | `"na"` for standalone orders, `"normalTpsl"` for parent-attached TP/SL, or `"positionTpsl"` for position-attached TP/SL |
| `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": "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..." } },
        { "prefunding": { "cloid": "0x1111...", "reason": "protocol_spot_prefund" } },
        { "pendingTrigger": { "cloid": "0x2222..." } },
        { "pendingParentFill": { "cloid": "0x3333..." } }
      ]
    }
  },
  "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" },
      { "orderId": "0x1111...", "status": "prefunding" },
      { "orderId": "0x2222...", "status": "pendingTrigger" },
      { "orderId": "0x3333...", "status": "pendingParentFill" }
    ]
  }
}
```

## Status Variants

| Response status           | Meaning                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resting.oid`             | Accepted 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 |
| `filled`                  | Fully filled immediately                                                                                                                                              |
| `filled` + `resting`      | Partially filled, remainder resting                                                                                                                                   |
| `pending.cloid`           | Submitted but exchange confirmation timed out                                                                                                                         |
| `prefunding.cloid`        | Spot buy accepted locally while protocol spot pre-funding is pending                                                                                                  |
| `pendingTrigger.cloid`    | Local trigger intent accepted and waiting for trigger detection                                                                                                       |
| `pendingParentFill.cloid` | Normal TP/SL child accepted and waiting for the parent order to fill                                                                                                  |
| `error`                   | Validation or exchange failure                                                                                                                                        |

## Example Request

```bash theme={null}
curl -X POST https://api.notional.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "order",
      "orders": [
        {
          "a": "00020000",
          "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

<Note>
  * 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 buy and sell orders. Spot
    buys may return `prefunding` before venue submission. - `metadata.results[].orderId` is the
    internal Notional order id used by cancel and modify. - `action.orders[].isPositionTpsl` is
    internal-only and must not be sent. Use `action.grouping="positionTpsl"` instead. - Resting
    reduce-only limit orders are disabled; use market, IOC, stop, or take-profit reduce-only orders. -
    On reduce-only `positionTpsl` trigger orders, `action.orders[].s = "0"` means "track the full live
    position size"; an explicit positive size creates a fixed-size position TP/SL.
</Note>