Orders #

The Orders API allows a user to 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 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.

For further details on order functionality, please see the Trading On Alpaca - Orders page.

Please note that body parameters should be passed using a JSON encoded body.

Get a list of orders

GET /v2/orders

Retrieves a list of orders for the account, filtered by the supplied query parameters.

Parameters

Query Parameters

Attribute	Type	Requirement	Description
`status`	string	Optional	Order status to be queried. `open`, `closed` or `all`. Defaults to `open`.
`limit`	int	Optional	The maximum number of orders in response. Defaults to 50 and max is 500.
`after`	timestamp	Optional	The response will include only ones submitted after this timestamp (exclusive.)
`until`	timestamp	Optional	The response will include only ones submitted until this timestamp (exclusive.)
`direction`	string	Optional	The chronological order of response based on the submission time. `asc` or `desc`. Defaults to `desc`.
`nested`	boolean	Optional	If true, the result will roll up multi-leg orders under the `legs` field of primary order.
`side`	string	Optional	Filters down to orders that have a matching `side` field set. See the Order model’s `side` field for the values you can specify here
`symbols`	string	Optional	A comma-separated list of symbols to filter by (ex. “AAPL,TSLA,MSFT”). A currency pair is required for crypto orders (ex. “BTCUSD,BCHUSD,LTCUSD,ETCUSD”).

Response

An array of Order object

Get All Orders Recipe

Looking for a way to get all your orders when faced with 500 orders per API call limit? See Get All Orders recipe for a readible code example with Python.

Request a new order

POST /v2/orders

Places a new order for the given account. An order request may be rejected if the account is not authorized for trading, or if the tradable balance is insufficient to fill the order.

Parameters

Body Parameters

Attribute	Type	Requirement	Description
`symbol`	string	Required	symbol, asset ID, or currency pair to identify the asset to trade
`qty`	string<number>	Required	number of coins/tokens to trade.
`notional`	string<number>	Required	dollar amount to trade. Cannot work with `qty`.
`side`	string	Required	`buy` or `sell`
`type`	string	Required	`market`, `limit`, `stop_limit`
`time_in_force`	string	Required	Please see Understand Orders for more info on what values are possible for what kind of orders.
`limit_price`	string<number>	Required	required if type is `limit` or `stop_limit`
`stop_price`	string<number>	Required	required if type is `stop_limit`
`client_order_id`	string (<= 48 characters)	Optional	A unique identifier for the order. Automatically generated if not sent.
`order_class`	string	Optional	`simple`, `bracket`, `oco` or `oto`. For details of non-simple order classes, please see Bracket Order Overview
`take_profit`	object	Optional	Additional parameters for take-profit leg of advanced orders
`stop_loss`	object	Optional	Additional parameters for stop-loss leg of advanced orders

Response

The new Order object

Errors

403 Forbidden

Buying power or shares is not sufficient.

422 Unprocessable

Input parameters are not recognized.

Get an order

GET /v2/orders/{order_id}

Retrieves a single order for the given order_id.

Parameters

Path Parameters

Attribute	Type	Requirement	Description
`order_id`	string<uuid>	Optional	Order ID

Response

The requested Order object

Errors

404 Not found

Order is not found.

Get an order by client order id

GET /v2/orders:by_client_order_id

Retrieves a single order for the given client_order_id.

Parameters

Query Parameters

Attribute	Type	Requirement	Description
`client_order_id`	string	Optional	Client Order ID

Response

The requested Order object

Errors

404 Not found

Order is not found.

Replace an order

PATCH /v2/orders/{order_id}

Replaces a single order with updated parameters. Each parameter overrides the corresponding attribute of the existing order. The other attributes remain the same as the existing order.

A success return code from a replaced order does NOT guarantee the existing open order has been replaced. If the existing open order is filled before the replacing (new) order reaches the execution venue, the replacing (new) order is rejected, and these events are sent in the trade_updates stream channel. Read more about the trade stream updates here.

While an order is being replaced, buying power is reduced by the larger of the two orders that have been placed (the old order being replaced, and the newly placed order to replace it). If you are replacing a buy entry order with a higher limit price than the original order, the buying power is calculated based on the newly placed order. If you are replacing it with a lower limit price, the buying power is calculated based on the old order.

Parameters

Path Parameters

Attribute	Type	Requirement	Description
`order_id`	string<uuid>	Optional	Order ID

Body Parameters

