Proper Options JSON Kata

Johnpaul_Williams · June 7, 2026, 10:22pm

Hello Alpaca Support,

We are using Alpaca Trading API for single-leg long option trading and want to confirm the current correct JSON order shapes.

Our current long-option entry order is:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "buy",
  "position_intent": "buy_to_open",
  "type": "limit",
  "time_in_force": "day",
  "limit_price": "1.23",
  "order_class": "simple",
  "client_order_id": "ms_uniqueid"
}

Our current long-option close order is:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "sell",
  "position_intent": "sell_to_close",
  "type": "market",
  "time_in_force": "day",
  "order_class": "simple",
  "client_order_id": "msfc_uniqueid"
}

Please confirm whether these are currently correct for single-leg long option buy-to-open and sell-to-close orders.

We also want to confirm the currently supported order-type and time-in-force matrix for options:

market + day
market + gtc
limit + day
limit + gtc
stop + day
stop + gtc
stop_limit + day
stop_limit + gtc
trailing_stop + day
trailing_stop + gtc

For each combination, please confirm whether it is supported for single-leg options, and whether position_intent is required or recommended.

Finally, please confirm whether single-leg option BUY orders can use order_class: "oto" or order_class: "bracket" with a stop_loss child leg. If yes, what exact JSON shape is supported? If no, should long-option risk exits be handled as separate sell-to-close orders after fill?

Thank you.

Alpaca option order JSON “kata” 形

Here is the exact order-shape progression to take to Alpaca.

A. Current order format we use now

Current long option BUY / entry

Function:

submitAlpacaOrder_
File: gas/src/01_Alpaca_Execution_Broker.gs

Current shape (Kata):

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "buy",
  "position_intent": "buy_to_open",
  "type": "limit",
  "time_in_force": "day",
  "limit_price": "1.23",
  "order_class": "simple",
  "client_order_id": "ms_<unique>"
}

Meaning:

Long option entry
Simple order
Limit buy
DAY TIF
Explicit buy_to_open
Client order ID included

This aligns with Alpaca’s current Options Trading guide requiring whole-number qty, no notional, extended_hours false/not populated, and option order payload fields such as time_in_force, type, and option order constraints. Alpaca’s guide currently says options time_in_force may be day or gtc, while the Create Order reference still lists options as day, so our current conservative day usage is the safest meeting position.

Current option SELL / close

Function:

_submitAlpacaMarketSell_
File: gas/src/01_Alpaca_Execution_Broker.gs

Current shape:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "sell",
  "position_intent": "sell_to_close",
  "type": "market",
  "time_in_force": "day",
  "order_class": "simple",
  "client_order_id": "msfc_<unique>"
}

Meaning:

Protective/dashboard/profit-protection close
Simple order
Market sell
DAY TIF
Explicit sell_to_close
Client order ID included
Close-only guard checks actual Alpaca position before submitting

Our current verifier confirms the intended logic: long option entries use buy_to_open, close sells use sell_to_close, fixed/trailing native option stops are retired, and software-managed protection exits with sell_to_close. The current Alpaca Create Order docs include position_intent values such as buy_to_open, buy_to_close, sell_to_open, and sell_to_close.

B. Our previous format immediately before the current system

This was the native broker stop/trailing protection era.

The entry was already moving toward:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "buy",
  "position_intent": "buy_to_open",
  "type": "limit",
  "time_in_force": "day",
  "limit_price": "1.23",
  "order_class": "simple",
  "client_order_id": "ms_<unique>"
}

But the protective exits were attempted as broker-native option stop/trailing orders.

Previous fixed stop SELL shape

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "sell",
  "position_intent": "sell_to_close",
  "type": "stop",
  "time_in_force": "gtc",
  "stop_price": "0.95",
  "client_order_id": "msstop_<unique>"
}

Previous trailing stop SELL shape

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "sell",
  "position_intent": "sell_to_close",
  "type": "trailing_stop",
  "time_in_force": "gtc",
  "trail_percent": "25.00",
  "client_order_id": "mstrail_<unique>"
}

Why we moved away from this:

Native option fixed/trailing stop behavior was retired in our code.
Software-managed Profit Protection now submits a close-only market sell only after the rule actually triggers.

Important Alpaca meeting question:

For single-leg long options, do you currently support broker-native stop, stop_limit, or trailing_stop sell_to_close orders through POST /v2/orders? If yes, which type/time_in_force combinations are valid for options today?

The docs are nuanced: the Options Trading guide says market, limit, stop, and stop_limit are allowed for single-leg options, but the Create Order reference still says options TIF is day, and GTC options appear to be a newer, more limited capability. I would ask them to confirm the exact allowed matrix.

C. Older format before that

This was the OTO/bracket/trailing-stop idea that we abandoned.

Approximate earlier idea:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "buy",
  "type": "limit",
  "time_in_force": "day",
  "limit_price": "1.23",
  "order_class": "oto",
  "stop_loss": {
    "type": "trailing_stop",
    "trail_percent": "25.00"
  }
}

Or conceptually:

{
  "symbol": "SPY260608C00759000",
  "qty": "1",
  "side": "buy",
  "type": "limit",
  "time_in_force": "day",
  "order_class": "bracket",
  "stop_loss": {
    "type": "trailing_stop"
  }
}

Why we abandoned it:

Alpaca does not accept type: trailing_stop as the stop_loss leg of an OTO/bracket order in our testing/code notes.
Trailing stops are standalone order types, not stop_loss child legs.

Support question:

Can a single-leg option BUY order use order_class='oto' or order_class='bracket' with a stop_loss child leg? If yes, what exact JSON shape is supported? If no, should all long-option protection be software-managed or separate child orders after fill?

D. GTC options question for Alpaca

Alpaca announced GTC options orders in March 2026, but their educational GTC options guide emphasizes GTC options as limit-order oriented and notes behavior like buying-power reservation and cancellation after 90 days.