Skip to main content

Options Trading

The Options API lets you trade US single-leg options and multi-leg option strategies from your JP account through the same unified order endpoints. Options are differentiated by setting instrument_type: OPTION and providing option-specific parameters including the legs array with strike price, expiration, and option type. A single-leg order has one item in legs; a multi-leg strategy order lists every leg of the strategy in legs.

For stock trading, see the dedicated Stock Trading page.

Supported Order Types​

Order TypeDescription
MARKETExecute at the current market price
LIMITExecute at the specified price or better
STOP_LOSSTrigger a market order when the stop price is reached
STOP_LOSS_LIMITTrigger a limit order when the stop price is reached

Time in Force​

ValueDescription
DAYValid for the current trading day only
GTCGood till cancelled

Trading Session​

ValueDescription
CORECore trading session only

Supported Strategies​

StrategyDescription
SINGLESingle-leg option order
COVERED_STOCKBuy/sell stock + sell/buy call (covered call or buy-write)
VERTICALTwo options of the same type and expiration with different strikes
STRADDLEBuy/sell a call and put at the same strike and expiration
STRANGLEBuy/sell a call and put at different strikes, same expiration
CALENDARTwo options of the same type and strike with different expirations
DIAGONALTwo options of the same type with different strikes and expirations
BUTTERFLYThree-strike strategy combining a bull and bear spread
CONDORFour-strike strategy with two middle strikes
IRON_BUTTERFLYSell a straddle and buy a strangle for protection
IRON_CONDORSell a strangle and buy a wider strangle for protection
COLLAR_WITH_STOCKOwn stock + buy put + sell call
info

option_strategy is provided for reference only and is not used for order validation. The system determines the actual strategy from the composition of legs.

Key Parameters​

Order-Level Parameters (new_orders[])​

ParameterRequiredDescription
client_order_idYesUnique client-defined order ID (max 32 chars, must be unique per account)
combo_typeYesNORMAL for standard orders
option_strategyYesStrategy type (see Supported Strategies). SINGLE for single-leg orders
instrument_typeYesOPTION
marketYesUS
symbolYesUnderlying symbol (e.g., AAPL)
order_typeYesMARKET, LIMIT, STOP_LOSS, or STOP_LOSS_LIMIT
sideYesBUY or SELL
quantityYesNumber of contracts
entrust_typeYesQTY (only quantity-based orders are supported)
time_in_forceYesDAY or GTC
support_trading_sessionNoCORE (default)
limit_priceConditionalRequired for LIMIT and STOP_LOSS_LIMIT
stop_priceConditionalRequired for STOP_LOSS and STOP_LOSS_LIMIT
account_tax_typeYesTax account type: GENERAL
margin_typeNoMargin account only: ONE_DAY or INDEFINITE
position_intentNoMargin account only: BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, or SELL_TO_CLOSE
close_contractsNoArray of contract details for closing specific positions (max 10)
leg_in_or_outNoLEG_IN — add this leg to an existing position; LEG_OUT — close this leg from an existing multi-leg strategy position
position_idConditionalPosition identifier of the target leg. Obtained from Account Positions. Required when leg_in_or_out is specified
legsYesOption leg details (see below). One item for SINGLE; every leg of the strategy for multi-leg orders

Leg Parameters (legs[])​

ParameterRequiredDescription
instrument_typeYesOPTION
marketYesUS
symbolYesUnderlying symbol (e.g., AAPL)
sideYesBUY or SELL
strike_priceYesStrike price of the option
option_expire_dateYesExpiration date in YYYY-MM-DD format
option_typeYesCALL or PUT
quantityYesNumber of contracts for this leg

Request Examples — Single-Leg​

Buy 1 AAPL call option at a limit price of $11.00, strike price $220, expiring 2026-06-19. Using a general tax account.

