# Place Trades

Source: https://docs.tradeit.app/sdk/trades

Once a user has [signed in](/sdk/authentication) and [connected a brokerage](/sdk/connect), choose how to present and submit orders:

- **Client side (embedded modal):** use the React trade modal for order entry, review, and user approval. Your server supplies its authenticated session URL.
- **Server side (your own UI):** use the REST API to prepare an order, and submit it with the user's consent. See [Trade through your server](#trade-through-your-server).

The embedded modal requires `asset:read brokerage:read trade:write`. Direct API trading requires `trade:write tool:execute`; add `trade:read` to read order status.

The modal and API support stocks, crypto, options, and outright futures, depending on the connected brokerage and account permissions. Futures use whole contracts and require a futures-enabled account; see [brokerage coverage](/brokerages).

## How It Works [#how-it-works]

1. Your server requests an authenticated trade session URL.
2. Your client-side app opens the trade modal via the SDK.
3. You pass a trade configuration (simple or options/multi-leg).
4. The user confirms, sending the order to their brokerage.

## Server side: Request a Trade Session URL [#server-side-request-a-trade-session-url]

Call Trade It's API server-side to get a url to the trade portal. The URL is pre-authenticated so the user does not need to log in.

### Request [#request]

```http
POST https://api.tradeit.app/api/session/url
Content-Type: application/json
Authorization: Bearer <user's trade it access token>

{
  "target": "trade"
}
```

### Response [#response]

```json
{
  "url": "https://tradeit.app/t/[ticker]?ti_token=ti:...&embedded=1",
  "expiresAt": "2026-02-27T19:35:12.000Z",
  "feature": "trade",
  "placeholder": "[ticker]"
}
```

Trade It returns an authenticated trade URL template.

> **Note**
>
> Request a fresh template immediately before opening the modal. It expires after 30 minutes and should not be cached for reuse.

Implement `POST /api/tradeit/trade` on your server using this request. Require your platform session and CSRF protection, load and refresh the current user's Trade It token, and return the session URL response. Keep OAuth tokens on the server and exclude session URLs from logs and analytics.

## Client side: Open the Trade Modal (Simple Trade) [#client-side-open-the-trade-modal-simple-trade]

```tsx
import { useState } from 'react';
import {
  LegType,
  OrderDirection,
  OrderType,
  PositionEffect,
  TimeInForce,
  TriggerUnit,
  TradeAction,
  TradeItModal,
  TradeType,
  TradeUnit,
} from '@trade-it/react';

function BuyButton() {
  const [open, setOpen] = useState(false);
  const [tradeUrl, setTradeUrl] = useState<string | null>(null);

  async function openTrade() {
    const res = await fetch('/api/tradeit/trade', { method: 'POST' });
    if (!res.ok) throw new Error('Unable to open the trade modal');
    const data = await res.json();
    setTradeUrl(data.url);
    setOpen(true);
  }

  return (
    <>
      <button onClick={openTrade}>Buy/Sell</button>
      {tradeUrl && (
        <TradeItModal
          open={open}
          onOpenChange={setOpen}
          launch={{
            mode: 'trade',
            url: tradeUrl,
            config: {
              tradeType: TradeType.Simple,
              ticker: 'AAPL',
              action: TradeAction.Buy,
              amount: 100,
              unit: TradeUnit.Dollars,
              orderType: OrderType.Market,
              takeProfit: { value: 10, unit: TriggerUnit.Percent },
              stopLoss: { value: 5, unit: TriggerUnit.Percent },
            },
          }}
        />
      )}
    </>
  );
}
```

> **Note**
>
> The same modal supports options orders too. Pass a multi-leg config and Trade It opens directly into the options workflow with details prefilled.

## Examples [#examples]

Use these examples of common scenarios as jumping off point.

### Example 1: Buy in Dollars [#example-1-buy-in-dollars]

*Buy shares of an asset.*

```tsx
tradeIt.openTrade({
  launch: {
    mode: 'trade',
    url: tradeUrl,
    config: {
      tradeType: TradeType.Simple,
      ticker: 'AAPL',
      action: TradeAction.Buy,
      amount: 100,
      unit: TradeUnit.Dollars,
      orderType: OrderType.Market,
    },
  },
});
```

