Get Started

Placing your first multi-leg options order

Learn how to place multi-leg options strategies like bull call spreads by getting option chain data, running multi-leg preflight checks, placing the strategy, and monitoring execution.

Get your account ID and check options level

Multi-leg options strategies require higher options approval levels (typically Level 2 or above). First, check your account options level:

curl --request GET \
  --url https://api.public.com/userapigateway/trading/account \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Ensure your account has sufficient options level for spread strategies:

{
  "accounts": [
    {
      "accountId": "YOUR_ACCOUNT_ID",
      "accountType": "BROKERAGE",
      "optionsLevel": "LEVEL_2",
      "brokerageAccountType": "MARGIN"
    }
  ]
}

Get option chain data

For a bull call spread, you need to identify two CALL options with different strike prices. Get the option chain to see available strikes:

curl --request POST \
  --url https://api.public.com/userapigateway/marketdata/{YOUR_ACCOUNT_ID}/option-chain \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "instrument": {
      "symbol": "AAPL",
      "type": "EQUITY"
    },
    "expirationDate": "2024-02-16"
  }'

Look for two CALL strikes where you'll buy the lower strike and sell the higher strike:

{
  "baseSymbol": "AAPL",
  "calls": [
    {
      "instrument": {
        "symbol": "AAPL240216C00140000",
        "type": "OPTION"
      },
      "outcome": "SUCCESS",
      "last": "9.75",
      "bid": "9.50",
      "ask": "9.90"
    },
    {
      "instrument": {
        "symbol": "AAPL240216C00150000",
        "type": "OPTION"
      },
      "outcome": "SUCCESS",
      "last": "4.25",
      "bid": "4.10",
      "ask": "4.40"
    }
  ]
}

Run multi-leg preflight check

Before placing a bull call spread, run a multi-leg preflight check to estimate the net cost and validate the strategy. This strategy involves buying the $140 call and selling the $150 call:

curl --request POST \
  --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/preflight/multi-leg \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderType": "LIMIT",
    "expiration": {
      "timeInForce": "DAY"
    },
    "quantity": "1",
    "limitPrice": "5.00",
    "legs": [
      {
        "instrument": {
          "symbol": "AAPL240216C00140000",
          "type": "OPTION"
        },
        "side": "BUY",
        "openCloseIndicator": "OPEN",
        "ratioQuantity": 1
      },
      {
        "instrument": {
          "symbol": "AAPL240216C00150000",
          "type": "OPTION"
        },
        "side": "SELL",
        "openCloseIndicator": "OPEN",
        "ratioQuantity": 1
      }
    ]
  }'

The response shows the estimated net cost and strategy details:

{
  "baseSymbol": "AAPL",
  "strategyName": "Call Spread",
  "legs": [
    {
      "instrument": {
        "symbol": "AAPL240216C00140000",
        "type": "OPTION"
      },
      "side": "BUY",
      "openCloseIndicator": "OPEN",
      "ratioQuantity": 1,
      "optionDetails": {
        "baseSymbol": "AAPL",
        "type": "CALL",
        "strikePrice": "140.00",
        "optionExpireDate": "2024-02-16"
      }
    },
    {
      "instrument": {
        "symbol": "AAPL240216C00150000",
        "type": "OPTION"
      },
      "side": "SELL",
      "openCloseIndicator": "OPEN",
      "ratioQuantity": 1,
      "optionDetails": {
        "baseSymbol": "AAPL",
        "type": "CALL",
        "strikePrice": "150.00",
        "optionExpireDate": "2024-02-16"
      }
    }
  ],
  "estimatedCommission": "1.30",
  "orderValue": "500.00",
  "estimatedQuantity": "1",
  "estimatedCost": "501.30",
  "buyingPowerRequirement": "501.30",
  "regulatoryFees": {
    "orfFee": "0.08",
    "occFee": "0.04"
  }
}

Place the multi-leg options order

Now place the bull call spread order using the multi-leg endpoint. Generate a unique UUID for the orderId:

curl --request POST \
  --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/order/multileg \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderId": "550e8400-e29b-41d4-a716-446655440002",
    "quantity": 1,
    "type": "LIMIT",
    "limitPrice": "5.00",
    "expiration": {
      "timeInForce": "DAY"
    },
    "legs": [
      {
        "instrument": {
          "symbol": "AAPL240216C00140000",
          "type": "OPTION"
        },
        "side": "BUY",
        "openCloseIndicator": "OPEN",
        "ratioQuantity": 1
      },
      {
        "instrument": {
          "symbol": "AAPL240216C00150000",
          "type": "OPTION"
        },
        "side": "SELL",
        "openCloseIndicator": "OPEN",
        "ratioQuantity": 1
      }
    ]
  }'

The response confirms the multi-leg order was submitted:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440002"
}

Monitor order execution

Multi-leg orders can take longer to fill since all legs must execute. Monitor the order status to see execution progress:

