# Trade

Source: https://docs.tradeit.app/models/trade

An order and its fills. [Get trades](/api/get-trades) and the trade operations return trades, and [`TRADE_UPDATED`](/sdk/webhooks#trade-updated) webhook events send one as `data`.

## Fields [#fields]

**`id`** `number | string`

Trade It trade ID. Pass it as `trade_id` to execute or cancel the trade.

**`created_at`** `string`

When the record was created.

**`updated_at`** `string` `optional`

When the record last changed.

**`user_id`** `number | string`

The Trade It user who owns the trade.

**`asset_id`** `number | string`

The traded asset, or the underlying for options.

**`account_id`** `number | string | null`

The account the trade is sent to.

**`parent_id`** `number | string | null`

The trade this take-profit or stop-loss exit belongs to, for certain bracket orders. Null otherwise.

**`source`** `string | null`

Where the trade came from: `ios_app`, `chatgpt`, `mcp`, `api`, or `discord`, or `brokerage:&lt;brokerage id&gt;` for trades synced from brokerage history.

**`image_url`** `string | null`

Screenshot the trade was created from.

**`external_id`** `string`

The brokerage's order ID. Not included in webhook events.

**`external_group_id`** `string | null` `optional`

The brokerage's ID for OCO group the order belongs to. Not included in webhook events.

**`type`** `enum`

`0` for a simple buy/sell, `1` for options/multi-leg.

`0``1`

**`action`** `enum`

Whether the trade buys or sells.

`buy``sell`

**`direction`** `enum | null`

Whether a multi-leg trade pays (`debit`) or receives (`credit`) its net premium. Null for simple trades.

`debit``credit``even`

**`total_units`** `number`

Shares, coins, or futures contracts ordered. A multi-leg trade counts its whole package as `1`.

**`filled_units`** `number`

Units filled so far.

**`canceled_units`** `number`

Units canceled. A canceled order can still be partly filled.

**`notional_amount`** [Balance](#balance) | null

Dollar amount, for orders placed by value instead of units.

**`execution_price`** [Balance](#balance) | null

Average fill price, always positive. For multi-leg trades, the net cash for the whole package. Null until something fills.

**`status`** `enum`

Order status. `complete`, `canceled`, `failed`, and `disconnected` are final.

`draft``pending``placed``partially_filled``complete``canceled``failed``disconnected`

**`order_type`** `enum`

How the order is priced.

`market``limit``stop``stop_limit`

**`limit_price`** [Balance](#balance) | null

Limit price, for limit and stop-limit orders. For multi-leg trades, the net premium per spread unit.

**`stop_price`** [Balance](#balance) | null

Price that triggers a stop or stop-limit order.

**`take_profit`** `object | null` `optional`

Take-profit exit attached to a buy or OCO sell order.

> **`value`** `number`
> 
> 
> Exit trigger level
> 
> 
> **`unit`** `enum`
> 
> 
> Absolute price ($) or percent from entry price (%).
> 
> 
> `$``%`

**`stop_loss`** `object | null` `optional`

Stop-loss exit attached to a buy or OCO sell order.

> **`value`** `number`
> 
> 
> Exit trigger level
> 
> 
> **`unit`** `enum`
> 
> 
> Absolute price ($) or percent from entry price (%).
> 
> 
> `$``%`

**`time_in_force`** `enum | null`

How long the order stays active.

`day``gtc``ioc``fok`

**`placed_at`** `string (format: date-time) | null`

When the order was sent to the brokerage.

**`executed_at`** `string (format: date-time) | null`

When the order finished filling.

**`error_message`** `string | null`

Why the trade failed.

**`fee`** [Balance](#balance) | null

Fees the brokerage charged.

**`legs`** `array of object | null`

Legs of a multi-leg trade. Null for simple trades.

> Each item has:
> 
> 
> **`type`** `enum`
> 
> 
> Whether the leg trades an option or the underlying stock.
> 
> 
> `option``equity`
> 
> 
> **`action`** `enum`
> 
> 
> Whether the leg buys or sells.
> 
> 
> `buy``sell`
> 
> 
> **`position_effect`** `enum | null`
> 
> 
> Whether the leg opens or closes a position.
> 
> 
> `open``close`
> 
> 
> **`occ`** `string | null`
> 
> 
> OCC option contract symbol, e.g. 260717C00435000. Null for stock legs.
> 
> 
> **`quantity`** `number`
> 
> 
> Number of option contracts, or shares for a stock leg.
> 
> 
> **`execution_price`** [Balance](#balance) | null
> 
> 
> The leg's fill price per share. Null when the brokerage only reports a price for the whole package.

**`contract`** `string | null` `optional`

Futures contract month code, e.g. `Z26`. Null for everything but futures.

**`event`** `enum | null`

Set when the trade records an option assignment, exercise, or expiration instead of an order.

`assignment``exercise``expiration`

**`analysis`** `string | null`

Analysis of the screenshot the trade was created from.

**`asset`** `object` `optional`

The traded asset. Expanded in `get_trades` responses and `TRADE_UPDATED` webhooks.

> **`id`** `number | string`
> 
> 
> The database ID. Use for lookups.
> 
> 
> **`created_at`** `string`
> 
> 
> When the record was created.
> 
> 
> **`updated_at`** `string` `optional`
> 
> 
> When the record last changed.
> 
> 
> **`name`** `string | null`
> 
> 
> Company or coin name.
> 
> 
> **`ticker`** `string`
> 
> 
> Ticker symbol.
> 
> 
> **`type`** `enum`
> 
> 
> Asset type: `2` for stocks, `4` for crypto, `8` for indexes, `16` for futures.
> 
> 
> `0``2``4``8``16`
> 
> 
> **`logo_url`** `string | null`
> 
> 
> Logo image URL.
> 
> 
> **`description`** `string | null`
> 
> 
> Short description of the asset.
> 
> 
> **`exchange`** `string`
> 
> 
> Exchange the asset trades on.
> 
> 
> **`mic_code`** `string | null`
> 
> 
> ISO 10383 market identifier code of the exchange.
> 
> 
> **`underlying`** `string | null`
> 
> 
> Underlying ticker, for derivatives.
> 
> 
> **`country`** `string | null`
> 
> 
> Country the asset is listed in.
> 
> 
> **`futures_details`** `object | null`
> 
> 
> Root-level futures specifications. Null for non-futures assets or unknown products. Contract-specific dates, quotes, and account margin are separate.
> 
> 
> > **`multiplier`** `number`
> > 
> > 
> > Futures monetary value of a 1.00 move in the quoted price, per contract, in quote_currency. Quoted price × multiplier × contracts gives notional exposure.
> > 
> > 
> > **`tick_size`** `number`
> > 
> > 
> > Default outright futures price increment, in quoted price units. tick_size × multiplier gives the monetary tick value per contract.
> > 
> > 
> > **`quote_currency`** `string`
> > 
> > 
> > ISO 4217 currency of futures monetary values after applying multiplier, e.g. USD.
> > 
> > 
> > **`contract_months`** `string`
> > 
> > 
> > Listed futures delivery month codes in calendar order, e.g. HMUZ for March, June, September, December.
> 
> 
> **`delisted_at`** `string (format: date-time) | null`
> 
> 
> When the asset was delisted.

## Balance [#balance]

Money fields are Balance objects.

**`amount`** `number`

Amount in `currency`.

**`currency`** `string`

ISO 4217 currency code, such as `USD`.
