Using Alpaca Trade API, a user can monitor, place and cancel their orders with Alpaca. Each order has a unique identifier provided by the client. This client-side unique order ID will be automatically generated by the system if not provided by the client, and will be returned as part of the order object along with the rest of the fields described below. Once an order is placed, it can be queried using the client-side order ID or system-assigned unique ID to check the status. Updates on open orders at Alpaca will also be sent over the streaming interface, which is the recommended method of maintaining order state.

Buying Power

In order to accept your orders that would open new positions or add to existing ones, your account must have sufficient buying power. Alpaca applies a “buying” power check to both buy long and sell short positions.

The calculated value of an opening sell short order is MAX(order’s limit price, 3% above the current ask price) multiplied by the order’s quantity. In the case of market short orders, the value is simply 3% above the current ask price * order quantity.

The order’s calculated value is then checked against your available buying power to determine if it can be accepted. Please note that your available buying power is reduced by your existing open buy long and sell short orders, whereas your sell long and buy to cover orders do not replenish your available buying power until they have executed.

For example, if your buying power is $10,000 and you submit a limit buy order with an order value of $3,000, your order will be accepted and your remaining available buying power will be $7,000. Even if this order is unfilled, as long as it is open and has not been cancelled, it will count against your available buying power. If you then submitted another order with an order value of $8,000, it would be rejected.

Initial buying power checks on orders:

When the core session is open: Far side of the NBBO (using Bid & Ask Price)

If the order is entered while the extended hours session is open: Midpoint of the inside market

If the order is entered when the core session and extended hours session are closed (pre-market hours): the latest trade from market cache

Equities Trading

The following section deals with equity trading

Orders Submitted Outside of Eligible Trading Hours

Orders not eligible for extended hours submitted after 4:00pm ET will be queued up for release the next trading day.

Orders eligible for extended hours submitted outside of 4:00am - 8:00pm ET are handled as described in the section below. Fractional shares and orders with notional sizes are not available during extended hours trading.

Extended Hours Trading

Using API v2, you can submit and fill orders during pre-market and after-hours. Extended hours trading has specific risks due to the less liquidity. Please read through Alpaca’s Extended Hours Trading Risk Disclosure for more details.

Currently, we support full extended hours:

• Pre-market: 4:00am - 9:30am ET, Monday to Friday
• After-hours: 4:00pm - 8:00pm ET, Monday to Friday

Submitting an Extended Hours Eligible Order

To indicate an order is eligible for extended hours trading, you need to supply a boolean parameter named extended_hours to your order request. By setting this parameter to true, the order is will be eligible to execute in the pre-market or after-hours.

Only limit day orders will be accepted as extended hours eligible. All other order types and TIFs will be rejected with an error. You must adhere to these settings in order to participate in extended hours:

1. The order type must be set to limit (with a limit price). Any other type of orders will be rejected with an error.
2. Time-in-force must be set to be day. Any other time_in_force will be rejected with an error.

For Fractional Orders, starting on October 27, 2021, customers will not be able to send the following sequence of orders outside of market hours for the same security. This is so customers will not have a net short position. Examples of the order sequences that will be rejected are shown below.

For more information - please see our Blog Post on this topic.

If this is done you will see the following error message: "unable to open new notional orders while having open closing position orders".

All symbols supported during regular market hours are also supported during extended hours. Short selling is also treated the same.

IPO Symbols

Alpaca supports trading symbols which have recently begun trading publicly on major exchanges such as the NYSE and NASDAQ. This process is known as a company going public, or an IPO.

As a registered broker/dealer, Alpaca must follow FINRA regulations regarding order types for IPO symbols:

• Alpaca is only able to accept limit orders prior to the security’s first trade on the exchange
• Once an IPO begins trading on an exchange, market orders are accepted

To assist our customers, Alpaca will expose an attribute called ipo on the Assets model. The ipo attribute will flag to customers that this particular symbol has an IPO coming up, or is just about to begin trading on an exchange, and therefore a limit order must be used.

