Orders #
The Orders API allows you to monitor, place and cancel your end user order requests. Each order has a unique identifier (client_order_id
) that could be provided by you. 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_order_id
or order_id
to check the status. Updates on open orders at Alpaca will also be sent over the streaming interface found here, which is the recommended method of maintaining order state.
The Order Object #
Sample Order Object #
{
"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": "AAPL",
"asset_class": "us_equity",
"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,
"commission": "1.25",
"commission_bps": "100"
}
Attributes #
Attribute | Type | Notes |
---|---|---|
id |
string/UUID | Order ID generated by Alpaca |
client_order_id |
string/UUID | Client unique order ID |
created_at |
string/timestamp | Time when order was entered |
updated_at |
string/timestamp | Time of most recent change to the order |
submitted_at |
string/timestamp | Time the order was submitted for execution or, if not yet submitted the created_at time. Because orders are submitted for execution asynchronous to database updates, at times this may be before the created_at time. |
filled_at |
string/timestamp | Time the order was filled. Can be null if not filled |
expired_at |
string/timestamp | Can be null |
cancelled_at |
string/timestamp | Can be null |
failed_at |
string/timestamp | Can be null |
replaced_at |
string/timestamp | Can be null |
replaced_by |
string/UUID | The order ID that this order was replaced by. (Can be null ) |
replaces |
string/UUID | The order ID that this order replaces. (Can be null ) |
asset_id |
string/UUID | The asset ID |
symbol |
string | The asset symbol |
asset_class |
string | The asset class |
notional |
string/number | Ordered notional amount. If entered, qty will be null. Can take up to 2 decimal points. |
qty |
string/number | Ordered quantity. If entered, notional will be null. Can take up to 2 decimal points. |
filled_qty |
string/number | Filled quantity |
filled_avg_price |
string/number | Filled average price. Can be 0 until order is processed in case order is passed outside of market hours |
order_class |
string | Valid values: simple , bracket , oco or oto |
order_type |
string/number | (Deprecated with just type field below.) |
type |
string | Valid values: market , limit , stop , stop_limit , trailing_stop |
side |
string | Valid values: buy and sell |
time_in_force |
string | Please see the relevant section in Understand Orders for more info on what values are possible for what kind of orders. |
limit_price |
string/number | Limit price |
stop_price |
string/number | Stop price |
status |
string | Enum.OrderStatus |
extended_hours |
boolean | If true, eligible for execution outside regular trading hours. |
legs |
array | When querying non-simple order_class orders in a nested style, an array of Order entities associated with this order. Otherwise, null. |
trail_percent |
string/number | The percent value away from the high water mark for trailing stop orders. |
trail_price |
string/number | The dollar value away from the high water mark for trailing stop orders. |
hwm |
string/number | The highest (lowest) market price seen since the trailing stop order was submitted. |
commission |
string/number | The dollar value commission you want to charge the end user. |
commission_bps |
string/number | The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission |
swap_rate |
string/number | Swap rate is the exchange rate (without mark-up) used to convert the price into local currency or crypto asset |
swap_fee_bps |
string/number | Fee in basis points on top swap rate charged by the correspondent on every order |
usd |
object | Nested object to encompass the USD equivalent fields for the local currency fields |
Enums #
Order Status #
Status | Description |
---|---|
new |
The order has been received by Alpaca, and routed to exchanges for execution. This is the usual initial state of an order. |
accepted |
|
held |
For multi-leg orders, the secondary orders (stop loss, take profit) will enter this state while waiting to be triggered. |
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. |
replaced |
The order was replaced by another order, or was updated due to a market event such as corporate action. |
pending_cancel |
The order is waiting to be canceled. |
pending_replace |
The order is waiting to be replaced by another order. The order will reject cancel request while in this state. |
Less common states are described below. Note that these states only occur on very rare occasions, and most orders will likely never reach these states:
Status | Description |
---|---|
accepted |
The order has been received by Alpaca, but hasn’t yet been routed to the execution venue. This could be seen often outside of trading session hours. |
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. |
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. No further updates will occur for the order. |
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
.
Fractional Trading #
All correspondent accounts at Alpaca have fractional trading enabled by default. You can now allow your users to participate in fractional trading in two ways:
- Inputting a fractional amount in
qty
- Inputting a notional amount in the
notional
field of the POST request body
Passing Commissions #
If you want to collect commissions on trades requested by your users you can simply pass in the POST request body a dollar amount in a string in the commission
field, or a percentage of the order (in bps) in the commission_bps
field.
{
"symbol": "AAPL",
"qty": "4.125",
"side": "buy",
"type": "market",
"time_in_force": "day",
"commission": "1"
}
Creating an Order #
POST /v1/trading/accounts/{account_id}/orders
Creating an order for your end customer. Each trading request must pass in the account_id
in the URL.
Request #
Sample Request #
{
"symbol": "ETHUSD",
"qty": "4.125",
"side": "buy",
"type": "market",
"time_in_force": "gtc"
}
Parameters #
Attribute | Type | Requirement | Notes |
---|---|---|---|
symbol |
string | Required |
Symbol or asset ID to identify the asset to trade |
qty |
string/number | Required |
Number of shares to trade. Can be fractionable for only market and day order types. |
notional |
string/number | Required |
Dollar amount to trade. Cannot work with qty . Can only work for market order types and time_in_force = day . |
side |
string | Required |
buy or sell |
type |
string | Required |
market , limit , stop , stop_limit , or trailing_stop |
time_in_force |
string | Required |
Please see the relevant section in Understand Orders for more info on what values are possible for what kind of orders. |
limit_price |
string/number | Optional |
RequiredIf type is limit or stop_limit |
stop_price |
string/number | Optional |
RequiredIf type is stop or stop_limit |
trail_price |
string/number | Optional |
RequiredIf type is trailing_stop , trail_price or trail_percent is required |
trail_percent |
string/number | Optional |
RequiredIf type is trailing_stop , trail_price or trail_percent is required |
extended_hours |
string | Optional |
Defaults to false . If true , order will be eligible to execute in premarket/afterhours. Only works with type limit and time_in_force = day . |
client_order_id |
string/UUID | Optional |
A unique identifier for the order. Automatically generated if not sent. (<= 48 characters) |
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 |
Takes in a string/number value for limit_price |
stop_loss |
object | Optional |
Takes in a string/number values for stop_price and limit_price |
commission |
string/numeric | Optional |
The commission you want to collect from the user. |
commission_bps |
string/numeric | Optional |
The commission you want to collect from the user, expressed in bps on the order. |
source |
string/numeric | Optional |
|
instructions |
string/numeric | Optional |
|
subtag |
string/numeric | Optional |
|
swap_fee_bps |
string/numeric | Optional |
Note that when submitting crypto orders, Market, Limit and Stop Limit orders are supported while the supported time_in_force
values are gtc
, and ioc
.
We accept fractional orders as well with either notional
or qty
provided.
Response #
Returns an Order object.
Estimating an Order #
POST /v1/trading/accounts/{account_id}/orders/estimation
Order estimation endpoint will display, based on user’s account balance, the estimated quantity and price they will receive for their notional order.
For LCT - customer’s order will include the Alpaca swap_fee
, while correspondent side swap_fee
is configurable in the API call. Utilising this API does not result in a real order and after the calculation - the user’s buying power reverts to the previous state.
Responses and Errors are the same as with the Orders API
Please note that the estimation is based on the market condition at the time of submission and a live order will differ. The output should be considered indicative.
Note: This does not support Crypto or non-market orders at this time.
Request #
Sample Request #
{
"symbol": "AAPL",
"side": "buy",
"type": "market",
"time_in_force": "day",
"notional": "40",
"swap_fee_bps": 45
}
Response #
{
"id": "bc215c69-b3c9-44b4-afff-896962ea6fd0",
"client_order_id": "1eebf13e-0308-40f4-b4a1-0bb0b37bc896",
"created_at": "2022-08-18T19:21:41.316050251Z",
"updated_at": "2022-08-18T19:21:41.316050251Z",
"submitted_at": "2022-08-18T19:21:41.3135829Z",
"filled_at": "2022-08-18T19:21:41.3135829Z",
"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": "AAPL",
"asset_class": "us_equity",
"notional": "40",
"qty": null,
"filled_qty": "0.0016",
"filled_avg_price": "23717.854",
"order_class": "",
"order_type": "market",
"type": "market",
"side": "buy",
"time_in_force": "day",
"limit_price": null,
"stop_price": null,
"status": "filled",
"extended_hours": false,
"legs": null,
"trail_percent": null,
"trail_price": null,
"hwm": null,
"commission": "0",
"swap_rate": "135.88",
"swap_fee_bps": "70",
"subtag": null,
"source": null,
"usd": {
"notional": "0.2923",
"filled_avg_price": "174.55"
}
}
Getting All Orders #
GET /v1/trading/accounts/{account_id}/orders
Retrieves a list of orders for the account, filtered by the supplied query parameters. Endpoint defaults to open
orders if no parameters are provided.
Request #
Parameters #
Attribute | Type | Requirement | Notes |
---|---|---|---|
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. |
symbols |
string | Optional |
A comma-separated list of symbols to filter by (ex. “AAPL,BTCUSD,TSLA). |
qty_above |
string/number | Optional |
|
qty_below |
string/number | Optional |
|
subtag |
string | Optional |
Response #
An array of Order object
Getting an Order By Order ID #
GET /v1/trading/accounts/{account_id}/orders/{order_id}
Retrieves a single order for the given order_id
.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
nested |
boolean | BODY - If true, the result will roll up multi-leg orders under the legs field of primary order. |
Response #
The requested Order object
Error Codes #
404
- Order is not found
Getting an Order By Client Order ID #
GET /v1/trading/accounts/{account_id}/orders:by_client_order_id
Retrieves a single order for the given client_order_id
passed as a query parameter.
Request #
Sample Request #
GET /v1/trading/accounts/7669ddfa-3592-41e7-befa-e3da441c913a/orders:by_client_order_id?client_order_id=28b224a5-eaef-448a-9a8f-3c6a2d02f07f
Parameters #
Attribute | Type | Notes |
---|---|---|
client_order_id |
string | QUERY - The client order ID |
Response #
An array containing the requested Order object
Error Codes #
404
- Order is not found
Patching an Order #
PATCH /v1/trading/accounts/{account_id}/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 found 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.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
qty |
string/int | You can only patch full shares for now |
time_in_force |
string/number | Please see the relevant section in Understand Orders for more info on what values are possible for what kind of orders. |
limit_price |
string/number | Required if type = limit or stop_limit |
stop_price |
string/number | Required if type = stop or stop_limit |
trail |
string/number | The new value of the trail_price or trail_percent |
client_order_id |
string/UUID |
Response #
A new Order object with a new order_id
Error Codes #
403
- ForbiddenBuying power or shares is not sufficient
422
- UnprocessableInput parameters are not recognized
Deleting All Orders #
DELETE /v1/trading/accounts/{account_id}/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.
Request #
N/A
Response #
HTTP 207 Multi-Status with body, which is an array of objects that include the order id, http status code and an order object for each cancellation request.
Sample Response Body #
[
{
"id": "aaeec1f3-4917-4cfd-b89f-bab24495d2ff",
"status": 200,
"body": {
"asset_class": "us_equity",
"asset_id": "93f58d0b-6c53-432d-b8ce-2bad264dbd94",
"canceled_at": null,
"client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565d115",
"commission": "1",
"created_at": "2021-06-01T07:50:08.061602Z",
"expired_at": null,
"extended_hours": false,
"failed_at": null,
"filled_at": null,
"filled_avg_price": null,
"filled_qty": "0",
"hwm": null,
"id": "aaeec1f3-4917-4cfd-b89f-bab24495d2ff",
"legs": null,
"limit_price": "500",
"notional": null,
"order_class": "simple",
"order_type": "stop_limit",
"qty": "1",
"replaced_at": null,
"replaced_by": null,
"replaces": null,
"side": "buy",
"status": "pending_cancel",
"stop_price": "600",
"submitted_at": "2021-06-01T07:50:08.048115Z",
"symbol": "AAPL",
"time_in_force": "gtc",
"trail_percent": null,
"trail_price": null,
"type": "stop_limit",
"updated_at": "2021-06-01T07:50:16.746769274Z"
}
},
{
"id": "f235da63-19c6-49c5-b179-1680576cf42b",
"status": 200,
"body": {
"asset_class": "us_equity",
"asset_id": "93f58d0b-6c53-432d-b8ce-2bad264dbd94",
"canceled_at": null,
"client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565d114",
"commission": "1",
"created_at": "2021-06-01T07:50:01.164738Z",
"expired_at": null,
"extended_hours": false,
"failed_at": null,
"filled_at": null,
"filled_avg_price": null,
"filled_qty": "0",
"hwm": null,
"id": "f235da63-19c6-49c5-b179-1680576cf42b",
"legs": null,
"limit_price": "500",
"notional": null,
"order_class": "simple",
"order_type": "stop_limit",
"qty": "1",
"replaced_at": null,
"replaced_by": null,
"replaces": null,
"side": "buy",
"status": "pending_cancel",
"stop_price": "600",
"submitted_at": "2021-06-01T07:50:01.154208Z",
"symbol": "AAPL",
"time_in_force": "gtc",
"trail_percent": null,
"trail_price": null,
"type": "stop_limit",
"updated_at": "2021-06-01T07:50:16.757113006Z"
}
}
]
Error Codes #
500
- Failed to cancel order.
Deleting an Order By Order ID #
DELETE /v1/trading/accounts/{account_id}/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.
Request #
Parameters #
Attribute | Type | Notes |
---|---|---|
order_id |
string | QUERY - The order ID |
Response #
204
- Success (No Content)
Error Codes #
404
- Not Found: Order is not found
422
- Unprocessable: The order status is not cancelable