![Buy order screen inside the Trade It trade modal](https://images.tradeit.app/docs/trade_buy.png?v=2)

Buy $100 of Apple stock.

### Example 2: Sell in Shares with Stop-Limit [#example-2-sell-in-shares-with-stop-limit]

*Sell shares while setting both stop and limit prices.*

```tsx
tradeIt.openTrade({
  launch: {
    mode: 'trade',
    url: tradeUrl,
    config: {
      tradeType: TradeType.Simple,
      ticker: 'AAPL',
      action: TradeAction.Sell,
      amount: 10,
      unit: TradeUnit.Shares,
      orderType: OrderType.StopLimit,
      stopPrice: 340,
      limitPrice: 330,
      timeInForce: TimeInForce.GoodTillCanceled,
    },
  },
});
```

![Sell order screen inside the Trade It trade modal](https://images.tradeit.app/docs/trade_sell.png?v=2)

Sell 10 shares of Apple with a stop-limit order.

### Example 3: Multi-Leg Options [#example-3-multi-leg-options]

*Open a credit spread with prefilled legs and pricing.*

```tsx
tradeIt.openTrade({
  launch: {
    mode: 'trade',
    url: tradeUrl,
    config: {
      tradeType: TradeType.MultiLeg,
      ticker: 'AAPL',
      direction: OrderDirection.Credit,
      orderType: OrderType.Limit,
      limitPrice: 15.48,
      timeInForce: TimeInForce.Day,
      legs: [
        {
          type: LegType.Option,
          action: TradeAction.Sell,
          positionEffect: PositionEffect.Open,
          occ: '280121C00340000',
          quantity: 1,
        },
        {
          type: LegType.Option,
          action: TradeAction.Buy,
          positionEffect: PositionEffect.Open,
          occ: '280121C00370000',
          quantity: 1,
        },
      ],
    },
  },
});
```

![Multi-leg options order screen inside the Trade It trade modal](https://images.tradeit.app/docs/trade_options.png?v=2)

Open an Apple call credit spread with prefilled legs.

### Example 4: Futures [#example-4-futures]

Use the slash-prefixed product root with `TradeUnit.Contracts`. Omit `contract` to select the active month, or supply a delivery code such as `Z26` for December 2026.

```tsx
tradeIt.openTrade({
  launch: {
    mode: 'trade',
    url: tradeUrl,
    config: {
      tradeType: TradeType.Simple,
      ticker: '/MES',
      action: TradeAction.Buy,
      amount: 1,
      unit: TradeUnit.Contracts,
      orderType: OrderType.Market,
    },
  },
});
```

The user selects an eligible futures account and reviews the contract month and quantity before placing the order. Quotes come from that brokerage; futures exposure and account margin differ from the quoted price.

## Config Parameters (`launch.config`) [#config-parameters-launch-config]

Configure a particular trade using the parameters below:

> **TIP**
>
> See all enum values on [SDK Enums Reference](/sdk/enums).

**Stock, crypto, or futures**

- **`ticker`** · `string` · required

Ticker symbol of the asset, or the underlying for options, e.g. TSLA. Futures use the product root with its slash, e.g. /ES.

- **`orderType`** · `string`

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

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

- **`limitPrice`** · `number`

Limit price in the asset currency for limit and stop_limit orders; per spread unit for multi-leg trades, where 0 with direction even means zero-net.

- **`stopPrice`** · `number`

Price in the asset currency that triggers stop and stop_limit orders.

- **`timeInForce`** · `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`.

- **`referral`** · `string`

Referral source label stored with the link for tracking, e.g. a newsletter name.

- **`tradeType`** · `number`

Allowed values: `0`.

- **`action`** · `string`

Whether a simple trade buys or sells. Set when trade_type is 0.

Allowed values: `buy`, `sell`.

- **`amount`** · `number`

How much a simple trade buys or sells,, as dollars or shares per unit.

- **`unit`** · `string`

Whether amount is a dollar value, a share count, or (futures only) a contract count.

Allowed values: `dollars`, `shares`, `contracts`.

- **`contract`** · `string`

Futures contract month code, e.g. Z26 for December 2026. Omit to trade the active month when the link is opened.

- **`takeProfit`** · `object`

Take-profit exit for bracket Buy entries or OCO Sell orders. Not supported by all brokerages.

- **`takeProfit.value`** · `number` · required

Exit trigger level

- **`takeProfit.unit`** · `string`

Absolute price ($) or percent from entry price (%).

Allowed values: `$`, `%`.

- **`stopLoss`** · `object`

Stop-loss exit for  bracket Buy entries or OCO Sell orders. Not supported by all brokerages.

- **`stopLoss.value`** · `number` · required

Exit trigger level

- **`stopLoss.unit`** · `string`

Absolute price ($) or percent from entry price (%).

Allowed values: `$`, `%`.

**Options or multi-leg**

- **`ticker`** · `string` · required

Ticker symbol of the asset, or the underlying for options, e.g. TSLA. Futures use the product root with its slash, e.g. /ES.

- **`orderType`** · `string`

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

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

- **`limitPrice`** · `number`

Limit price in the asset currency for limit and stop_limit orders; per spread unit for multi-leg trades, where 0 with direction even means zero-net.

- **`stopPrice`** · `number`

Price in the asset currency that triggers stop and stop_limit orders.

- **`timeInForce`** · `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`.

- **`referral`** · `string`

Referral source label stored with the link for tracking, e.g. a newsletter name.

- **`tradeType`** · `number` · required

Allowed values: `1`.

- **`direction`** · `string`

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

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

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

Option or equity legs. Supply an OCC identifier and positionEffect for option legs.

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

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

Whether the leg trades an option or the underlying stock.

Allowed values: `option`, `equity`.

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

Whether the leg buys or sells.

Allowed values: `buy`, `sell`.

- **`legs[].positionEffect`** · `string | null`

Whether the leg opens or closes a position.

Allowed values: `open`, `close`.

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

OCC option contract symbol, e.g. 260717C00435000. Null for stock legs.

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

Number of option contracts, or shares for a stock leg.

## Trade through your server [#trade-through-your-server]

Use this path if your platform owns the order form and review screen. All API calls use the current user's OAuth token on your server. We recommend user review and approval before execution. Platforms control their consent flow, including whether to rely on prior or blanket consent.

1. [Read accounts](/sdk/accounts) and have the user select the account.
2. Prepare an order with [Create trade](/api/create-trade) or [Create options trade](/api/create-options-trade).
3. Display the returned order's account, symbol, side, quantity, prices, order type, and any option legs. Ask for approval of that order in the recommended flow.
4. In an authenticated, CSRF-protected handler, submit the draft using [Execute trade](/api/execute-trade).
5. Read [Get trades](/api/get-trades) for order status; an accepted order may not have filled. Offer [Cancel trade](/api/cancel-trade) where eligible.

> **Check automatic execution before creating an order**
>
> Accounts configured for automatic execution may submit an order during `create_trade` or `create_options_trade`. Use accounts with automatic execution disabled for a draft-first flow. Always inspect the returned status; do not execute an already submitted order.

For example, prepare a limit order from your server with the user's selected `account_id`:

```json
{
  "tool_name": "create_trade",
  "params": {
    "symbol": "AAPL",
    "account_id": 304,
    "buy_or_sell": "buy",
    "amount": 1,
    "unit": "shares",
    "order_type": "limit",
    "limit_price": 150,
    "time_in_force": "day"
  }
}
```

Send this JSON to `POST https://api.tradeit.app/api/tool/execute` with `Authorization: Bearer <user_access_token>`. Replace `304` with the selected Trade It account ID and the sample order fields with the user's intended order.

After review and approval, the confirmation handler sends a **separate** request to the same endpoint:

```json
{
  "tool_name": "execute_trade",
  "params": { "trade_id": 842 }
}
```

Replace `842` with the returned draft's `id`. Bind the saved draft and approval to the current platform user; re-review if any order details change. Prevent duplicate confirmation requests and check order status before retrying a submission after a network timeout.
