> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/guides/order-types.md). # Order Types `OrderRequest` is the body of every order-placing operation — `POST /orders`, `POST /orders/batch` (as array elements) and `POST /orders/preview`, plus their `/api/v1` twins. **This page is the cross-operation context the generated endpoint pages deliberately do not carry.** Those pages state what the contract declares for one operation; the requirement matrix below is what you need to construct a valid order at all, and it is identical across all of them. For the trader-facing view of what each type is *for*, see [Order Types](https://docs.nexus.xyz/exchange/trading/perpetuals/order-types) in the Exchange section. ## Order placement schema `OrderRequest` is the body of `POST /orders`, `POST /orders/batch` (as array elements), and `POST /orders/preview`, plus their `/api/v1` twins. It supports plain `Limit` and `Market` orders and six conditional order types (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`, `TrailingStop`, `TrailingLimit`). Field requirements depend on `order_type`: * **Limit-family** (`Limit`, `StopLimit`, `TakeProfitLimit`) require a limit `price`. * **Triggerable, non-trailing** orders (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`) require a `trigger_price` (the legacy `stop_price` field is accepted as a fallback when `trigger_price` is absent). * **`TrailingStop`** is market-only — it fires as a market order — and requires `trailing_offset_bps`. It does not take a limit `price` or a `trigger_price` (the trigger anchor is derived from the mark price and the offset). * **`TrailingLimit`** trails like `TrailingStop` but fires a limit order instead of a market order. It requires both `trailing_offset_bps` (the trailing trigger) and `limit_offset_bps` (the fire-time limit offset). It does not take `price`, `trigger_price`, or `stop_price`; the limit price is computed at fire time from the mark that crossed the offset. ### Required fields by order type `market_id`, `side`, `order_type`, `quantity`, and `time_in_force` are required for **every** order type. The four conditional fields resolve as follows: | `order_type` | `price` | `trigger_price` | `trailing_offset_bps` | `limit_offset_bps` | Fires as | | ------------------ | ------------ | --------------- | --------------------- | ------------------ | ------------------------ | | `Limit` | **Required** | Not used | Ignored | Ignored | — (rests immediately) | | `Market` | Omit | Not used | Ignored | Ignored | — (executes immediately) | | `StopLimit` | **Required** | **Required** | Ignored | Ignored | Limit | | `StopMarket` | Omit | **Required** | Ignored | Ignored | Market | | `TakeProfitLimit` | **Required** | **Required** | Ignored | Ignored | Limit | | `TakeProfitMarket` | Omit | **Required** | Ignored | Ignored | Market | | `TrailingStop` | Not taken | Not taken | **Required** | Ignored | Market | | `TrailingLimit` | Not taken | Not taken | **Required** | **Required** | Limit | Reading the matrix: * **Required** — the request is rejected without it. * **Omit** — the field is not part of a market-family order; there is no limit price to set. * **Not used** / **Not taken** — the contract states the field is not used by this order type; the trailing types derive their trigger from the mark price and the offset instead. * **Ignored** — the field may be present but has no effect for this order type. The four triggerable, non-trailing types differ only in trigger direction: `StopLimit` and `StopMarket` fire when the mark price crosses `trigger_price` in the **adverse** direction; `TakeProfitLimit` and `TakeProfitMarket` fire on the **favorable** direction. ### `stop_price` is deprecated `stop_price` is **deprecated in favour of `trigger_price`**. The rules are exact: * `trigger_price` is the canonical trigger threshold. * `stop_price` is accepted **only as a fallback**, when `trigger_price` is absent. * When **both** are supplied, **`trigger_price` wins** and `stop_price` is disregarded. * Both are ignored entirely for `Limit`, `Market`, `TrailingStop`, and `TrailingLimit` orders. New integrations should send `trigger_price` and never `stop_price`. ### Time in force `time_in_force` is required on every order and takes one of four policies: | Value | Meaning | | ---------- | --------------------------------------------------------------------------------------------------------- | | `GTC` | Good-till-cancelled — rests on the book until filled or cancelled. | | `IOC` | Immediate-or-cancel — fills what it can immediately, cancels the remainder. | | `FOK` | Fill-or-kill — fills in full immediately or is cancelled entirely. | | `PostOnly` | Rejects the order if it would take liquidity (cross the book) on entry, guaranteeing it rests as a maker. | `PostOnly` is the only value the contract describes in detail; the description above for `GTC`, `IOC`, and `FOK` states the standard meaning of each acronym, which the contract itself does not spell out. ### `OrderRequest` fields | Field | Type | Required | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | string | Yes | Market identifier, e.g. `BTC-USDX-PERP`. | | `side` | `Buy` / `Sell` | Yes | Order side. | | `order_type` | `Limit` / `Market` / `StopLimit` / `StopMarket` / `TakeProfitLimit` / `TakeProfitMarket` / `TrailingStop` / `TrailingLimit` | Yes | Order type. `Limit` and `Market` are unconditional. The remaining six are conditional: `StopLimit` / `StopMarket` fire when the mark price crosses `trigger_price` in the adverse direction; `TakeProfitLimit` / `TakeProfitMarket` fire on the favorable direction; `TrailingStop` fires as a market order when the mark retraces from its best-seen extreme by `trailing_offset_bps`; `TrailingLimit` fires the same way but rests a limit order priced off the fire price by `limit_offset_bps`. | | `price` | decimal string | Conditional | Limit price. Required for limit-family orders (`Limit`, `StopLimit`, `TakeProfitLimit`); omit for market-family and trailing orders. | | `quantity` | decimal string | Yes | Order size. Arbitrary-precision decimal serialized as a string (lossless) — parse with a decimal type, never a float. | | `time_in_force` | `GTC` / `IOC` / `FOK` / `PostOnly` | Yes | Time-in-force policy. `PostOnly` rejects the order if it would take liquidity (cross the book) on entry, guaranteeing it rests as a maker. | | `reduce_only` | boolean | No | The contract declares the field with no description; see [Open questions](#open-questions). | | `stop_price` | decimal string or null | No — **deprecated** | **Deprecated** — use `trigger_price` instead. Legacy trigger threshold for the stop / take-profit family. Accepted as a fallback only when `trigger_price` is absent; when both are supplied, `trigger_price` wins. Ignored for `Limit`, `Market`, `TrailingStop`, and `TrailingLimit` orders. | | `trigger_price` | decimal string or null | Conditional | Canonical trigger threshold for triggerable, non-trailing orders (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`), which require it (the legacy `stop_price` field is accepted as a fallback when this is omitted). Not used by `Limit`, `Market`, `TrailingStop`, or `TrailingLimit` orders. | | `trailing_offset_bps` | integer (minimum 0) or null | Conditional | Trailing offset in basis points (1 bp = 0.01%). Required for `TrailingStop` and `TrailingLimit` orders; ignored for all other order types. The trailing trigger fires once the mark price retraces from its best-seen extreme by this many basis points: `TrailingStop` fires a market order, `TrailingLimit` fires a limit order priced by `limit_offset_bps`. A value of `0` is accepted and fires the trigger at the first mark-price evaluation after placement (no retracement required). | | `limit_offset_bps` | integer (0–9999) or null | Conditional | Offset in basis points for the fired limit price (`TrailingLimit` only; required together with `trailing_offset_bps`). When the trailing trigger fires at `fire_price`, the injected limit order rests at `fire_price` × (1 + offset) for buys / × (1 − offset) for sells, tick-rounded toward the tighter bound. A value of `0` rests the limit exactly at `fire_price`. Ignored for other order types. | ### Order admission is governed by the margin inequality Order admission is not a free-form validation: an order is accepted only if the account still satisfies the initial-margin requirement once the order's own reservation is included. That is the order-admission inequality **(M.13)** in the Exchange's margin model — see [Margin math](https://docs.nexus.xyz/math-engine/margin-math). A `400` on `POST /orders` with an insufficient-margin reason is that inequality failing. Use `POST /orders/preview` to evaluate it without submitting. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/api-reference/guides/order-types.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.