The Alpaca Trading API enables commission-free trading of US-listed equities, options, and crypto. It exposes endpoints for orders, positions, account information, watchlists, calendar, clock, and assets. A paper trading sandbox is available at paper-api.alpaca.markets.
openapi: 3.0.0
info:
title: Broker Account Activities Trading API
description: Open brokerage accounts, enable crypto and stock trading, and manage the ongoing user experience with Alpaca Broker API
version: 1.0.0
contact:
name: Alpaca Support
email: support@alpaca.markets
url: https://alpaca.markets/support
termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
servers:
- url: https://broker-api.sandbox.alpaca.markets
description: Sandbox endpoint
- url: https://broker-api.alpaca.markets
description: Production endpoint
security:
- BasicAuth: []
tags:
- name: Trading
paths:
/v1/trading/accounts/{account_id}/positions:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
summary: List open positions for an account
tags:
- Trading
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Position'
operationId: getPositionsForAccount
description: List open positions for an account
delete:
summary: Close All Positions for an Account
operationId: closeAllPositionsForAccount
responses:
'207':
description: HTTP 207 Multi-Status with body; an array of objects that include the order id and http status code for each status request.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PositionClosedResponse'
examples:
example-1:
value:
- symbol: TSLA
status: 200
body:
id: d1143025-89fc-4952-8936-db2409d899f3
client_order_id: 17dbfab4-cb86-4e0a-8fa6-f0606b0a9a4e
created_at: '2022-05-13T16:25:29.336330998Z'
updated_at: '2022-05-13T16:25:29.336330998Z'
submitted_at: '2022-05-13T16:25:29.335776073Z'
filled_at: null
expired_at: null
canceled_at: null
failed_at: null
replaced_at: null
replaced_by: null
replaces: null
asset_id: a4778bc8-fad1-47b7-87fe-d5cde10d43f4
symbol: TSLA
asset_class: us_equity
notional: null
qty: '4'
filled_qty: '0'
filled_avg_price: null
order_class: ''
order_type: market
type: market
side: sell
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
source: null
'500':
description: Failed to liquidate some positions
description: Closes (liquidates) all of the account’s open long and short positions. 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.
parameters:
- schema:
type: boolean
in: query
name: cancel_orders
description: If true is specified, cancel all open orders before liquidating all positions.
tags:
- Trading
/v1/trading/accounts/{account_id}/positions/{symbol_or_asset_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
- schema:
type: string
name: symbol_or_asset_id
in: path
required: true
description: 'The symbol or asset_id '
get:
summary: Get an Open Position for account by Symbol or AssetId
responses:
'200':
description: The requested Position object
content:
application/json:
schema:
$ref: '#/components/schemas/Position'
'404':
description: 'Account doesn''t have a position for this symbol or asset_id '
operationId: getPositionsForAccountBySymbol
description: Retrieves the account’s open position for the given symbol or asset_id.
tags:
- Trading
delete:
summary: Close a Position for an Account
operationId: closePositionForAccountBySymbol
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
description: Closes (liquidates) the account’s open position for the given symbol. Works for both long and short positions.
tags:
- Trading
parameters:
- schema:
type: string
in: query
name: qty
description: Optional the number of shares to liquidate. Can accept up to 9 decimal points. Cannot work with percentage
- schema:
type: string
in: query
description: percentage of position to liquidate. Must be between 0 and 100. Would only sell fractional if position is originally fractional. Can accept up to 9 decimal points. Cannot work with qty
name: percentage
/v1/trading/accounts/{account_id}/orders/{order_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
- $ref: '#/components/parameters/OrderID'
get:
summary: Retrieves a single order for the given order_id.
tags:
- Trading
description: Retrieves a single order for the given order_id.
responses:
'200':
description: The requested Order object
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getOrderForAccount
patch:
summary: Replaces a single order with updated parameters
tags:
- Trading
description: '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 in the market data api](https://alpaca.markets/docs/api-references/market-data-api/#order-updates).
While an order is being replaced, the account''s 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.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOrderRequest'
responses:
'200':
description: A new Order object with a new order_id
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'403':
description: Buying power or shares are not sufficient
'404':
$ref: '#/components/responses/NotFound'
operationId: replaceOrderForAccount
delete:
summary: Attempts to cancel an open order.
tags:
- Trading
description: 'Attempts to cancel an open order. If the order is no longer cancelable (for example if the status is "filled"), the server will respond with status 422, and reject the request.
Upon acceptance of the cancel request, it returns status 204.'
responses:
'204':
description: Success (No Content)
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: deleteOrderForAccount
/v1/trading/accounts/{account_id}/orders:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
parameters:
- name: status
in: query
description: Order status to be queried. open, closed or all. Defaults to open.
schema:
type: string
enum:
- open
- closed
- all
- name: limit
in: query
description: The maximum number of orders in response. Defaults to 50 and max is 500.
schema:
type: integer
example: 500
- $ref: '#/components/parameters/After'
- $ref: '#/components/parameters/Until'
- $ref: '#/components/parameters/Direction'
- schema:
type: boolean
in: query
name: nested
description: If true, the result will roll up multi-leg orders under the legs field of primary order.
- $ref: '#/components/parameters/Symbols'
summary: Retrieves a list of orders for the account, filtered by the supplied query parameters.
tags:
- Trading
description: 'Retrieves a list of orders for the account, filtered by the supplied query parameters.
Endpoint defaults to open orders if no parameters are provided.'
responses:
'200':
description: Retrieves a list of orders for the account, filtered by the supplied query parameters.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getAllOrdersForAccount
post:
summary: Create an order for an account.
tags:
- Trading
description: Create an order for an account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
operationId: createOrderForAccount
delete:
summary: Attempts to cancel all open orders. A response will be provided for each order that is attempted to be cancelled.
tags:
- Trading
description: Attempts to cancel all open orders. A response will be provided for each order that is attempted to be cancelled.
responses:
'207':
description: 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.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrderClosedResponse'
examples:
example-1:
value:
- id: 872994c5-0620-40ad-8ae0-f224b9948df5
status: 200
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: deleteAllOrdersForAccount
/v1/events/trades:
parameters: []
get:
summary: Subscribe to Trade Events (SSE)
tags:
- Trading
responses:
'200':
description: Connected. Events will now start streaming as long as you keep the connection open.
content:
text/event-stream:
schema:
type: array
items:
$ref: '#/components/schemas/TradeUpdateEvent'
parameters:
- name: since
in: query
schema:
type: string
format: date-time
description: 'Format: YYYY-MM-DD'
- name: until
in: query
schema:
type: string
format: date-time
description: 'Format: YYYY-MM-DD'
- name: since_id
in: query
schema:
type: integer
- name: until_id
in: query
schema:
type: integer
operationId: subscribeToTradeSSE
description: 'The Events API provides event push as well as historical queries via SSE (server sent events).
You can listen to events related to trade updates. Most market trades sent during market hours are filled instantly; you can listen to limit order updates through this endpoint.
Historical events are streamed immediately if queried, and updates are pushed as events occur.
Query Params Rules:
- `since` required if `until` specified
- `since_id` required if `until_id` specified
- `since` and `since_id` can’t be used at the same time
Behavior:
- if `since` or `since_id` not specified this will not return any historic data
- if `until` or `until_id` reached stream will end (status 200)
---
Note for people using the clients generated from this OAS spec. Currently OAS-3 doesn''t have full support for representing SSE style responses from an API, so if you are using a generated client and don''t specify a `since` and `until` there is a good chance the generated clients will hang waiting for the response to end.
If you require the streaming capabilities we recommend not using the generated clients for this specific usecase until the OAS-3 standards come to a consensus on how to represent this correcting in OAS-3.'
components:
schemas:
TimeInForce:
type: string
enum:
- day
- gtc
- opg
- cls
- ioc
- fok
example: gtc
UpdateOrderRequest:
type: object
title: OrderUpdateRequest
description: 'Represents the fields that are editable in an order replace/update call.
Note: client_order_id is currently not editable on its own, one of the other fields must be changed at the same time to effectively replace the order'
properties:
qty:
type: string
format: decimal
example: '4.2'
description: You can only patch full shares for now
time_in_force:
$ref: '#/components/schemas/TimeInForce'
limit_price:
type: string
format: decimal
example: '3.14'
description: Required if original order's `type` field was limit or stop_limit
stop_price:
type: string
format: decimal
example: '3.14'
description: Required if original order's `type` field was stop or stop_limit
trail:
type: string
format: decimal
example: '3.14'
description: The new value of the trail_price or trail_percent
client_order_id:
type: string
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
OrderStatus:
type: string
enum:
- new
- partially_filled
- filled
- done_for_day
- canceled
- expired
- replaced
- pending_cancel
- pending_replace
- accepted
- pending_new
- accepted_for_bidding
- stopped
- rejected
- suspended
- calculated
example: filled
Error:
title: Error
type: object
properties:
code:
type: number
message:
type: string
required:
- code
- message
OrderSide:
type: string
enum:
- buy
- sell
- buy_minus
- sell_plus
- sell_short
- sell_short_exempt
- undisclosed
- cross
- cross_short
example: buy
description: Represents what side of the transaction an order was on.
Position:
description: ''
type: object
x-examples:
example-1:
asset_id: 93f58d0b-6c53-432d-b8ce-2bad264dbd94
symbol: AAPL
exchange: NASDAQ
asset_class: us_equity
asset_marginable: false
qty: '4'
avg_entry_price: '172.08'
side: long
market_value: '688.32'
cost_basis: '688.32'
unrealized_pl: '0'
unrealized_plpc: '0'
unrealized_intraday_pl: '0'
unrealized_intraday_plpc: '0'
current_price: '172.08'
lastday_price: '168.88'
change_today: '0.0189483657034581'
properties:
asset_id:
type: string
example: 904837e3-3b76-47ec-b432-046db621571b
format: uuid
description: Asset ID
symbol:
type: string
example: AAPL
description: Asset symbol
exchange:
type: string
example: NASDAQ
description: Exchange name of the asset
asset_class:
$ref: '#/components/schemas/AssetClass'
asset_marginable:
type: boolean
description: Indicates if this asset is marginable
avg_entry_price:
type: string
example: '100.0'
description: Average entry price of the position
qty:
type: string
example: '5'
description: The number of shares
side:
type: string
example: long
enum:
- long
- short
market_value:
type: string
format: decimal
example: '600.0'
description: Total dollar amount of the position
cost_basis:
type: string
format: decimal
example: '500.0'
description: Total cost basis in dollar
unrealized_pl:
type: string
format: decimal
example: '100.0'
description: Unrealized profit/loss in dollars
unrealized_plpc:
type: string
format: decimal
example: '0.20'
description: Unrealized profit/loss percent (by a factor of 1)
unrealized_intraday_pl:
type: string
format: decimal
example: '10.0'
description: Unrealized profit/loss in dollars for the day
unrealized_intraday_plpc:
type: string
format: decimal
example: '0.0084'
description: Unrealized interday profit/loss percent (by a factor of 1)
current_price:
type: string
format: decimal
example: '120.0'
description: Current asset price per share
lastday_price:
type: string
format: decimal
example: '119.0'
description: Last day’s asset price per share based on the closing value of the last trading day
change_today:
type: string
format: decimal
example: '0.0084'
description: Percent change from last day price (by a factor of 1)
required:
- asset_id
- symbol
- exchange
- asset_class
- avg_entry_price
- qty
- side
- market_value
- cost_basis
- unrealized_pl
- unrealized_plpc
- unrealized_intraday_pl
- unrealized_intraday_plpc
- current_price
- lastday_price
- change_today
TradeUpdateEventType:
type: string
description: "**Common events**\n\nThese are the events that are the expected results of actions you may have taken by sending API requests.\n\nThe meaning of the `timestamp` field changes for each type; the meanings have been specified here for which types the\ntimestamp field will be present.\n\n- `new`: Sent when an order has been routed to exchanges for execution.\n- `fill`: Sent when your order has been completely filled.\n - `timestamp`: The time at which the order was filled.\n- `partial_fill`: Sent when a number of shares less than the total remaining quantity on your order has been filled.\n - `timestamp`: The time at which the shares were filled.\n- `canceled`: Sent when your requested cancellation of an order is processed.\n - `timestamp`: The time at which the order was canceled.\n- `expired`: Sent when an order has reached the end of its lifespan, as determined by the order’s time in force value.\n - `timestamp`: The time at which the order expired.\n- `done_for_day`: Sent when the order is done executing for the day, and will not receive further updates until the next trading day.\n- `replaced`: Sent when your requested replacement of an order is processed.\n - `timestamp`: The time at which the order was replaced.\n\n**Rarer events**\n\nThese are events that may rarely be sent due to unexpected circumstances on the exchanges. It is unlikely you will need to design your code around them, but you may still wish to account for the possibility that they will occur.\n\n- `rejected`: Sent when your order has been rejected.\n - `timestamp`: The time at which the rejection occurred.\n- `pending_new`: Sent when the order has been received by Alpaca and routed to the exchanges, but has not yet been accepted for execution.\n- `stopped`: Sent when your order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred.\n- `pending_cancel`: Sent when the order is awaiting cancellation. Most cancellations will occur without the order entering this state.\n- `pending_replace`: Sent when the order is awaiting replacement.\n- `calculated`: Sent when the order has been completed for the day - it is either `filled` or `done_for_day` - but remaining settlement calculations are still pending.\n- `suspended`: Sent when the order has been suspended and is not eligible for trading.\n- `order_replace_rejected`: Sent when the order replace has been rejected.\n- `order_cancel_rejected`: Sent when the order cancel has been rejected.\n"
enum:
- new
- fill
- partial_fill
- canceled
- expired
- done_for_day
- replaced
- rejected
- pending_new
- stopped
- pending_cancel
- pending_replace
- calculated
- suspended
- order_replace_rejected
- order_cancel_rejected
OrderType:
type: string
enum:
- market
- limit
- stop
- stop_limit
- trailing_stop
example: stop
CreateOrderRequest:
type: object
description: ''
properties:
symbol:
type: string
example: AAPL
description: Symbol or asset ID to identify the asset to trade
qty:
type: string
format: decimal
example: '4.124'
description: Number of shares to trade. Can be fractionable for only market and day order types.
notional:
type: string
format: decimal
example: '3'
description: Dollar amount to trade. Cannot work with qty. Can only work for market order types and time_in_force = day.
side:
$ref: '#/components/schemas/OrderSide'
type:
$ref: '#/components/schemas/OrderType'
time_in_force:
$ref: '#/components/schemas/TimeInForce'
limit_price:
type: string
format: decimal
example: '3.14'
description: Required if type is limit or stop_limit
stop_price:
type: string
format: decimal
example: '3.14'
description: Required if type is stop or stop_limit
trail_price:
type: string
format: decimal
example: '3.14'
description: If type is trailing_stop, then one of trail_price or trail_percent is required
trail_percent:
type: string
format: decimal
example: '5.0'
description: If type is trailing_stop, then one of trail_price or trail_percent is required
extended_hours:
type: boolean
example: false
description: 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:
type: string
example: eb9e2aaa-f71a-4f51-b5b4-52a6c565dad4
description: A unique identifier for the order. Automatically generated if not sent. (<= 48 characters)
maxLength: 48
order_class:
$ref: '#/components/schemas/OrderClass'
take_profit:
type: object
description: Takes in a string/number value for limit_price
properties:
limit_price:
type: string
format: decimal
example: '3.14'
stop_loss:
description: Takes in a string/number values for stop_price and limit_price
type: object
properties:
stop_price:
type: string
format: decimal
example: '3.14'
limit_price:
type: string
format: decimal
example: '3.14'
commission:
type: string
format: decimal
example: '1.0'
description: The commission you want to collect from the user.
required:
- symbol
- side
- type
- time_in_force
PositionClosedResponse:
title: PositionClosedResponse
type: object
description: 'Represents the result of asking the api to close a position.
`body` is the Order used to close out the position.'
x-examples:
example-1:
symbol: AAPL
status: 200
body:
id: f7f25e89-939a-4587-aaf6-414a6b3c341d
client_order_id: 52f8574c-96d5-49b6-94c1-2570a268434e
created_at: '2022-02-04T16:53:29.53427917Z'
updated_at: '2022-02-04T16:53:29.53427917Z'
submitted_at: '2022-02-04T16:53:29.533738219Z'
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: null
qty: '2'
filled_qty: '0'
filled_avg_price: null
order_class: ''
order_type: market
type: market
side: sell
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
commision: '1.0'
properties:
symbol:
type: string
description: Symbol name of the asset
status:
type: integer
description: Http status code for the attempt to close this position
body:
$ref: '#/components/schemas/Order'
required:
- symbol
- status
OrderClass:
type: string
enum:
- simple
- bracket
- oco
- oto
example: bracket
OrderClosedResponse:
title: OrderClosedResponse
type: object
description: 'Represents the result of asking the api to cancel an Order.
'
x-examples: {}
properties:
id:
type: string
description: UUID of the order that was canceled
format: uuid
status:
type: integer
description: Http status code for the attempt to close this Order
body:
$ref: '#/components/schemas/Order'
required:
- id
- status
Order:
type: object
properties:
id:
type: string
format: uuid
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
client_order_id:
type: string
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
created_at:
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
updated_at:
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
submitted_at:
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
filled_at:
nullable: true
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
expired_at:
nullable: true
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
canceled_at:
nullable: true
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
failed_at:
nullable: true
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
replaced_at:
nullable: true
type: string
format: date-time
example: '2021-03-16T18:38:01.942282Z'
replaced_by:
nullable: true
type: string
format: uuid
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
replaces:
nullable: true
type: string
format: uuid
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
asset_id:
type: string
format: uuid
example: 61e69015-8549-4bfd-b9c3-01e75843f47d
symbol:
type: string
example: AALP
asset_class:
$ref: '#/components/schemas/AssetClass'
notional:
nullable: true
type: string
format: decimal
example: '4.2'
qty:
nullable: true
type: string
format: decimal
example: '4.2'
filled_qty:
type: string
format: decimal
example: '4.2'
filled_avg_price:
nullable: true
type: string
format: decimal
example: '4.2'
order_class:
$ref: '#/components/schemas/OrderClass'
order_type:
$ref: '#/components/schemas/OrderType'
type:
$ref: '#/components/schemas/OrderType'
side:
$ref: '#/components/schemas/OrderSide'
time_in_force:
$ref: '#/components/schemas/TimeInForce'
limit_price:
nullable: true
type: string
format: decimal
example: '3.14'
stop_price:
nullable: true
type: string
format: decimal
example: '3.14'
status:
$ref: '#/components/schemas/OrderStatus'
extended_hours:
type: boolean
example: true
legs:
nullable: true
type: array
items:
$ref: '#/components/schemas/Order'
trail_price:
nullable: true
type: string
format: decimal
example: '3.14'
trail_percent:
nullable: true
type: string
format: decimal
example: '5.0'
hwm:
nullable: true
type: string
format: decimal
example: '3.14'
commission:
type: string
format: decimal
example: '3.14'
required:
- id
- symbol
AssetClass:
type: string
enum:
- us_equity
- crypto
TradeUpdateEvent:
description: Represents an update to an order/trade, sent over the events streaming api.
type: object
title: TradeUpdateEvent
x-examples:
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alpaca/refs/heads/main/openapi/alpaca-trading-api-openapi.yml