Place complex order / SnapTrade

Place complex order

post

https://api.snaptrade.com/accounts/{accountId}/trading/complex

Places a complex conditional order (OCO, OTO, or OTOCO). Only supported on certain brokerages. Please refer to the brokerage trading support page for details on which brokerages support complex orders and which types they support.

OCO (One Cancels the Other): Two peer orders; when one fills the other is cancelled.
OTO (One Triggers the Other): A trigger order that, when filled, activates a conditional order.
OTOCO (One Triggers a One Cancels the Other): A trigger order that, when filled, activates an OCO pair of two peer orders.

Option OCO peers must trade the same OCC option symbol with the same closing action and positive whole-contract quantity.

On tastytrade, option OCO supports closing an existing long or short option position with one Limit order and one Stop or StopLimit order. Both PEER orders must use SELL_TO_CLOSE or both must use BUY_TO_CLOSE, with Day or GTC time in force. Opening option OCOs are not supported.

On enabled Webull US v3 accounts, option OCO supports closing an existing long option position with one Limit take-profit order and one Stop stop-loss order. Both PEER orders must use SELL_TO_CLOSE, Day, the same OCC option symbol, and the same positive whole-contract quantity. Webull receives these as STOP_PROFIT and STOP_LOSS orders sharing a combo ID, without a MASTER order. Opening option OCOs, BUY_TO_CLOSE, StopLimit, and other option order pairs are not supported on Webull. Equity complex-order behavior is unchanged.

Execute an API Request

Authentication Method

Use commercial authentication when acting on behalf of your application and passing end-user credentials with requests that require them.

Credentials

clientId

consumerKey

userId

userSecret

Path

accountIdstring (format: uuid)required

The ID of the account to execute the trade on.

Request Body

typestringrequired

The complex order type.

OCO: One Cancels the Other — two peer orders.
OTO: One Triggers the Other — a trigger order and a conditional order.
OTOCO: One Triggers a One Cancels the Other — a trigger order and two peer orders.

ordersarray of objectsrequired

The orders that make up the complex order. Required counts and roles per type:

OCO: exactly 2 orders, both PEER
OTO: exactly 2 orders, one TRIGGER and one CONDITIONAL
OTOCO: exactly 3 orders, one TRIGGER and two PEER

client_order_idstring (format: uuid) or null

Optional caller-supplied identifier passed through to the brokerage for idempotent order placement. Must be a canonical 36-character UUID. Idempotency enforcement is brokerage-specific - SnapTrade forwards this value to the broker but does not enforce uniqueness server-side. Refer to per-brokerage documentation for behavior on duplicate submission.

Request

Installation

GitHub npm

npm install snaptrade-typescript-sdk

1
import {
2
  Snaptrade,
3
  SnaptradeAuth,
4
} from "snaptrade-typescript-sdk";
5

6
const snaptrade = new Snaptrade({
7
  auth: SnaptradeAuth.commercialApiKey({
8
    consumerKey: "CONSUMER_KEY",
9
    clientId: "CLIENT_ID",
10
  }),
11
});
12

13
const response =
14
  await snaptrade.trading.placeComplexOrder({
15
    accountId:
16
      "917c8734-8470-4a3e-a18f-57c3f2ee6631",
17
    userId: "USER_ID",
18
    userSecret: "USER_SECRET",
19
    type: "OTO",
20
    orders: [
21
      {
22
        order_role: "TRIGGER",
23
        action: "ACTION",
24
        instrument: {
25
          symbol: "AAPL",
26
          type: "TYPE",
27
        },
28
        order_type: "Market",
29
        units: 1,
30
        time_in_force: "Day",
31
        price: 31.33,
32
        stop: 29.5,
33
      },
34
    ],
35
  });
36
console.log(response.data);

Response fields

object

Response returned after successfully placing a complex order. AccountOrderRecord rows for the legs are not created synchronously — they're hydrated by the next brokerage sync, and can be queried later using the returned brokerage_group_order_id.

typestring

The complex order type that was placed.

brokerage_group_order_idstring or null

The brokerage-assigned identifier that links all legs of this complex order together. Each leg will eventually appear as a separate AccountOrderRecord sharing this value. May be null if the brokerage does not return a group identifier.

1
{
2
  "type": "OTO",
3
  "brokerage_group_order_id": "1234567890"
4
}