# Create options trade

Source: https://docs.tradeit.app/api/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](/models/trade)

## Request body [#request-body]

- **`tool_name`** · `string` · required

Selects this API operation.

Allowed values: `create_options_trade`.

- **`params`** · `object` · required

Parameters for this operation.

- **`params.symbol`** · `string` · required

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

- **`params.legs`** · `object[]` · required

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

- **`params.legs[]`** · `object`

- **`params.legs[].type`** · `string` · required

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

Allowed values: `option`, `equity`.

- **`params.legs[].action`** · `string` · required

Whether the leg buys or sells.

Allowed values: `buy`, `sell`.

- **`params.legs[].position_effect`** · `string | null`

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

Allowed values: `open`, `close`.

- **`params.legs[].occ`** · `string | null` · required

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.

- **`params.legs[].quantity`** · `number` · required

Number of contracts for options or shares for equity

- **`params.direction`** · `string`

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

Allowed values: `debit`, `credit`, `even`.

- **`params.limit_price`** · `number`

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.

- **`params.order_type`** · `string`

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

Allowed values: `market`, `limit`, `stop`, `stop_limit`.

- **`params.stop_price`** · `number`

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

- **`params.time_in_force`** · `string`

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

Allowed values: `day`, `gtc`, `ioc`, `fok`.

- **`params.account_id`** · `number | string`

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

### Leg fields [#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 [#example-request]

```bash
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 [#example-response]

### `200 OK` [#_200-ok]

```json
{
  "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 [#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.

| Field | Unit | Notes |
| --- | --- | --- |
| `legs[].execution_price` | Per share | Multiply by 100 for the per-contract cost. |
| `legs[].quantity` | Contracts | The absolute count on that leg. |
| `limit_price` | Per contract/spread unit | A `1.00` limit on a spread is a $100 package. |
| `execution_price` | Net cash for the whole package | Unsigned. |
| `total_units` | 1 | A multi-leg order counts as a single package. |
| `filled_units` | Fraction of the package | Same as total_units when fully filled. |
| `direction` | `debit`, `credit`, `even` | Which way the cash moved. |