tastytradeDeveloper Docs
Legacy ↗

Orders & Order Types

An order in the tastytrade API is a JSON document with two parts: order attributes that apply to the trade as a whole, and a legs array where each leg names a single instrument, a side, and a quantity. All JSON keys are dasherized (for example order-type, price-effect, time-in-force, instrument-type), and prices/values are sent as strings or decimals.

Orders are submitted to POST /accounts/{account_number}/orders. Because orders move real money, always dry-run first against POST /accounts/{account_number}/orders/dry-run (the same JSON body), inspect the returned buying-power-effect/fee-calculation and any warnings, then submit. There is no idempotency-key header and the API does not deduplicate retried submissions, so set your own unique external-identifier on each order (it is echoed back on the order response); if a submission's outcome is uncertain (timeout or 5xx), check GET /accounts/{account_number}/orders (or /orders/live) for that identifier before resubmitting. See Idempotency & retries and the full schema at /reference/orders.

Order attributes

AttributeRequiredMeaning
order-typeYesThe kind of order (see below)
time-in-forceYesHow long the order lives if unfilled
priceYes for Limit / Stop LimitThe limit price
price-effectWith priceDebit (you pay) or Credit (you receive)
stop-triggerYes for Stop / Stop LimitThe trigger price
gtc-dateYes for GTDExpiry date (yyyy-mm-dd)
value / value-effectYes for Notional MarketDollar amount to buy/sell
legsYesArray of leg objects
sourceNoFree-form origin tag

price-effect must agree with the leg action: buying is a Debit, selling is a Credit. Buying for a credit (or selling for a debit) is rejected.

Legs

Each leg names one instrument. All orders need at least one leg. Equity, future, and cryptocurrency orders are limited to 1 leg; equity-option and future-option orders allow up to 4 legs. Two legs may not share the same symbol.

Leg attributeRequiredMeaning
actionYesBuy to Open, Sell to Open, Buy to Close, Sell to Close (or Buy/Sell for single-leg outright futures)
instrument-typeYesEquity, Equity Option, Future, Future Option, or Cryptocurrency
quantityYes (omit for Notional Market)Whole number, or decimal for crypto
symbolYesThe instrument symbol

The action and instrument-type values above are the commonly used ones — the full enums (which also include Allocate, Equity Offering, Fixed Income Security, and Liquidity Pool) are in /reference/orders.

Symbols follow tastytrade symbology: plain tickers for equities (AAPL), OCC-style strings for equity options (AAPL 230818C00197500), leading-slash futures (/CLZ2), future options, and crypto pairs (BTC/USD). Look symbols up via the instruments endpoints — see /reference.

Order types

TypeRule
LimitMust include price and price-effect
MarketNo price/price-effect; single leg; time-in-force not GTC
StopMarket order with a stop-trigger; becomes a market order when the quote hits the trigger
Stop LimitLimit order (price + price-effect) plus a stop-trigger

A Notional Market type also exists for buying a dollar value of crypto or eligible equities (omit quantity). These are the commonly used order types — the full order-type enum (which also includes Marketable Limit and Liquidity Allocation) is in /reference/orders.

{
  "time-in-force": "Day",
  "order-type": "Limit",
  "price": "1.09",
  "price-effect": "Debit",
  "legs": [
    { "instrument-type": "Equity Option", "symbol": "AAPL  230818C00197500", "quantity": 1, "action": "Buy to Open" },
    { "instrument-type": "Equity Option", "symbol": "AAPL  230818C00200000", "quantity": 1, "action": "Sell to Open" }
  ]
}

Time-in-force

TIFMeaning
DayWorks until filled or the market closes
GTCGood 'til canceled — works until filled or canceled
GTDGood 'til date — also requires gtc-date (yyyy-mm-dd)

Some venues also support immediate-or-cancel and extended-hours behaviors; refer to /reference/orders for the values your instrument accepts.

Complex orders

Complex (bracket) orders are submitted to POST /accounts/{account_number}/complex-orders and have a type plus an orders array (and, for triggered types, a trigger-order; PAIRS adds ratio-price fields — see below). Supported types are OTOCO, OCO, OTO, and PAIRS. BLAST is deprecated and is not supported in any environment.

  • OTO — the trigger-order goes live immediately; when it fills, its orders (up to 3) are routed. They do not cancel one another.
  • OCO — no trigger-order; the orders go live immediately, and when one fills the other is canceled.
  • OTOCO — a trigger-order plus an OCO pair that sit in Contingent status until the trigger fills, then route as an OCO.
  • PAIRS — orders worked together as a pairs strategy, triggered by a ratio price: set ratio-price-comparator (gte or lte) and ratio-price-threshold (a decimal serialized as a JSON string, e.g. "150.25"); optionally set ratio-price-is-threshold-based-on-notional to compare on notional value instead of price. A working PAIRS order's threshold and comparator can later be edited via PATCH /accounts/{account_number}/complex-orders/{id} (only PAIRS orders can be edited there).
{
  "type": "OTOCO",
  "trigger-order": {
    "order-type": "Limit", "price": 157.97, "price-effect": "Debit", "time-in-force": "Day",
    "legs": [{ "instrument-type": "Equity", "symbol": "AAPL", "action": "Buy to Open", "quantity": 100 }]
  },
  "orders": [
    { "order-type": "Limit", "price": 198.68, "price-effect": "Credit", "time-in-force": "GTC",
      "legs": [{ "symbol": "AAPL", "instrument-type": "Equity", "action": "Sell to Close", "quantity": 100 }] },
    { "order-type": "Stop", "time-in-force": "GTC", "stop-trigger": 143.06,
      "legs": [{ "symbol": "AAPL", "instrument-type": "Equity", "action": "Sell to Close", "quantity": 100 }] }
  ]
}

The response returns a complex-order.id (used to fetch or cancel the whole bracket) plus individual ids for the trigger and nested orders. Cancel a complex order through its own endpoint using the complex-order id, not a nested order id.

Related