curl --request GET \
  --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/order/550e8400-e29b-41d4-a716-446655440002 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response shows the multi-leg order status with individual leg details:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440002",
  "instrument": {
    "symbol": "AAPL_SPREAD",
    "type": "MULTI_LEG_INSTRUMENT"
  },
  "createdAt": "2024-01-15T16:00:00Z",
  "type": "LIMIT",
  "status": "FILLED",
  "quantity": "1",
  "filledQuantity": "1",
  "averagePrice": "4.85",
  "limitPrice": "5.00",
  "expiration": {
    "timeInForce": "DAY"
  },
  "legs": [
    {
      "instrument": {
        "symbol": "AAPL240216C00140000",
        "type": "OPTION"
      },
      "side": "BUY",
      "openCloseIndicator": "OPEN",
      "ratioQuantity": 1
    },
    {
      "instrument": {
        "symbol": "AAPL240216C00150000",
        "type": "OPTION"
      },
      "side": "SELL",
      "openCloseIndicator": "OPEN",
      "ratioQuantity": 1
    }
  ]
}

Verify your spread position

Check your portfolio to see both legs of your bull call spread position:

curl --request GET \
  --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/portfolio/v2 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

You should see both the long and short option positions in your portfolio:

{
  "accountId": "YOUR_ACCOUNT_ID",
  "accountType": "BROKERAGE",
  "buyingPower": {
    "cashOnlyBuyingPower": "4614.70",
    "buyingPower": "9614.70",
    "optionsBuyingPower": "9614.70"
  },
  "positions": [
    {
      "instrument": {
        "symbol": "AAPL240216C00140000",
        "name": "AAPL Feb 16 '24 $140 Call",
        "type": "OPTION"
      },
      "quantity": "1.0",
      "currentValue": "975.00",
      "percentOfPortfolio": "9.75",
      "costBasis": {
        "totalCost": "950.65",
        "unitCost": "950.65",
        "gainValue": "24.35",
        "gainPercentage": "2.56"
      }
    },
    {
      "instrument": {
        "symbol": "AAPL240216C00150000",
        "name": "AAPL Feb 16 '24 $150 Call",
        "type": "OPTION"
      },
      "quantity": "-1.0",
      "currentValue": "-425.00",
      "percentOfPortfolio": "-4.25",
      "costBasis": {
        "totalCost": "-465.00",
        "unitCost": "-465.00",
        "gainValue": "-40.00",
        "gainPercentage": "-8.60"
      }
    }
  ],
  "equity": [
    {
      "type": "OPTIONS_LONG",
      "value": "975.00",
      "percentageOfPortfolio": "9.75"
    },
    {
      "type": "OPTIONS_SHORT",
      "value": "-425.00",
      "percentageOfPortfolio": "-4.25"
    }
  ]
}

📊 Understanding Multi-Leg Options Strategies

Bull Call Spread: Buy a lower strike call, sell a higher strike call. Profit if the stock rises but is limited by the short call.
Net Debit Strategy: You pay to enter this position (buy premium is higher than sell premium received).
Maximum Profit: Strike difference minus net premium paid (e.g., $10 - $4.85 = $5.15 per contract).
Maximum Loss: Limited to the net premium paid ($4.85 per contract in this example).
Breakeven Point: Lower strike plus net premium paid ($140 + $4.85 = $144.85).
ratioQuantity: Typically 1:1 for standard spreads. Some strategies use different ratios.
Multi-leg orders require LIMIT pricing only. The limit price is the net premium for the entire spread.
Execution Risk: All legs must fill together. If only partial fills occur, you may have unwanted single-leg exposure.
Both legs show as separate positions in your portfolio but work together as a unified strategy.

Other multi-leg strategies

The multi-leg endpoint supports various options strategies by adjusting the legs configuration:

// Bear Put Spread (Buy high strike PUT, sell low strike PUT)
{
  "legs": [
    {
      "instrument": {"symbol": "AAPL240216P00150000", "type": "OPTION"},
      "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1
    },
    {
      "instrument": {"symbol": "AAPL240216P00140000", "type": "OPTION"},
      "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1
    }
  ]
}

