Create trade

POST /api/tool/execute

Creates a stock or crypto trade for review. This operation is distinct from create_options_trade and does not accept an options legs array.

OAuth scopes: trade:write, tool:execute

Plan: Trade It Pro

Request body

Field	Type	Required	Description
toolName	"create_trade"	Yes	Selects the equity or crypto draft operation.
params.symbol	string	Yes	Ticker symbol, such as TSLA or BTC.
params.amount	number	Yes	Positive amount interpreted using unit.
params.unit	"dollars" or "shares"	Yes	Whether amount is notional value or units.
params.buy_or_sell	"buy" or "sell"	Yes	Order side.
params.order_type	"market", "limit", "stop", or "stop_limit"	No	Defaults to market.
params.limit_price	number	Conditional	Required for limit and stop_limit.
params.stop_price	number	Conditional	Required for stop and stop_limit.
params.take_profit	object	No	Attached exit as { "value": number, "unit": "$" or "%" }. Buy entries only; support varies by brokerage.
params.stop_loss	object	No	Attached exit as { "value": number, "unit": "$" or "%" }. Buy entries only; support varies by brokerage.
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.
params.metadata.image_url	string	No	Source image URL to associate with the trade.

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_trade",
    "params": {
      "symbol": "TSLA",
      "amount": 1000,
      "unit": "dollars",
      "buy_or_sell": "buy",
      "order_type": "limit",
      "limit_price": 250,
      "time_in_force": "day",
      "account_id": 304
    }
  }'

Example response

200 OK

{
  "id": 842,
  "created_at": "2026-03-17T14:14:31.112Z",
  "updated_at": "2026-03-17T14:14:31.112Z",
  "user_id": 1,
  "asset_id": 88,
  "account_id": 304,
  "source": null,
  "image_url": null,
  "external_id": "draft-842",
  "type": 0,
  "action": "buy",
  "direction": null,
  "total_units": 4,
  "filled_units": 0,
  "canceled_units": 0,
  "notional_amount": { "amount": 1000, "currency": "USD" },
  "execution_price": { "amount": 250, "currency": "USD" },
  "status": "draft",
  "order_type": "limit",
  "limit_price": { "amount": 250, "currency": "USD" },
  "stop_price": null,
  "take_profit": null,
  "stop_loss": null,
  "time_in_force": "day",
  "placed_at": null,
  "executed_at": null,
  "error_message": null,
  "fee": null,
  "legs": null,
  "event": null,
  "analysis": null
}

Show the returned order to the user and obtain explicit approval before passing id to execute_trade. If automatic execution is enabled for the account, the returned status may already be placed instead of draft.