> For the complete documentation index, see [llms.txt](https://agentdex.gitbook.io/agentdex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agentdex.gitbook.io/agentdex-docs/trading/order-types.md).

# Order types

AgentDex supports the order primitives a serious trader expects: market, limit (with post-only and hidden modifiers), stop-market / stop-limit (take-profit and stop-loss), and reduce-only. All of them are reachable through REST, WebSocket, and MCP.

### Market

Fills against the best available prices on the book until your size is exhausted or there's no more liquidity. Use when execution certainty matters more than price.

{% code title="Market order via REST" %}

```http
POST /v1/futures/place-order
{ "side": "buy", "instrument_id": "BTC_USDT_PERPETUAL",
  "is_market": true, "quoted_currency_volume": "50" }
```

{% endcode %}

Or via MCP:

{% code title="Market order via MCP" %}

```json
{"name":"place_order",
 "arguments":{"instrument_id":"BTC_USDT_PERPETUAL",
              "side":"buy","type":"market","amount":50}}
```

{% endcode %}

### Limit

Rests on the book at a chosen price. Fills only when an opposite order crosses it.

{% code title="Limit order via REST" %}

```http
POST /v1/futures/place-order
{ "side": "sell", "instrument_id": "BTC_USDT_PERPETUAL",
  "price": "80500", "quoted_currency_volume": "50",
  "is_market": false }
```

{% endcode %}

Modifiers:

* **Hidden** — the order is not visible in the public book; matchers still fill against it. Set `"hidden": true`.
* **Post-only** — rejects the order if it would cross the spread (i.e. it would have been a taker fill). Set `"post_only": true`.

### Stop / Take-profit (TP) / Stop-loss (SL)

Trigger orders evaluated against **mark price** ([Mark price](/agentdex-docs/trading/mark-price.md)). When the mark crosses the trigger, the order is released into the book as either a market or a limit order.

{% code title="Stop order via REST" %}

```http
POST /v1/futures/place-stop-order
{ "side": "sell", "instrument_id": "BTC_USDT_PERPETUAL",
  "trigger_price": "78000", "price": "77900",
  "quoted_currency_volume": "50", "trigger": "mark" }
```

{% endcode %}

A TP/SL can also be attached directly to a position via `positions/tpsl/replace`, in which case it sizes itself to the position automatically.

### Reduce-only

A flag, not a separate type. Any order can be marked `"reduce_only": true`; the matching engine rejects fills that would grow the position past zero (or flip it). Use for stop-loss orders on bots that should never accidentally open a new position.

### Sizing: USDT vs. contracts vs. base

You can size orders three ways:

| Mode                    | Field                                                         | Notes                                                             |
| ----------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Contracts** (default) | `contract_volume`                                             | Integer count of contracts; must be a multiple of `contract_size` |
| **Quote (USDT)**        | `quoted_currency_volume` via `place-order-by-quoted-currency` | Easiest for agents; engine converts to contracts                  |
| **Base**                | `base_currency_volume` via `place-order-by-base-currency`     | Engine converts `floor(amount / contract_size)`                   |

MCP `place_order` always takes USDT (`amount`).

### Order lifecycle

{% code title="Order lifecycle" %}

```
pending  →  open  →  partially_filled  →  filled
                  ↘  cancelled  ↙
                  ↘  rejected
```

{% endcode %}

State changes are streamed over WebSocket (private `order` and `fill` topics — see [Websocket API](/agentdex-docs/developers/websocket-api.md)).

### Cancellation

* `POST /v1/futures/cancel-order` — cancel by order id.
* `POST /v1/futures/cancel-all-orders` — cancel everything for an instrument.
* `POST /v1/futures/cancel-stop-order` — cancel a stop trigger.
* MCP `cancel_all_orders` (`rw` scope) — same as the REST batch version.

A cancellation request is acknowledged once the engine has removed the order from the book; partial fills that occurred before the cancel are already booked and not reversed.

### Error codes

| Code                                    | Meaning                                                                                                                |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST_DATA`                  | Malformed JSON, missing fields, bad `side`                                                                             |
| `INVALID_INSTRUMENT_ID`                 | Instrument unknown or not on your key's allowlist                                                                      |
| `INSTRUMENT_IS_NOT_ACTIVE`              | Instrument paused (e.g. maintenance or pre-launch)                                                                     |
| `INSUFFICIENT_FUNDS`                    | Not enough available balance for the required margin + fee reserve                                                     |
| `ORDER_VOLUME_MISMATCHES_CONTRACT_SIZE` | Volume not a multiple of contract size (only when sizing by contracts)                                                 |
| `AMOUNT_TOO_SMALL`                      | Below the per-instrument minimum                                                                                       |
| `IN_EMERGENCY_MODE`                     | Engine in emergency mode (typically a stale index-price feed — see [Mark price](/agentdex-docs/trading/mark-price.md)) |
| `UNKNOWN_ERROR`                         | Unexpected engine response — retry once, then escalate                                                                 |

The full table lives in the API reference; see [Rest API](/agentdex-docs/developers/rest-api.md) and [Fees](/agentdex-docs/trading/fees.md) for fee fields in fill responses.


---

# 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://agentdex.gitbook.io/agentdex-docs/trading/order-types.md?ask=<question>&goal=<endgoal>
```

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