> 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 The eight order types, the four time-in-force policies, and which fields each one requires. `OrderRequest` is the body of every order-placing operation: `POST /orders`, `POST /orders/batch` (as array elements) and `POST /orders/preview`. **This page covers what applies across operations, which the generated endpoint pages leave out.** 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 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, so 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 venue computes the limit price 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, and there is no limit price to set. * **Not used** / **Not taken.** The contract states this order type does not use the field. 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, and `TakeProfitLimit` and `TakeProfitMarket` fire on the **favorable** direction. ### `stop_price` is deprecated `stop_price` is **deprecated in favour of `trigger_price`**. The rules: * `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 and 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 descriptions above for `GTC`, `IOC`, and `FOK` give 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 it 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 [Known Gaps](/api-reference/guides/known-gaps.md#trading). | | `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, and 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, and `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 The venue accepts an order 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.