# Advanced Order Types and Time in Force

> Configure limit, stop, stop-limit, GTC, DAY, and GTD orders and understand their trigger, expiry, escrow, and cancellation behavior.

| Order type | Required fields | Initial behavior |
| --- | --- | --- |
| MARKET | `quoteId` | Executes against the current dealing workflow. |
| LIMIT | `limitPrice` | Rests as `WORKING` until executable or cancelled. |
| STOP | `stopPrice` | Rests until the trigger is crossed, then enters the execution queue. |
| STOP_LIMIT | `stopPrice`, `limitPrice` | Triggers into a limit order. |

These order types are supported in both production and sandbox. Sandbox reserves BUY cash or SELL
units while the order is `WORKING`; `DELETE /users/{userId}/orders/{orderId}` cancels it and releases
that reservation, while the execution simulator can advance it through fill/reject scenarios.

Prices (`limitPrice`, `stopPrice`) are always in the instrument's **local trading currency** — the same
units a quote's `price` is quoted in, so you never have to convert.

Resting orders are available on **both** the master account and sub-accounts, and behave identically:

| | Master account | Sub-account |
| --- | --- | --- |
| Place | `POST /trade` | `POST /users/{userId}/trade` |
| Modify | `PATCH /orders/{orderId}` | `PATCH /users/{userId}/orders/{orderId}` |
| Cancel | `DELETE /orders/{orderId}` | `DELETE /users/{userId}/orders/{orderId}` |

A MARKET order is quote-gated and requires a `quoteId`. A resting order is **not** — you are setting
the price yourself — so it can be placed while the exchange is closed, which is the point: it triggers
when the market reopens and the price crosses.

## Time in force

- `GTC` keeps the order live until execution or cancellation (the default).
- `DAY` automatically cancels if it is not executed within 24 hours.
- `GTD` cancels at `expiresAt`; the timestamp is required.
- `IOC` and `FOK` are **not supported**. Orders execute automatically on the MyStocks internal book rather than an external exchange
  matching engine, so immediate-or-cancel semantics cannot be honoured. Submitting `IOC` returns a
  `400` explaining this.

## Modifying a resting order

`PATCH` an order to change `limitPrice`, `stopPrice`, and/or `quantity`, keeping the same `orderId`.
Only `WORKING` resting orders can be modified — a MARKET order is already `PENDING` for automatic internal-book execution
and can only be cancelled. Check `replaceable` on the order to know which applies.

An `Idempotency-Key` is **required**, because a replace moves money: a BUY re-escrows the difference
(and is refused with `INSUFFICIENT_FUNDS` if the wallet cannot cover an increase), and a SELL adjusts
the reserved units. A replace is repriced on the same FX basis and fee rates captured when the order
was first placed, so modifying an order never silently reprices it against a newer rate. The response
carries `escrowAdjustment` on a BUY, and an `order.replaced` event is emitted.

```bash
curl -X PATCH https://mystocks.africa/api/v1/partner/orders/{orderId} \
  -H "Authorization: Bearer pk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "limitPrice": 18.50, "quantity": 200 }'
```

On expiry or cancellation, BUY escrow is refunded and SELL reservations are released. An `order.cancelled` event is emitted. Do not infer a fill from a trigger; inspect executions and final order status.