Order Types

When you submit an order, you can choose one of supported order types. Currently, Alpaca supports four different types of orders.

Market Order

A market order is a request to buy or sell a security at the currently available market price. It provides the most likely method of filling an order. Market orders fill nearly instantaneously.

As a trade-off, your fill price may slip depending on the available liquidity at each price level as well as any price moves that may occur while your order is being routed to its execution venue. There is also the risk with market orders that they may get filled at unexpected prices due to short-term price spikes.

Limit Order

A limit order is an order to buy or sell at a specified price or better. A buy limit order (a limit order to buy) is executed at the specified limit price or lower (i.e., better). Conversely, a sell limit order (a limit order to sell) is executed at the specified limit price or higher (better). Unlike a market order, you have to specify the limit price parameter when submitting your order.

While a limit order can prevent slippage, it may not be filled for a quite a bit of time, if at all. For a buy limit order, if the market price is within your specified limit price, you can expect the order to be filled. If the market price is equivalent to your limit price, your order may or may not be filled; if the order cannot immediately execute against resting liquidity, then it is deemed non-marketable and will only be filled once a marketable order interacts with it. You could miss a trading opportunity if price moves away from the limit price before your order can be filled.

Sub-penny increments for limit orders

The minimum price variance exists for limit orders. Orders received in excess of the minimum price variance will be rejected.

• Limit price >=$1.00: Max Decimals= 2
• Limit price <$1.00: Max Decimals = 4

{
  "code": 42210000,
  "message": "invalid limit_price 290.123. sub-penny increment does not fulfill minimum pricing criteria"
}

Stop Orders

A stop (market) order is an order to buy or sell a security when its price moves past a particular point, ensuring a higher probability of achieving a predetermined entry or exit price. Once the order is elected, the stop order becomes a market order. Alpaca converts buy stop orders into stop limit orders with a limit price that is 4% higher than a stop price < $50 (or 2.5% higher than a stop price >= $50). Sell stop orders are not converted into stop limit orders.

A stop order does not guarantee the order will be filled at a certain price after it is converted to a market order.

In order to submit a stop order, you will need to specify the stop price parameter in the API.

Sub-penny increments for stop orders

The minimum price variance exists for stop orders. Orders received in excess of the minimum price variance will be rejected.

• Stop price >=$1.00: Max Decimals= 2
• Stop price <$1.00: Max Decimals = 4

{
  "code": 42210000,
  "message": "invalid stop_price 290.123. sub-penny increment does not fulfill minimum pricing criteria"
}

Stop Limit Order

A stop-limit order is a conditional trade over a set time frame that combines the features of a stop order with those of a limit order and is used to mitigate risk. The stop-limit order will be executed at a specified limit price, or better, after a given stop price has been reached. Once the stop price is reached, the stop-limit order becomes a limit order to buy or sell at the limit price or better. In the case of a gap down in the market that causes the election of your order, but not the execution, you order will remain active as a limit order until it is executable or cancelled.

In order to submit a stop limit order, you will need to specify both the limit and stop price parameters in the API.

Opening and Closing Auction Orders

Market on open and limit on open orders are only eligible to execute in the opening auction. Market on close and limit on close orders are only eligible to execute in the closing auction. Please see the Time in Force section for more details.

Bracket Orders

A bracket order is a chain of three orders that can be used to manage your position entry and exit. It is a common use case of an OTOCO (One Triggers OCO {One Cancels Other}) order.

The first order is used to enter a new long or short position, and once it is completely filled, two conditional exit orders are activated. One of the two closing orders is called a take-profit order, which is a limit order, and the other is called a stop-loss order, which is either a stop or stop-limit order. Importantly, only one of the two exit orders can be executed. Once one of the exit orders is filled, the other is canceled. Please note, however, that in extremely volatile and fast market conditions, both orders may fill before the cancellation occurs.

