Build with the AI Skill
Trade ItTrade ItDocs
Actions

Place Trades

Once a user has signed in and connected a brokerage, 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, show it to the user, and submit it after explicit approval. See 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.

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

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

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

{
  "target": "trade"
}

Response

{
  "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)

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

Use these examples of common scenarios as jumping off point.

Example 1: Buy in Dollars

Buy shares of an asset.

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
Buy $100 of Apple stock.

Example 2: Sell in Shares with Stop-Limit

Sell shares while setting both stop and limit prices.

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
Sell 10 shares of Apple with a stop-limit order.

Example 3: Multi-Leg Options

Open a credit spread with prefilled legs and pricing.

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
Open an Apple call credit spread with prefilled legs.

Config Parameters (launch.config)

Configure a particular trade using the parameters below:

TIP

See all enum values on SDK Enums Reference.

ticker*string

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

orderTypestring

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

marketlimitstopstop_limit
limitPricenumber

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.

stopPricenumber

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

timeInForcestring

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

daygtciocfok
referralstring

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

tradeTypenumber
0
actionstring

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

buysell
amountnumber

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

unitstring

Whether amount is a dollar value or a share count.

dollarsshares

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

value*number

Exit trigger level

unitstring

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

$%

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

value*number

Exit trigger level

unitstring

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

$%
ticker*string

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

orderTypestring

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

marketlimitstopstop_limit
limitPricenumber

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.

stopPricenumber

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

timeInForcestring

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

daygtciocfok
referralstring

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

tradeType*number
1
directionstring

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

debitcrediteven

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

typestring

Whether the leg trades an option or the underlying stock.

optionequity
actionstring

Whether the leg buys or sells.

buysell
positionEffectstring | null

Whether the leg opens or closes a position.

openclose
occstring | null

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

quantitynumber

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

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.

  1. Read accounts and have the user select the account.
  2. Prepare an order with Create trade or Create options trade.
  3. Display the returned order's account, symbol, side, quantity, prices, order type, and any option legs. Require explicit approval for that specific order.
  4. In a separate authenticated, CSRF-protected confirmation handler, submit the approved draft using Execute trade.
  5. Read Get trades for order status; an accepted order may not have filled. Offer 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. If automatic execution is enabled, obtain explicit approval of the exact order before the create call. 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:

{
  "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:

{
  "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.

On this page