> ## Documentation Index
> Fetch the complete documentation index at: https://finance.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-Leg Option Order
> Trade spreads, calendars, and ratio strategies as a single atomic order. Learn how legs, ratioQty, and the net limit price work for 2–4 leg options.
A **multi-leg option order** sends **2 to 4 option legs as one order** that fills atomically — either the whole spread executes or none of it does. This is how you trade verticals, calendars, ratio spreads, and similar strategies without legging in manually and taking on execution risk between fills.
It's the same `POST /v1/orders` endpoint and the same `legs` array as a [single-leg option](/api-reference/orders/single-leg-option) — you just include 2–4 legs.
**Leg count drives the shape:** `2–4` legs = multi-leg option order. The maximum is **4 legs**. See [Order Flow](/api-reference/orders/order-flow#how-the-order-type-is-decided).
***
## Strategies you can express
| Strategy | Structure | Legs |
| -------------------------------- | ----------------------------------------------------------------------- | ---- |
| **Vertical spread** | Same expiration, different strikes (e.g. buy 150C / sell 155C) | 2 |
| **Calendar (horizontal) spread** | Same strike, different expirations | 2 |
| **Ratio spread** | Unequal leg quantities (e.g. buy 1 / sell 2) — expressed via `ratioQty` | 2–3 |
| **Iron condor / butterfly** | Four legs combining puts and calls | 3–4 |
Each leg independently sets its own `side`, `putCall`, `strikePrice`, `maturity`, and `positionEffect`, so you can describe any of these.
***
## How quantity works: `qty` and `ratioQty`
This is the one concept unique to multi-leg orders.
* **`ratioQty`** on each leg is the leg's share of the spread **ratio** — e.g. a 1:1 vertical has `ratioQty: "1"` on both legs; a 1:2 ratio spread has `"1"` and `"2"`.
* **`qty`** at the order level is the **number of spreads** (the greatest common divisor of the leg quantities). Placing 5 of a 1:1 vertical → order `qty: "5"`, each leg `ratioQty: "1"`. The actual contracts traded per leg = `qty × ratioQty`.
**Net price.** For a multi-leg `LIMIT` order, `price` is the **net** debit or credit for the whole spread, not a per-leg price. A `BUY` order with a positive `price` is a net debit; selling a spread for a credit uses the corresponding sell side.
***
## Leg fields (recap)
Same leg schema as single-leg options — repeated per leg:
| Field | Required | Notes |
| ---------------- | -------- | --------------------------------------------------------------- |
| `securityType` | yes | `OPT`. |
| `side` | yes | `BUY` or `SELL` for this leg (`B`/`S` accepted). |
| `ratioQty` | yes | This leg's ratio (e.g. `"1"`, `"2"`). |
| `putCall` | yes\* | `CALL` or `PUT` (`C`/`P` accepted). \*Required for option legs. |
| `strikePrice` | yes\* | Strike, decimal string. |
| `maturity` | yes\* | `YYYY-MM-DD`. |
| `positionEffect` | yes | `OPEN` or `CLOSE` (`O`/`C` accepted). |
| `symbol` | no | Defaults to the order-level underlying. |
***
## Example — vertical call debit spread
Buy 1 AAPL **$150/$155 call vertical** expiring 2025-01-17 for a net debit of **\$1.50**. (Buy the 150 call, sell the 155 call.)
```bash cURL theme={null}
curl -X POST https://api.aries.com/v1/orders \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "1",
"price": "1.50",
"timeInForce": "DAY",
"legs": [
{
"side": "BUY",
"ratioQty": "1",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "150.00",
"maturity": "2025-01-17",
"positionEffect": "OPEN"
},
{
"side": "SELL",
"ratioQty": "1",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "155.00",
"maturity": "2025-01-17",
"positionEffect": "OPEN"
}
]
}'
```
### Example — calendar spread (same strike, different expirations)
```json Request body theme={null}
{
"tradingAccountId": "ACC123456",
"symbol": "MSFT",
"side": "BUY",
"type": "LIMIT",
"qty": "1",
"price": "2.20",
"timeInForce": "DAY",
"legs": [
{
"side": "SELL",
"ratioQty": "1",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "420.00",
"maturity": "2025-01-17",
"positionEffect": "OPEN"
},
{
"side": "BUY",
"ratioQty": "1",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "420.00",
"maturity": "2025-02-21",
"positionEffect": "OPEN"
}
]
}
```
### Example — 1×2 ratio spread
Order `qty: "1"` with leg ratios `1` and `2` → trades 1 long and 2 short contracts.
```json Request body theme={null}
{
"tradingAccountId": "ACC123456",
"symbol": "SPY",
"side": "BUY",
"type": "LIMIT",
"qty": "1",
"price": "0.40",
"timeInForce": "DAY",
"legs": [
{
"side": "BUY",
"ratioQty": "1",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "450.00",
"maturity": "2025-01-17",
"positionEffect": "OPEN"
},
{
"side": "SELL",
"ratioQty": "2",
"securityType": "OPT",
"putCall": "CALL",
"strikePrice": "460.00",
"maturity": "2025-01-17",
"positionEffect": "OPEN"
}
]
}
```
Multi-leg constraints: **2–4 legs**, time-in-force **`DAY` or `GTC` only**, and `price` (for `LIMIT`) is the **net** spread price. The whole order fills atomically — you won't be left with one leg of a spread.
***
## Response
```json theme={null}
{
"success": true,
"clOrdId": "CLIENT-200",
"status": "NEW",
"symbol": "AAPL",
"side": "BUY",
"qty": "1",
"cumQty": "0",
"leavesQty": "1",
"avgPrice": "0",
"transactTime": "2024-01-15T11:00:00Z"
}
```
***
## Watch it fill
Multi-leg updates arrive as `account.order` events with `category: "MULTI_LEG"` and every leg echoed in the `legs` array. `qty`/`cumQty` count **spreads**, not individual contracts:
```json account.order — spread partially filled theme={null}
{
"type": "event",
"timestamp": "2024-01-15T11:00:10Z",
"payload": {
"topic": "account",
"name": "account.order",
"target": "account:ACC123456",
"data": {
"ordId": "ORD-67890",
"clOrdId": "CLIENT-200",
"accountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "1",
"price": "1.50",
"ordStatus": "PARTIALLY_FILLED",
"cumQty": "1",
"avgPrice": "1.48",
"securityType": "OPTION",
"category": "MULTI_LEG",
"legs": [
{
"symbol": "AAPL",
"side": "BUY",
"ratioQty": "1",
"securityType": "OPTION",
"maturity": "2025-01-17",
"strikePrice": "150",
"positionEffect": "OPEN",
"putCall": "CALL"
},
{
"symbol": "AAPL",
"side": "SELL",
"ratioQty": "1",
"securityType": "OPTION",
"maturity": "2025-01-17",
"strikePrice": "155",
"positionEffect": "OPEN",
"putCall": "CALL"
}
],
"createdAt": "2024-01-15T11:00:00Z",
"updatedAt": "2024-01-15T11:00:10Z"
}
}
}
```
For the connect/subscribe handshake see [Limit order → Listen for updates](/api-reference/orders/limit-order#listen-for-updates); the [Account Updates WebSocket](/websockets/account-updates) reference covers the option-spread event shape in full.
***
## Next steps
The one-leg foundation these strategies build on.
Find the strikes and expirations to build your legs.
Recap how every order type fits together.
Interactive reference and full schema.