Attribute	Type	Requirement	Description
`qty`	string<int>	Optional	number of shares to trade
`time_in_force`	string	Optional	Please see Understand Orders for more info on what values are possible for what kind of orders.
`limit_price`	string<number>	Optional	required if type is `limit` or `stop_limit`
`stop_price`	string<number>	Optional	required if type is `stop_limit`
`client_order_id`	string (<= 48 characters)	Optional	A unique identifier for the order. Automatically generated if not sent.

Response

The new Order object with the new order ID.

Errors

403 Forbidden

Buying power or shares is not sufficient.

422 Unprocessable

Input parameters are not recognized.

Cancel all orders

DELETE /v2/orders

Attempts to cancel all open orders. A response will be provided for each order that is attempted to be cancelled. If an order is no longer cancelable, the server will respond with status 500 and reject the request.

Response

HTTP 207 Multi-Status with body; an array of objects that include the order id and http status code for each status request.

Errors

500

Failed to cancel order.

Cancel an order

DELETE /v2/orders/{order_id}

Attempts to cancel an open order. If the order is no longer cancelable (example: status="filled"), the server will respond with status 422, and reject the request. Upon acceptance of the cancel request, it returns status 204.

Parameters

Path Parameters

Attribute	Type	Requirement	Description
`order_id`	string<uuid>	Optional	Order ID

Response

Errors

404 Not found

Order is not found.

422 Unprocessable

The order status is not cancelable.

Order Entity #

Example #

{
  "id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565dad4",
  "created_at": "2021-03-16T18:38:01.942282Z",
  "updated_at": "2021-03-16T18:38:01.942282Z",
  "submitted_at": "2021-03-16T18:38:01.937734Z",
  "filled_at": null,
  "expired_at": null,
  "canceled_at": null,
  "failed_at": null,
  "replaced_at": null,
  "replaced_by": null,
  "replaces": null,
  "asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
  "symbol": "BTC/USD",
  "asset_class": "crypto",
  "notional": "500",
  "qty": null,
  "filled_qty": "0",
  "filled_avg_price": null,
  "order_class": "",
  "order_type": "market",
  "type": "market",
  "side": "buy",
  "time_in_force": "day",
  "limit_price": null,
  "stop_price": null,
  "status": "accepted",
  "extended_hours": false,
  "legs": null,
  "trail_percent": null,
  "trail_price": null,
  "hwm": null
}

Properties #

Attribute	Type	Description
`id`	string<uuid>	Order ID
`client_order_id`	string	Client unique order ID
`created_at`	string<timestamp>
`updated_at`	string<timestamp> (Nullable)
`submitted_at`	string<timestamp> (Nullable)
`filled_at`	string<timestamp> (Nullable)
`expired_at`	string<timestamp> (Nullable)
`canceled_at`	string<timestamp> (Nullable)
`failed_at`	string<timestamp> (Nullable)
`replaced_at`	string<timestamp> (Nullable)
`replaced_by`	string<uuid> (Nullable)	The order ID that this order was replaced by
`replaces`	string<uuid> (Nullable)	The order ID that this order replaces
`asset_id`	string<uuid>	Asset ID
`symbol`	string	Asset symbol
`asset_class`	string	Asset class
`notional`	string<number>	Ordered notional amount. If entered, `qty` will be null. Can take up to 9 decimal points.
`qty`	string<number>	Ordered quantity. If entered, `notional` will be null. Can take up to 9 decimal points.
`filled_qty`	string<number>	Filled quantity
`filled_avg_price`	string<number> (Nullable)	Filled average price
`order_type`	string	(Deprecated with just `type` field below.)
`type`	string<order_type>	Valid values: `market`, `limit`, `stop_limit`
`side`	string<side>	Valid values: `buy`, `sell`
`time_in_force`	string<time_in_force>	For crypto, only `gtc` and `ioc`. See Orders page.
`limit_price`	string<number> (Nullable)	Limit price
`status`	string<order_status>	See Orders page

Disclosures

Brokerage services are provided by Alpaca Securities, member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc.

Technology and services are offered by AlpacaDB, Inc.

Brokerage services are provided to customers who can write automated investment code and self-direct their own investments. Alpaca brokerage services are only provided to customers who agree to electronically sign agreements and agree to receive messages, confirmations, and statements electronically. Is Alpaca right for me?

This is not an offer, solicitation of an offer, or advice to buy or sell securities or cryptocurrencies, or open a brokerage account or cryptocurrency account in any jurisdiction where Alpaca Securities or Alpaca Crypto respectively, are not registered or licensed, as applicable.

