Build with the AI Skill
Trade ItTrade ItDocs
Trades

Create options trade

POST /api/tool/execute

Creates a single-leg or multi-leg options order for review. This is a separate operation from create_trade.

OAuth scopes: trade:write, tool:execute

Plan: Trade It Pro

Returns: Trade

Request body

tool_name*string

Selects this API operation.

create_options_trade

Parameters for this operation.

symbol*string

Ticker symbol of the underlying asset, e.g. SPX or TSLA

Array of trade legs. At least one leg is required.

type*string

Whether the leg trades an option contract or shares of the underlying.

optionequity
action*string

Whether the leg buys or sells.

buysell
position_effectstring | null

Whether an option leg opens a new position or closes an existing one. Use null for equity legs.

openclose
occ*string | null

Option contract in OCC format without the root symbol: YYMMDD, C or P, then the strike x1000 zero-padded to 8 digits, e.g. "240119C00195000" for the Jan 19, 2024 $195 call. Use null for equity legs.

quantity*number

Number of contracts for options or shares for equity

directionstring

Net cash flow of a multi-leg spread: debit when paying, credit when receiving, even for zero-net. Set for multi-leg spreads only.

debitcrediteven
limit_pricenumber

Net price per spread unit for limit and stop_limit orders, in the asset currency. Use 0 with direction even for a zero-net spread.

order_typestring

How the order is priced. Omit for a market order.

marketlimitstopstop_limit
stop_pricenumber

Price per share, in the asset currency, that triggers the order. Set for stop and stop_limit orders.

time_in_forcestring

How long the order stays open: day expires at market close, gtc stays open until canceled. Omit to use the brokerage default.

daygtciocfok
account_idnumber | string

ID of the brokerage account to trade in, from get_accounts. Omit to use the user's default account.

Leg fields

Expand params → legs in the request schema to inspect each leg’s fields, types, and allowed values.

OCC symbols

OCC identifiers use YYMMDD[C|P]STRIKE, with the strike multiplied by 1,000 and zero-padded to eight digits. For example, 260620P00580000 is a $580 put expiring June 20, 2026.

Example request

curl https://api.tradeit.app/api/tool/execute \
  --request POST \
  --header "Authorization: Bearer $TRADE_IT_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "tool_name": "create_options_trade",
    "params": {
      "symbol": "SPY",
      "legs": [
        {
          "type": "option",
          "action": "buy",
          "position_effect": "open",
          "occ": "260620P00580000",
          "quantity": 1
        },
        {
          "type": "option",
          "action": "sell",
          "position_effect": "open",
          "occ": "260620P00570000",
          "quantity": 1
        }
      ],
      "direction": "debit",
      "order_type": "limit",
      "limit_price": 2.35,
      "time_in_force": "day",
      "account_id": 304
    }
  }'

Example response

200 OK

{
  "id": 843,
  "created_at": "2026-03-17T14:19:07.444Z",
  "updated_at": "2026-03-17T14:19:07.444Z",
  "user_id": 1,
  "asset_id": 23,
  "account_id": 304,
  "source": null,
  "image_url": null,
  "external_id": "draft-843",
  "type": 1,
  "action": "buy",
  "direction": "debit",
  "total_units": 1,
  "filled_units": 0,
  "canceled_units": 0,
  "notional_amount": null,
  "execution_price": null,
  "status": "draft",
  "order_type": "limit",
  "limit_price": { "amount": 2.35, "currency": "USD" },
  "stop_price": null,
  "time_in_force": "day",
  "placed_at": null,
  "executed_at": null,
  "error_message": null,
  "fee": null,
  "legs": [
    {
      "occ": "260620P00580000",
      "type": "option",
      "action": "buy",
      "quantity": 1,
      "execution_price": null,
      "position_effect": "open"
    },
    {
      "occ": "260620P00570000",
      "type": "option",
      "action": "sell",
      "quantity": 1,
      "execution_price": null,
      "position_effect": "open"
    }
  ],
  "event": null,
  "analysis": null
}

Show every returned leg and the net direction and price to the user before calling execute_trade.

Reading prices on a multi-leg trade

Note

Every price on a trade is unsigned, including execution_price. A credit spread and a debit spread of the same size store the same number. direction tells them apart, and total_cost is the signed figure to display.

FieldUnitNotes
legs[].execution_pricePer shareMultiply by 100 for the per-contract cost.
legs[].quantityContractsThe absolute count on that leg.
limit_pricePer contract/spread unitA 1.00 limit on a spread is a $100 package.
execution_priceNet cash for the whole packageUnsigned.
total_units1A multi-leg order counts as a single package.
filled_unitsFraction of the packageSame as total_units when fully filled.
directiondebit, credit, evenWhich way the cash moved.

Create Trade

Previous Page

Execute Trade

Next Page

On this page

Request bodyExample requestExample responseReading prices on a multi-leg trade