Understand Orders

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.

Orders Submitted Outside of Eligible Trading Hours

Orders submitted outside of Regular Trading Hours (9:30am - 4:00pm ET) that are not eligible to be executed during extended hours will be queued and eligible for execution at the time of the next market open.

Orders eligible for extended hours submitted outside of 9:00am - 6:00pm ET are handled as described in the section below.

Extended Hours Trading

Using API v2 (only available to ETC accounts), you can submit and fill orders during pre-market and after-hours. This feature is not available to legacy accounts or those using API v1. Extended hours trading has specific risks due to the less liquidity. Please read through our disclosure for more details.

Currently, we supported the following extended hours:
Pre-market: 9:00 - 9:30am
After-hours: 4:00 - 6:00pm

Additionally, please be aware of the following constraints.

  • If the order is submitted between 6:00pm and 8:00pm ET on a market day, the order request is returned with error. Alpaca reserves this time window for future expansion of supported hours.
  • If the order is submitted after 8:00pm but before 9:00am ET of the following trading day, the order request is queued and will be eligible for execution from the beginning of the next available supported pre-market hours at 9:00am.

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 as 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 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.

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

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.

To protect against excessive price impact and buying power violations, Alpaca converts buy market orders into marketable limit orders with a price limit that is 4% higher than a current market price < $50 and 2.5% higher than a current market price >= $50. In most cases, this will have the same exact outcome as using a true market order. However, if the stock price moves more than 4% (or 2.5% for >=$50/share stocks) above the market price in the time that it takes to route your order to the execution venue, then your order would not execute until the price came back within the collar. Sell market orders are not converted into limit orders.

If you submit a buy market order during pre-market or extended-hours trading, we use the last traded price to determine the limit price. This means that if the stock opens more than 4% (or 2.5% for >=$50/share stocks) above the last traded price that existed at the time you submitted your order, your order won’t be executed until the price comes back within the price collar.

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.

Hyper-marketable Limit Order Rejection A limit orders with a limit price that significantly exceeds the current market price will be rejected as part of our risk checks to mitigate against “fat finger” errors. We currently use exchange guidelines for erroneous trades to determine the thresholds at which orders are rejected:

Share Price Threshold
Greater than $0.00 up to and including $25.00 10%
Greater than $25.00 up to and including $50.00 5%
Greater than $50.00 3%

The thresholds are doubled during pre-market and after-hours.

Stop Order

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 market price crosses the specified stop price, 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.

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 order to submit a stop limit order, you will need to specify both the limit and stop price parameters in the API.

Advanced Order Types

Advanced order types such as OCO(one-cancels-the-other), trailing stop, and MOC are coming soon. Stay tuned!

Time in Force

Alpaca supports the following Time-In-Force designations:

  • day
    A day order is eligible for execution only on the day it is live. By default, the order is only valid during Regular Trading Hours (9:30am - 4:00pm ET). If unfilled after the closing auction, it is automatically canceled. If submitted after the close, it is queued and submitted the following trading day. However, if marked as eligible for extended hours, the order can also execute during supported extended hours.
  • gtc
    The order is good until canceled. Non-marketable GTC limit orders are subject to price adjustments to offset corporate actions affecting the issue. We do not currently support Do Not Reduce(DNR) orders to opt out of such price adjustments.
  • opg
    The order is eligible to execute only in the market opening auction. The order will be accepted if it is received before 9:15AM ET. The order can be cancelled after 9:15AM, but it cannot be edited. After 9:28AM, OPG orders cannot be edited or cancelled. Any unfilled orders after the open will be cancelled. If you submit an OPG order during market hours, it will appear as “rejected” in your dashboard.
  • ioc
    An Immediate Or Cancel (IOC) order requires all or part of the order to be executed immediately. Any unfilled portion of the order is canceled. Only available with API v2.
  • fok
    A Fill or Kill (FOK) order is only executed if the entire order quantity can be filled, otherwise the order is canceled. Only available with API v2.

Order Lifecycle

An order executed through Alpaca can experience several status changes during its lifecycle. The most common statuses are described in detail below:

  • new
    The order has been received by Alpaca, and routed to exchanges for execution. This is the usual initial state of an order.
  • partially_filled
    The order has been partially filled.
  • filled
    The order has been filled, and no further updates will occur for the order.
  • done_for_day
    The order is done executing for the day, and will not receive further updates until the next trading day.
  • canceled
    The order has been canceled, and no further updates will occur for the order. This can be either due to a cancel request by the user, or the order has been canceled by the exchanges due to its time-in-force.
  • expired
    The order has expired, and no further updates will occur for the order.

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:

  • accepted
    The order has been received by Alpaca, but hasn’t yet been routed to the execution venue. This state only occurs on rare occasions.
  • pending_new
    The order has been received by Alpaca, and routed to the exchanges, but has not yet been accepted for execution. This state only occurs on rare occasions.
  • accepted_for_bidding
    The order has been received by exchanges, and is evaluated for pricing. This state only occurs on rare occasions.
  • pending_cancel
    The order is waiting to be canceled. This state only occurs on rare occasions.
  • stopped
    The order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred. This state only occurs on rare occasions.
  • rejected
    The order has been rejected, and no further updates will occur for the order. This state occurs on rare occasions and may occur based on various conditions decided by the exchanges.
  • suspended
    The order has been suspended, and is not eligible for trading. This state only occurs on rare occasions.
  • calculated
    The order has been completed for the day (either filled or done for day), but remaining settlement calculations are still pending. This state only occurs on rare occasions.

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

Buying Power

In order to submit a buy order and have it accepted, your account must have sufficient buying power. Alpaca calculates the value of a buy order as the order’s limit price (in the case of market orders, the limit price is 2.5% to 4% above the current market price as noted above) multiplied by the order’s quantity. The value of the order is then checked against your available cash balance to determine if it can be accepted. Please note that your available cash balance is reduced by other open (pending) buy orders, while sell orders do not add to your available cash balance until they have executed.

For example, if your cash balance 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 cash balance 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.

Suggestions or questions?
We're always happy to hear from you. You can contribute to these docs on GitHub, or you can join our Community Slack to get help from other community members and the Alpaca team.