Order Templates¶

tda-api strives to be easy to use. This means making it easy to do simple things, while making it possible to do complicated things. Order construction is a major challenge to this mission: both simple and complicated orders use the same format, meaning simple orders require a surprising amount of sophistication to place.

We get around this by providing templates that make it easy to place common orders, while allowing advanced users to modify the orders returned from the templates to create more complex ones. Very advanced users can even create their own orders from scratch. This page describes the simple templates, while the OrderBuilder Reference page documents the order builder in all its complexity.

Using These Templates¶

These templates serve two purposes. First, they are designed to choose defaults so you can immediately place them. These defaults are:

All orders execute during the current normal trading session. If placed outside of trading hours, the execute during the next normal trading session.

Time-in-force is set to DAY.

All other fields (such as requested destination, etc.) are left unset, meaning they receive default treatment from TD Ameritrade. Note this treatment depends on TDA’s implementation, and may change without warning.

Secondly, they serve as starting points for building more complex order types. All templates return a pre-populated OrderBuilder object, meaning complex functionality can be specified by modifying the returned object. For example, here is how you would place an order to buy GOOG for no more than $1250 at any time in the next six months:

from tda.orders.equities import equity_buy_limit
from tda.orders.common import Duration, Session

(equity_buy_limit('GOOG', 1, 1250.0)
 .set_duration(Duration.GOOD_TILL_CANCEL)
 .set_session(Session.SEAMLESS))

You can find a full reference for all supported fields in OrderBuilder Reference.

Equity Templates¶

Buy orders¶

tda.orders.equities.equity_buy_market(symbol, quantity)¶: Returns a pre-filled OrderBuilder for an equity buy market order.

tda.orders.equities.equity_buy_limit(symbol, quantity, price)¶: Returns a pre-filled OrderBuilder for an equity buy limit order.

Sell orders¶

tda.orders.equities.equity_sell_market(symbol, quantity)¶: Returns a pre-filled OrderBuilder for an equity sell market order.

tda.orders.equities.equity_sell_limit(symbol, quantity, price)¶: Returns a pre-filled OrderBuilder for an equity sell limit order.

Sell short orders¶

tda.orders.equities.equity_sell_short_market(symbol, quantity)¶: Returns a pre-filled OrderBuilder for an equity short sell market order.

tda.orders.equities.equity_sell_short_limit(symbol, quantity, price)¶: Returns a pre-filled OrderBuilder for an equity short sell limit order.

Buy to cover orders¶

tda.orders.equities.equity_buy_to_cover_market(symbol, quantity)¶: Returns a pre-filled OrderBuilder for an equity buy-to-cover market order.

tda.orders.equities.equity_buy_to_cover_limit(symbol, quantity, price)¶: Returns a pre-filled OrderBuilder for an equity buy-to-cover limit order.

Options Templates¶

Due to their complexity, options order templates are pending. Templates for options orders will be added in subsequent releases.

In the meantime, you can construct all supported options orders using the OrderBuilder, although you will have to construct them yourself.

Utility Methods¶

These methods return orders that represent complex multi-order strategies, namely “one cancels other” and “first triggers second” strategies. Note they expect all their parameters to be of type OrderBuilder. You can construct these orders using the templates above or by creating them from scratch.

tda.orders.common.one_cancels_other(order1, order2)¶: If one of the orders is executed, immediately cancel the other.

tda.orders.common.first_triggers_second(first_order, second_order)¶: If first_order is executed, immediately place second_order.

What happened to `EquityOrderBuilder`?¶

Long-time users may notice that this documentation no longer mentions the EquityOrderBuilder class. This class used to be used to create equities orders, and offered a subset of the functionality offered by the OrderBuilder. This class has been deprecated in favor of the order builder and the above templates, and will be removed from a future release.

In the meantime, you can continue using this order builder, although you really should migrate to the new one soon. You can find documentation for this class in the older versions of tda-api’s documentation.