Multi-Leg Option Order

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

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

cURL

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)

Request body

{
  "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.

Request body

{
  "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

{
  "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:

account.order — spread partially filled

{
  "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; the Account Updates WebSocket reference covers the option-spread event shape in full.

Next steps

Single-leg option

The one-leg foundation these strategies build on.

Options contract symbols

Find the strikes and expirations to build your legs.

Order Flow

Recap how every order type fits together.

Try it live

Interactive reference and full schema.

​Strategies you can express

​How quantity works: qty and ratioQty

​Leg fields (recap)

​Example — vertical call debit spread

​Example — calendar spread (same strike, different expirations)

​Example — 1×2 ratio spread

​Response

​Watch it fill

​Next steps

Single-leg option

Options contract symbols

Order Flow

Try it live

Strategies you can express

How quantity works: `qty` and `ratioQty`

Leg fields (recap)

Example — vertical call debit spread

Example — calendar spread (same strike, different expirations)

Example — 1×2 ratio spread

Response

Watch it fill

Next steps