// Iron Condor (4-leg strategy)
{
  "legs": [
    {"instrument": {"symbol": "AAPL240216P00135000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1},
    {"instrument": {"symbol": "AAPL240216P00140000", "type": "OPTION"}, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1},
    {"instrument": {"symbol": "AAPL240216C00150000", "type": "OPTION"}, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1},
    {"instrument": {"symbol": "AAPL240216C00155000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1}
  ]
}

// Straddle (Buy CALL and PUT at same strike)
{
  "legs": [
    {"instrument": {"symbol": "AAPL240216C00145000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1},
    {"instrument": {"symbol": "AAPL240216P00145000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1}
  ]
}

curl --request POST \ --url https://api.public.com/userapigateway/marketdata/{YOUR_ACCOUNT_ID}/option-chain \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "instrument": { "symbol": "AAPL", "type": "EQUITY" }, "expirationDate": "2024-02-16" }'

{ "baseSymbol": "AAPL", "calls": [ { "instrument": { "symbol": "AAPL240216C00140000", "type": "OPTION" }, "outcome": "SUCCESS", "last": "9.75", "bid": "9.50", "ask": "9.90" }, { "instrument": { "symbol": "AAPL240216C00150000", "type": "OPTION" }, "outcome": "SUCCESS", "last": "4.25", "bid": "4.10", "ask": "4.40" } ] }

curl --request POST \ --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/preflight/multi-leg \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "orderType": "LIMIT", "expiration": { "timeInForce": "DAY" }, "quantity": "1", "limitPrice": "5.00", "legs": [ { "instrument": { "symbol": "AAPL240216C00140000", "type": "OPTION" }, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1 }, { "instrument": { "symbol": "AAPL240216C00150000", "type": "OPTION" }, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1 } ] }'

{ "baseSymbol": "AAPL", "strategyName": "Call Spread", "legs": [ { "instrument": { "symbol": "AAPL240216C00140000", "type": "OPTION" }, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1, "optionDetails": { "baseSymbol": "AAPL", "type": "CALL", "strikePrice": "140.00", "optionExpireDate": "2024-02-16" } }, { "instrument": { "symbol": "AAPL240216C00150000", "type": "OPTION" }, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1, "optionDetails": { "baseSymbol": "AAPL", "type": "CALL", "strikePrice": "150.00", "optionExpireDate": "2024-02-16" } } ], "estimatedCommission": "1.30", "orderValue": "500.00", "estimatedQuantity": "1", "estimatedCost": "501.30", "buyingPowerRequirement": "501.30", "regulatoryFees": { "orfFee": "0.08", "occFee": "0.04" } }

curl --request POST \ --url https://api.public.com/userapigateway/trading/{YOUR_ACCOUNT_ID}/order/multileg \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "orderId": "550e8400-e29b-41d4-a716-446655440002", "quantity": 1, "type": "LIMIT", "limitPrice": "5.00", "expiration": { "timeInForce": "DAY" }, "legs": [ { "instrument": { "symbol": "AAPL240216C00140000", "type": "OPTION" }, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1 }, { "instrument": { "symbol": "AAPL240216C00150000", "type": "OPTION" }, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1 } ] }'

{ "orderId": "550e8400-e29b-41d4-a716-446655440002", "instrument": { "symbol": "AAPL_SPREAD", "type": "MULTI_LEG_INSTRUMENT" }, "createdAt": "2024-01-15T16:00:00Z", "type": "LIMIT", "status": "FILLED", "quantity": "1", "filledQuantity": "1", "averagePrice": "4.85", "limitPrice": "5.00", "expiration": { "timeInForce": "DAY" }, "legs": [ { "instrument": { "symbol": "AAPL240216C00140000", "type": "OPTION" }, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1 }, { "instrument": { "symbol": "AAPL240216C00150000", "type": "OPTION" }, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1 } ] }

{ "accountId": "YOUR_ACCOUNT_ID", "accountType": "BROKERAGE", "buyingPower": { "cashOnlyBuyingPower": "4614.70", "buyingPower": "9614.70", "optionsBuyingPower": "9614.70" }, "positions": [ { "instrument": { "symbol": "AAPL240216C00140000", "name": "AAPL Feb 16 '24 $140 Call", "type": "OPTION" }, "quantity": "1.0", "currentValue": "975.00", "percentOfPortfolio": "9.75", "costBasis": { "totalCost": "950.65", "unitCost": "950.65", "gainValue": "24.35", "gainPercentage": "2.56" } }, { "instrument": { "symbol": "AAPL240216C00150000", "name": "AAPL Feb 16 '24 $150 Call", "type": "OPTION" }, "quantity": "-1.0", "currentValue": "-425.00", "percentOfPortfolio": "-4.25", "costBasis": { "totalCost": "-465.00", "unitCost": "-465.00", "gainValue": "-40.00", "gainPercentage": "-8.60" } } ], "equity": [ { "type": "OPTIONS_LONG", "value": "975.00", "percentageOfPortfolio": "9.75" }, { "type": "OPTIONS_SHORT", "value": "-425.00", "percentageOfPortfolio": "-4.25" } ] }

// Bear Put Spread (Buy high strike PUT, sell low strike PUT) { "legs": [ { "instrument": {"symbol": "AAPL240216P00150000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1 }, { "instrument": {"symbol": "AAPL240216P00140000", "type": "OPTION"}, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1 } ] } // Iron Condor (4-leg strategy) { "legs": [ {"instrument": {"symbol": "AAPL240216P00135000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1}, {"instrument": {"symbol": "AAPL240216P00140000", "type": "OPTION"}, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1}, {"instrument": {"symbol": "AAPL240216C00150000", "type": "OPTION"}, "side": "SELL", "openCloseIndicator": "OPEN", "ratioQuantity": 1}, {"instrument": {"symbol": "AAPL240216C00155000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1} ] } // Straddle (Buy CALL and PUT at same strike) { "legs": [ {"instrument": {"symbol": "AAPL240216C00145000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1}, {"instrument": {"symbol": "AAPL240216P00145000", "type": "OPTION"}, "side": "BUY", "openCloseIndicator": "OPEN", "ratioQuantity": 1} ] }