Without a bracket order, you would not be able to submit both entry and exit orders simultaneously since Alpaca’s system only accepts exit orders for existing positions. Additionally, even if you had an open position, you would not be able to submit two conditional closing orders since Alpaca’s system would view one of the two orders as exceeding the available position quantity. Bracket orders address both of these issues, as Alpaca’s system recognizes the entry and exit orders as a group and queues them for execution appropriately.

In order to submit a bracket order, you need to supply additional parameters to the API. First, add a parameter order_class as “bracket”. Second, give two additional fields take_profit and stop_loss both of which are nested JSON objects. The take_profit object needs limit_price as a field value that specifies limit price of the take-profit order, and the stop_loss object needs a mandatory stop_price field and optional limit_price field. If limit_price is specified in stop_loss, the stop-loss order is queued as a stop-limit order, but otherwise it is queued as a stop order.

An example JSON body parameter to submit a bracket order is as follows.

{
  "side": "buy",
  "symbol": "SPY",
  "type": "market",
  "qty": "100",
  "time_in_force": "gtc",
  "order_class": "bracket",
  "take_profit": {
    "limit_price": "301"
  },
  "stop_loss": {
    "stop_price": "299",
    "limit_price": "298.5"
  }
}

This creates three orders.

• A buy market order for 100 SPY with GTC
• A sell limit order for the same 100 SPY, with limit price = 301
• A sell stop-limit order, with stop price = 299 and limit price = 298.5

The second and third orders won’t be active until the first order is completely filled. Additional bracket order details include:

• If any one of the orders is canceled, any remaining open order in the group is canceled.
• take_profit.limit_price must be higher than stop_loss.stop_price for a buy bracket order, and vice versa for a sell.
• Both take_profit.limit_price and stop_loss.stop_price must be present.
• Extended hours are not supported. extended_hours must be “false” or omitted.
• time_in_force must be day or gtc.
• Each order in the group is always sent with a DNR/DNC (Do Not Reduce/Do Not Cancel) instruction. Therefore, the order price will not be adjusted and the order will not be canceled in the event of a dividend or other corporate action.
• If the take-profit order is partially filled, the stop-loss order will be adjusted to the remaining quantity.
• Order replacement (PATCH /v2/orders) is supported to update limit_price and stop_price.

Each order of the group is reported as an independent order in GET /v2/orders endpoint. But if you specify additional parameter nested=true, the order response will nest the result to include child orders under the parent order with an array field legs in the order entity.

OCO Orders

OCO (One-Cancels-Other) is another type of advanced order type. This is a set of two orders with the same side (buy/buy or sell/sell) and currently only exit order is supported. In other words, this is the second part of the bracket orders where the entry order is already filled, and you can submit the take-profit and stop-loss in one order submission.

With OCO orders, you can add take-profit and stop-loss after you open the position, without thinking about those two legs upfront.

In order to submit an OCO order, specify “oco” for the order_class parameter.

{
  "side": "sell",
  "symbol": "SPY",
  "type": "limit",
  "qty": "100",
  "time_in_force": "gtc",
  "order_class": "oco",
  "take_profit": {
    "limit_price": "301"
  },
  "stop_loss": {
    "stop_price": "299",
    "limit_price": "298.5"
  }
}

{
  "side": "buy",
  "symbol": "SPY",
  "type": "limit",
  "qty": "100",
  "time_in_force": "gtc",
  "order_class": "oco",
  "take_profit":{
    "limit_price": "298"
  },
  "stop_loss": {
    "stop_price": "299",
    "limit_price": "300"
  }
}

The type parameter must always be “limit”, indicating the take-profit order type is a limit order. The stop-loss order is a stop order if only stop_price is specified, and is a stop-limit order if both limit_price and stop_price are specified (i.e. stop_price must be present in any case). Those two orders work exactly the same way as the two legs of the bracket orders.