{
  "account_id": "<your_account_id>",
  "new_orders": [
    {
      "client_order_id": "<unique_id>",
      "combo_type": "NORMAL",
      "option_strategy": "SINGLE",
      "instrument_type": "OPTION",
      "market": "US",
      "symbol": "AAPL",
      "order_type": "LIMIT",
      "limit_price": "11.0",
      "side": "BUY",
      "quantity": "1",
      "entrust_type": "QTY",
      "time_in_force": "DAY",
      "account_tax_type": "GENERAL",
      "legs": [
        {
          "instrument_type": "OPTION",
          "market": "US",
          "symbol": "AAPL",
          "side": "BUY",
          "strike_price": "220.0",
          "option_expire_date": "2026-06-19",
          "option_type": "CALL",
          "quantity": "1"
        }
      ]
    }
  ]
}

Request Examples — Multi-Leg​

For multi-leg orders, quantity, side, and limit_price at the order level apply to the strategy as a whole, while each item in legs describes one option contract of the strategy.

Bull call spread on AAPL: buy a $220 call and sell a $230 call with the same expiration, at a net debit limit price of $2.50.

{
  "account_id": "<your_account_id>",
  "new_orders": [
    {
      "client_order_id": "<unique_id>",
      "combo_type": "NORMAL",
      "option_strategy": "VERTICAL",
      "instrument_type": "OPTION",
      "market": "US",
      "symbol": "AAPL",
      "order_type": "LIMIT",
      "limit_price": "2.5",
      "side": "BUY",
      "quantity": "1",
      "entrust_type": "QTY",
      "time_in_force": "DAY",
      "account_tax_type": "GENERAL",
      "legs": [
        {
          "instrument_type": "OPTION",
          "market": "US",
          "symbol": "AAPL",
          "side": "BUY",
          "strike_price": "220.0",
          "option_expire_date": "2026-11-20",
          "option_type": "CALL",
          "quantity": "1"
        },
        {
          "instrument_type": "OPTION",
          "market": "US",
          "symbol": "AAPL",
          "side": "SELL",
          "strike_price": "230.0",
          "option_expire_date": "2026-11-20",
          "option_type": "CALL",
          "quantity": "1"
        }
      ]
    }
  ]
}
tip

Use Preview Order with the same request body to check the estimated cost of a multi-leg order before placing it.

Leg In / Leg Out​

You can adjust an existing position one leg at a time instead of placing a full strategy order:

  • LEG_IN — Add a leg to an existing position (e.g., sell a call against an existing long call to form a spread).
  • LEG_OUT — Close one leg of an existing multi-leg strategy position while keeping the other legs open.

Workflow:

  1. Call Account Positions and find the target position. Multi-leg positions are returned with option_strategy and a legs array.
  2. Take the position_id of the target position.
  3. Place the order with leg_in_or_out set to LEG_IN or LEG_OUT, position_id set to the value from step 2, and the leg to add or close in legs.
caution

position_id is required whenever leg_in_or_out is specified.

Modifying Multi-Leg Orders​

Use Replace Order to change the price or quantity of an open multi-leg order. For multi-leg orders, legs is required and must contain every leg of the order, identified by the leg id returned in the order query APIs (Order Detail / Open Orders).

{
  "account_id": "<your_account_id>",
  "modify_orders": [
    {
      "client_order_id": "<original_client_order_id>",
      "limit_price": "2.3",
      "quantity": "2",
      "legs": [
        { "id": "<leg_id_1>", "quantity": "2" },
        { "id": "<leg_id_2>", "quantity": "2" }
      ]
    }
  ]
}
caution

A replace request cannot change the strategy structure. To add or remove legs, or to change the strike price, expiration date, or side of a leg, cancel the order and place a new one.

What's Next​

  • Accounts — Query positions and obtain position_id for Leg In / Leg Out
  • Stock Trading — Stock and ETF order management (JP supports US stock trading)
  • Trading API FAQ — Common questions and troubleshooting