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
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 objectGet 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
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 objectErrors
Get an order
GET /v2/orders/{order_id}
order_id
.
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
order_id |
string<uuid> | Optional |
Order ID |
Response
The requested Order objectErrors
Get an order by client order id
GET /v2/orders:by_client_order_id
client_order_id
.
Parameters
Query Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
client_order_id |
string | Optional |
Client Order ID |
Response
The requested Order objectErrors
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
Cancel all orders
DELETE /v2/orders
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
Cancel an order
DELETE /v2/orders/{order_id}
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
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 |