Note that when you retrieve the list of orders with the nested parameter true, the take-profit order shows up as the parent order while the stop-loss order appears as a child order.

Like bracket orders, order replacement is supported to update limit_price and stop_price.

OTO Orders

OTO (One-Triggers-Other) is a variant of bracket order. It takes one of the take-profit or stop-loss order in addition to the entry order. For example, if you want to set only a stop-loss order attached to the position, without a take-profit, you may want to consider OTO orders.

The order submission is done with the order_class parameter be “oto”.

{
  "side": "buy",
  "symbol": "SPY",
  "type": "market",
  "qty": "100",
  "time_in_force": "gtc",
  "order_class": "oto",
  "stop_loss": {
    "stop_price": "299",
    "limit_price": "298.5"
  }
}

Either of take_profit or stop_loss must be present (the above example is for take-profit case), and the rest of requirements are the same as the bracket orders.

Like bracket orders, order replacement is not supported yet.

Threshold on stop price of stop-loss orders

For the stop-loss order leg of advanced orders, please be aware the order request can be rejected because of the restriction of the stop_price parameter value. The stop price input has to be at least $0.01 below (for stop-loss sell, above for buy) than the “base price”. The base price is determined as follows.

• It is the limit price of the take-profit, for OCO orders.
• It is the limit price of the entry order, for bracket or OTO orders if the entry type is limit.
• It is also the current market price for any, of OCO, OTO and bracket.

This restriction is to avoid potential race-conditions in the order handling, but as we improve our system capability, this may be loosened in the future.

Trailing Stop Orders

Trailing stop orders allow you to continuously and automatically keep updating the stop price threshold based on the stock price movement. You request a single order with a dollar offset value or percentage value as the trail and the actual stop price for this order changes as the stock price moves in your favorable way, or stay at the last level otherwise. This way, you don’t need to monitor the price movement and keep sending replace requests to update the stop price close to the latest market movement.

Trailing stop orders keep track of the highest (for sell, lowest for buy) prices (called high water mark, or hwm) since the order was submitted, and the user-specified trail parameters determine the actual stop price to trigger relative to high water mark. Once the stop price is triggered, the order turns into a market order, and it may fill above or below the stop trigger price.

To submit a trailing stop order, you will set the type parameter to “trailing_stop”. There are two order submission parameters related to trailing stop, one of which is required when type is “trailing_stop”.

One of these values must be set for trailing stop orders. The following is an example of trailing order submission JSON parameter.

{
  "side": "sell",
  "symbol": "SPY",
  "type": "trailing_stop",
  "qty": "100",
  "time_in_force": "day",
  "trail_price": "6.15"
}

The Order entity returned from the GET method has a few fields related to trailing stop orders.

If a trailing stop order is accepted, the order status becomes “new”. While the order is pending stop price trigger, you can update the trail parameter by the PATCH method.

Some notes on trailing stop orders

• Trailing stop will not trigger outside of the regular market hours.
• Valid time-in-force values for trailing stop are “day” and “gtc”.
• Trailing stop orders are currently supported only with single orders. However, we plan to support trailing stop as the stop loss leg of bracket/OCO orders in the future.

Proper use of Trailing Stop orders requires understanding the purpose and how they operate. The primary point to keep in mind with Trailing Stop orders is to ensure the difference between the trailing stop and the price is big enough that typical price fluctuations do not trigger a premature execution.

In fast moving markets, the execution price may be less favorable than the stop price. The potential for such vulnerability increases for GTC orders across trading sessions or stocks experiencing trading halts. The stop price triggers a market order and therefore, it is not necessarily the case that the stop price will be the same as the execution price.

With regard to stock splits, Alpaca reserves the right to cancel or adjust pricing and/or share quantities of trailing stop orders based upon its own discretion. Since Alpaca relies on third parties for market data, corporate actions or incorrect price data may cause a trailing stop to be triggered prematurely.

Time in Force

🚧

Crypto Time in Force

For Crypto Trading, Alpaca only supports gtc, and ioc.