The Paper Trading API is offered by AlpacaDB, Inc. and does not require real money or permit a user to transact in real securities in the market. Providing use of the Paper Trading API is not an offer or solicitation to buy or sell securities, securities derivative or futures products of any kind, or any type of trading or investment advice, recommendation or strategy, given or in any manner endorsed by AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate and the information made available through the Paper Trading API is not an offer or solicitation of any kind in any jurisdiction where AlpacaDB, Inc. or any AlpacaDB, Inc. affiliate (collectively, "Alpaca") is not authorized to do business.

You should know that the use or granting of any third party access to your account information or place transactions in your account at your direction is solely at your risk. Alpaca does not warrant against loss of use or any direct, indirect or consequential damages or losses to you caused by your assent, expressed or implied, to a third party accessing your account or information, including access provided through any other third party apps, systems, or sites.

Market prices, data and other information available through Alpaca are not warranted as to completeness or accuracy and are subject to change without notice. System response and account access times may vary due to a variety of factors, including trading volumes, market conditions, system performance, and other factors. A more complete description of the impact these factors may have can be found in our risks of automated trading systems section.

All investments involve risk and the past performance of a security, or financial product does not guarantee future results or returns. Keep in mind that while diversification may help spread risk it does not assure a profit, or protect against loss, in a down market. There is always the potential of losing money when you invest in securities, or other financial products. Investors should consider their investment objectives and risks carefully before investing.

There are risks unique to automated trading algorithms that you should know about and plan for. You should setup a method or system of continuous monitoring or alerting to let you know if there is a mechanical failure, such as connectivity issues, power loss, a computer crash, or system quirk. You should also monitor for instances where your automated trading system experiences anomalies that could result in errant, missing, or duplicated orders. A more complete description of these and other risks can be found in our FAQ section.

Conditional orders may have increased risk as a result of their reliance on trigger processing, market data, and other internal and external systems. Such orders are not sent to the market until specified conditions are met. During that time, issues such as system outages with downstream technologies or third parties may occur. Conditional orders triggering near the market close may fail to execute that day. Furthermore, our executing partner may impose controls on conditional orders to limit erroneous trades triggering downstream orders. Alpaca Securities may not always be made aware of such changes to external controls immediately, which may lead to some conditional orders not being executed. As such, it is important to monitor conditional orders for reasonability. Conditional orders are “Not Held” orders whose execution instructions are on a best efforts basis upon being triggered. Furthermore, conditional orders may be subject to the increased risks of stop orders and market orders outlined above. Given the increased potential risk of using conditional orders, the client agrees that Alpaca Securities cannot be held responsible for losses, damages, or missed opportunity costs associated with market data problems, systems issues, and user error, among other factors. By using conditional orders the client understands and accepts the risks outlined above. Alpaca Securities encourages leveraging the use of Paper accounts to become more comfortable with the intricacies associated with these orders.

ETFs can entail risks similar to direct stock ownership, including market, sector, or industry risks. Some ETFs may involve international risk, currency risk, commodity risk, and interest rate risk. Trading prices may not reflect the net asset value of the underlying securities.

All accounts are opened as limited purpose margin accounts. You should know that margin trading involves interest charges and risks, including the potential to lose more than deposited or the need to deposit additional collateral in a falling market. Before using margin, customers must determine whether this type of trading strategy is right for them given their specific investment objectives, experience, risk tolerance, and financial situation. For more information please see Alpaca's Margin Disclosure Statement and Margin Agreement. These disclosures contain information on Alpaca Securities's lending policies, interest charges, and the risks associated with margin accounts.

Commission-Free trading means that there are no commission charges for Alpaca Securities self-directed individual brokerage accounts that trade U.S. listed securities through an API. Relevant regulatory fees may apply.

Commission free trading is available for Alpaca's retail customers. Alpaca reserves the right to charge additional fees if it is determined that orders flow is non-retail in nature.

Cryptocurrency is highly speculative in nature, involves a high degree of risks, such as volatile market price swings, market manipulation, flash crashes, and cybersecurity risks. Cryptocurrency is not regulated or is lightly regulated in most countries. Cryptocurrency trading can lead to large, immediate and permanent loss of financial value. You should have appropriate knowledge and experience before engaging in cryptocurrency trading. For additional information please click here.

Cryptocurrency services are made available by Alpaca Crypto, a FinCEN registered money services business (NMLS # 2160858), and a wholly-owned subsidiary of AlpacaDB, Inc. Alpaca Crypto is not a member of SIPC or FINRA. Cryptocurrencies are not stocks and your cryptocurrency investments are not protected by either FDIC or SIPC. Please see the Disclosure Library for more information.