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

Request body

Field	Type	Required	Description
toolName	"create_options_trade"	Yes	Selects the options draft operation.
params.symbol	string	Yes	Underlying ticker symbol, such as SPY.
params.legs	array	Yes	One or more option or equity legs.
params.direction	"debit", "credit", or "even"	Conditional	Net direction for a multi-leg spread.
params.order_type	"market", "limit", "stop", or "stop_limit"	No	Defaults to market.
params.limit_price	number	Conditional	Required for limit and stop_limit. May be 0 with direction even.
params.stop_price	number	Conditional	Required for stop and stop_limit.
params.time_in_force	"day", "gtc", "ioc", or "fok"	No	How long the order remains active. Brokerage support varies.
params.account_id	integer or string	No	Account from get_accounts. Uses the user's compatible default account when omitted.

Leg fields

Field	Type	Required	Description
type	"option" or "equity"	Yes	Instrument represented by the leg.
action	"buy" or "sell"	Yes	Leg side.
position_effect	"open", "close", or null	Conditional	Required for option legs; use null for equity legs.
occ	string or null	Yes	OCC contract identifier for an option leg; null for an equity leg.
quantity	number	Yes	Positive number of contracts or shares.

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 '{
    "toolName": "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.