OPG, fok, day, and CLS are not supported.

Alpaca supports the following Time-In-Force designations:

Order Lifecycle

An order executed through Alpaca can experience several status changes during its lifecycle.

The most common statuses are described in detail below:

Less common states are described below. Note that these states only occur on very rare occasions, and most users will likely never see their orders reach these states:

An order may be canceled through the API up until the point it reaches a state of either filled, canceled, or expired.

Odd Lots and Block Trades

When trading stocks, a round lot is typically defined as 100 shares, or a larger number that can be evenly divided by 100. An odd lot is anything that cannot be evenly divided by 100 shares (e.g. 48, 160, etc.). A block trade is typically defined as a trade that involves 10,000 shares or more.

For trading purposes, odd lots are typically treated like round lots. However, regulatory trading rules allow odd lots to be treated differently. Similarly, block trades are usually broken up for execution and may take longer to execute due to the market having to absorb the block of shares over time rather than in one large execution. When combined with a thinly traded stock, it’s quite possible that odd lots and block trades may not get filled or execute in a timely manner, and sometimes, not at all, depending on other factors like order types used.

Short Sales

A short sale is the sale of a stock that a seller does not own. In general, a short seller sells borrowed stock in anticipation of a price decline. The short seller later closes out the position by purchasing the stock.

Order Handling Standards at Alpaca Securities LLC

Market and limit order orders are protected on the primary exchange opening print. We do not necessarily route retail orders to the exchange, but will route orders to market makers who will route orders on your behalf to the primary market opening auction. This protection is subject to exchange time cutoff for each exchange’s opening process. For instance, if you enter a market order between 9:28:01 and 9:29:59 on a Nasdaq security you would not receive the Nasdaq Official Opening Price (NOOP) since Nasdaq has a cutoff of 9:28 for market orders to be sent to the cross. Any market orders received before 9:28 will be filled at the Nasdaq Official Opening Price.

Stop orders and trailing stops are elected on the consolidated print. Your sell stop order will only elect if there is a trade on the consolidated tape at or lower than your stop price and provided the electing trade is not outside of the NBBO. Your buy stop order will only elect if there is a trade on the consolidated tape that is at or above your stop price that is not outside of the NBBO.

Limit Orders are generally subject to limit order display and protection. Protection implies that you should not see the stock trade better than your limit without you receiving an execution. Limit Order Display is bound by REG NMS Rule 611. Your orders will be displayed if they are the National Best Bid or Best Offer excluding exceptions outlined REG NMS Rule 611. Some examples are listed below:

• An odd lot order (under a unit of trade). Most NMS securities have a unit of trade of 100 shares.
• Block Order. A block order under REG NMS is designated as an order of at least 10,000 shares or at least $200,000 notional.
• An “all or none” order
• The client requests the order to not be displayed.
• Not Held orders

OTC Positions

OTC positions that are actively trading will not be automatically removed/liquidated from a user's account. The user can submit orders if the client wishes to remove or liquidate them.

OTC markets have several market tiers and depending on the market tier there may be more considerations when placing an order to close the position.

OTC Market Tier
OTCQX, OTCQB, Pink (Current, limited, No information)
Clients can enter market orders, limit orders and stop orders to close positions. For market orders, clients can mix whole shares and fractional shares.

Expert Market, Caveat Emptor
Clients must enter limit orders for whole shares, fractional shares in an order with whole shares will not be accepted. We are not able to accept a combination of a whole and fractional share for Expert Market and Caveat Emptor securities. Clients must enter a market in order to sell a fractional position.

Example: User owns 10.53 shares of WXYZ Stock: Sell Limit Order for 10 shares of WXYZ Stock and Sell Market Order for 0.53 shares of WXYZ Stock.

OTC market data is a separate data subscription. In many circumstances, a client can obtain a real-time level one quote from otcmarkets.com. Additionally, you can check the OTC market tier on that website as well.