Requests

OrderRequest

class alpaca.trading.requests.OrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None)

A base class for requests for creating an order. You probably shouldn’t directly use this class when submitting an order. Instead, use one of the order type specific classes.

symbol

The symbol identifier for the asset being traded. Required for all order classes other than mleg.

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders. Required for mleg order class.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset. Either side or position_intent is required for all order classes other than mleg.

Type:

Optional[OrderSide]

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order If specified (must contain at least 2 but no more than 4 legs for options). Otherwise, for equities, a list of individual orders.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

MarketOrderRequest

class alpaca.trading.requests.MarketOrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None)

Used to submit a market order.

symbol

The symbol identifier for the asset being traded. Required for all order classes other than mleg.

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset. Required for all order classes other than mleg.

Type:

OrderSide

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order. At most 4 legs are allowed for options.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

StopOrderRequest

class alpaca.trading.requests.StopOrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None, stop_price: float)

Used to submit a stop order.

symbol

The symbol identifier for the asset being traded

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset.

Type:

OrderSide

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order. At most 4 legs are allowed for options.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

stop_price

The price at which the stop order is converted to a market order or a stop limit order is converted to a limit order.

Type:

float

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

LimitOrderRequest

class alpaca.trading.requests.LimitOrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None, limit_price: float | None = None)

Used to submit a limit order.

symbol

The symbol identifier for the asset being traded

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset.

Type:

OrderSide

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order. At most 4 legs are allowed for options.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

limit_price

The worst fill price for a limit or stop limit order. This field is optional at the model-field level because the requirement depends on the order class. It is required for simple, bracket, oto, and mleg limit orders, but may be omitted for oco orders when the exit limit price is supplied via take_profit.limit_price. For the mleg order class, this is specified such that a positive value indicates a debit (representing a cost or payment to be made) while a negative value signifies a credit (reflecting an amount to be received).

Type:

Optional[float]

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

StopLimitOrderRequest

class alpaca.trading.requests.StopLimitOrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None, stop_price: float, limit_price: float)

Used to submit a stop limit order.

symbol

The symbol identifier for the asset being traded

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset.

Type:

OrderSide

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order. At most 4 legs are allowed for options.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

stop_price

The price at which the stop order is converted to a market order or a stop limit order is converted to a limit order.

Type:

float

limit_price

The worst fill price for a limit or stop limit order. For the mleg order class, this is specified such that a positive value indicates a debit (representing a cost or payment to be made) while a negative value signifies a credit (reflecting an amount to be received).

Type:

float

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

TrailingStopOrderRequest

class alpaca.trading.requests.TrailingStopOrderRequest(*, symbol: str | None = None, qty: float | None = None, notional: float | None = None, side: OrderSide | None = None, type: OrderType, time_in_force: TimeInForce, order_class: OrderClass | None = None, extended_hours: bool | None = None, client_order_id: str | None = None, legs: List[OptionLegRequest] | None = None, take_profit: TakeProfitRequest | None = None, stop_loss: StopLossRequest | None = None, position_intent: PositionIntent | None = None, trail_price: float | None = None, trail_percent: float | None = None)

Used to submit a trailing stop order.

symbol

The symbol identifier for the asset being traded

Type:

str

qty

The number of shares to trade. Fractional qty for stocks only with market orders.

Type:

Optional[float]

notional

The base currency value of the shares to trade. For stocks, only works with MarketOrders. Does not work with qty.

Type:

Optional[float]

side

Whether the order will buy or sell the asset.

Type:

OrderSide

type

The execution logic type of the order (market, limit, etc).

Type:

OrderType

time_in_force

The expiration logic of the order.

Type:

TimeInForce

extended_hours

Whether the order can be executed during extended hours.

Type:

Optional[bool]

client_order_id

A string to identify which client submitted the order.

Type:

Optional[str]

order_class

The class of the order. Simple orders have no other legs.

Type:

Optional[OrderClass]

legs

For multi-leg option orders, the legs of the order. At most 4 legs are allowed for options.

Type:

Optional[List[OptionLegRequest]]

take_profit

For orders with multiple legs, an order to exit a profitable trade.

Type:

Optional[TakeProfitRequest]

stop_loss

For orders with multiple legs, an order to exit a losing trade.

Type:

Optional[StopLossRequest]

trail_price

The absolute price difference by which the trailing stop will trail.

Type:

Optional[float]

trail_percent

The percent price difference by which the trailing stop will trail.

Type:

Optional[float]

position_intent

An enum to indicate the desired position strategy: BTO, BTC, STO, STC.

Type:

Optional[PositionIntent]

GetOrdersRequest

class alpaca.trading.requests.GetOrdersRequest(*, status: QueryOrderStatus | None = None, limit: int | None = None, after: datetime | None = None, until: datetime | None = None, direction: Sort | None = None, nested: bool | None = None, side: OrderSide | None = None, symbols: List[str] | None = None)

Contains data for submitting a request to retrieve orders.

status

Order status to be queried. open, closed or all. Defaults to open. Not same as OrderStatus property of Order.

Type:

Optional[QueryOrderStatus]

limit

The maximum number of orders in response. Defaults to 50 and max is 500.

Type:

Optional[int]

after

The response will include only ones submitted after this timestamp.

Type:

Optional[datetime]

until

The response will include only ones submitted until this timestamp.

Type:

Optional[datetime]

direction

The chronological order of response based on the submission time. asc or desc. Defaults to desc.

Type:

Optional[Sort]

nested

If true, the result will roll up multi-leg orders under the legs field of primary order.

Type:

Optional[bool]

side

Filters down to orders that have a matching side field set.

Type:

Optional[OrderSide]

symbols

List of symbols to filter by.

Type:

Optional[List[str]]

GetOrderByIdRequest

class alpaca.trading.requests.GetOrderByIdRequest(*, nested: bool)

Contains data for submitting a request to retrieve a single order by its order id.

nested

If true, the result will roll up multi-leg orders under the legs field of primary order.

Type:

bool

ReplaceOrderRequest

class alpaca.trading.requests.ReplaceOrderRequest(*, qty: int | None = None, time_in_force: TimeInForce | None = None, limit_price: float | None = None, stop_price: float | None = None, trail: float | None = None, client_order_id: str | None = None)

Contains data for submitting a request to replace an order.

qty

Number of shares to trade

Type:

Optional[int]

time_in_force

The new expiration logic of the order.

Type:

Optional[TimeInForce]

limit_price

Required if type of order being replaced is limit or stop_limit

Type:

Optional[float]

stop_price

Required if type of order being replaced is stop or stop_limit

Type:

Optional[float]

trail

The new value of the trail_price or trail_percent value (works only for type=“trailing_stop”)

Type:

Optional[float]

client_order_id

A unique identifier for the order.

Type:

Optional[str]

TakeProfitRequest

class alpaca.trading.requests.TakeProfitRequest(*, limit_price: float)

Used for providing take profit details for a bracket order.

limit_price

The execution price for exiting a profitable trade.

Type:

float

StopLossRequest

class alpaca.trading.requests.StopLossRequest(*, stop_price: float, limit_price: float | None = None)

Used for providing stop loss details for a bracket order.

stop_price

The price at which the stop loss is triggered.

Type:

float

limit_price

The execution price for exiting a losing trade. If not provided, the stop loss will execute as a market order.

Type:

Optional[float]

GetOptionContractsRequest

class alpaca.trading.requests.GetOptionContractsRequest(*, underlying_symbols: List[str] | None = None, status: AssetStatus | None = AssetStatus.ACTIVE, expiration_date: date | str | None = None, expiration_date_gte: date | str | None = None, expiration_date_lte: date | str | None = None, root_symbol: str | None = None, type: ContractType | None = None, style: ExerciseStyle | None = None, strike_price_gte: str | None = None, strike_price_lte: str | None = None, show_deliverables: bool | None = None, ppind: bool | None = None, limit: int | None = None, page_token: str | None = None)

Used to fetch option contracts for a given underlying symbol.

underlying_symbols

The underlying symbols for the option contracts to be returned. (e.g. [“AAPL”, “SPY”])

Type:

Optional[List[str]]

status

The status of the asset.

Type:

Optional[AssetStatus]

expiration_date

The expiration date of the option contract. (YYYY-MM-DD)

Type:

Optional[Union[date, str]]

expiration_date_gte

The expiration date of the option contract greater than or equal to. (YYYY-MM-DD)

Type:

Optional[Union[date, str]]

expiration_date_lte

The expiration date of the option contract less than or equal to. (YYYY-MM-DD)

Type:

Optional[Union[date, str]]

root_symbol

The option root symbol.

Type:

Optional[str]

type

The option contract type.

Type:

Optional[ContractType]

style

The option contract style.

Type:

Optional[ExerciseStyle]

strike_price_gte

The option contract strike price greater than or equal to.

Type:

Optional[str]

strike_price_lte

The option contract strike price less than or equal to.

Type:

Optional[str]

show_deliverables

Include each contract’s deliverables. The list endpoint omits them unless this is true.

Type:

Optional[bool]

ppind

Filter by Penny Program eligibility. True returns only contracts eligible for penny price increments.

Type:

Optional[bool]

limit

The number of contracts to limit per page (default=100, max=10000).

Type:

Optional[int]

page_token

Pagination token to continue from. The value to pass here is returned in specific requests when more data is available than the request limit allows.

Type:

Optional[str]

OptionLegRequest

class alpaca.trading.requests.OptionLegRequest(*, symbol: str, ratio_qty: float, side: OrderSide | None = None, position_intent: PositionIntent | None = None)

Used for providing details for a leg of a multi-leg order.

symbol

The symbol identifier for the asset being traded.

Type:

str

ratio_qty

The proportional quantity of this leg in relation to the overall multi-leg order quantity.

Type:

float

side

Represents the side this order was on.

Type:

Optional[OrderSide]

position_intent

Represents the position strategy for this leg.

Type:

Optional[PositionIntent]

ClosePositionRequest

class alpaca.trading.requests.ClosePositionRequest(*, qty: str | None = None, percentage: str | None = None)

qty

The number of shares to liquidate.

Type:

str

percentage

The percentage of shares to liquidate.

Type:

str

GetAssetsRequest

class alpaca.trading.requests.GetAssetsRequest(*, status: AssetStatus | None = None, asset_class: AssetClass | None = None, exchange: AssetExchange | None = None, attributes: str | None = None)

When querying for available assets, this model provides the parameters that can be filtered by.

status

The active status of the asset.

Type:

Optional[AssetStatus]

asset_class

The type of asset (i.e. us_equity, crypto).

Type:

Optional[AssetClass]

exchange

The exchange the asset trades on.

Type:

Optional[AssetExchange]

attributes

Comma separated values to query for more than one attribute.

Type:

Optional[str]

GetPortfolioHistoryRequest

class alpaca.trading.requests.GetPortfolioHistoryRequest(*, period: str | None = None, timeframe: str | None = None, intraday_reporting: str | None = None, start: datetime | None = None, pnl_reset: str | None = None, end: datetime | None = None, date_end: date | None = None, extended_hours: bool | None = None, cashflow_types: str | None = None)

period

The duration of the data in number + unit, such as 1D. unit can be D for day, W for week, M for month and A for year. Defaults to 1M.

Type:

Optional[str]

timeframe

The resolution of time window. 1Min, 5Min, 15Min, 1H, or 1D. If omitted, 1Min for less than 7 days period, 15Min for less than 30 days, or otherwise 1D.

Type:

Optional[str]

intraday_reporting

this specfies which timestamps to return data points

Type:

Optional[str]

start

The timestamp the data is returned starting from in RFC3339 format (including timezone specification).

Type:

Optional[datetime]

pnl_reset

efines how we are calculating the baseline values for Profit And Loss (pnl) for queries with timeframe less than 1D (intraday queries).

Type:

Optional[str]

end

The timestamp the data is returned up to in RFC3339 format (including timezone specification).

Type:

Optional[datetime]

date_end

The date the data is returned up to. Defaults to the current market date (rolls over at the market open if extended_hours is false, otherwise at 7am ET).

Type:

Optional[date]

extended_hours

If true, include extended hours in the result. This is effective only for timeframe less than 1D.

Type:

Optional[bool]

cashflow_types

The cashflow activities to include in the report

Type:

Optional[str]

GetCalendarRequest

class alpaca.trading.requests.GetCalendarRequest(*, start: date | None = None, end: date | None = None, date_type: CalendarDateType | None = None)

Represents the optional filtering you can do when requesting a Calendar object.

start

Inclusive range start. Date-time strings are accepted.

Type:

Optional[date]

end

Inclusive range end. Date-time strings are accepted.

Type:

Optional[date]

date_type

TRADING or SETTLEMENT.

Type:

Optional[CalendarDateType]

CreateWatchlistRequest

class alpaca.trading.requests.CreateWatchlistRequest(*, name: str, symbols: List[str])

Represents the fields you can specify when creating a Watchlist

name

Name of the Watchlist

Type:

str

symbols

Symbols of Assets to watch

Type:

List[str]

UpdateWatchlistRequest

class alpaca.trading.requests.UpdateWatchlistRequest(*, name: str | None = None, symbols: List[str] | None = None)

Represents the fields you can specify when updating a Watchlist

name

Name of the Watchlist

Type:

Optional[str]

symbols

Symbols of Assets to watch

Type:

Optional[List[str]]

CancelOrderResponse

class alpaca.trading.requests.CancelOrderResponse(*, id: UUID, status: int, body: Dict[str, Any] | None = None)

Data returned after requesting to cancel an order. It contains the cancel status of an order.

id

The order id

Type:

UUID

status

The HTTP status returned after attempting to cancel the order.

Type:

int

body

an error description

Type:

Dict[str, Any]

GetCorporateAnnouncementsRequest

class alpaca.trading.requests.GetCorporateAnnouncementsRequest(*, ca_types: List[CorporateActionType], since: date, until: date, symbol: str | None = None, cusip: str | None = None, date_type: CorporateActionDateType | None = None)

Contains parameters for querying corporate action data. .. attribute:: ca_types

A list of corporate action types.

type:

List[CorporateActionType]

since

The start (inclusive) of the date range when searching corporate action announcements. The date range is limited to 90 days.

Type:

date

until

The end (inclusive) of the date range when searching corporate action announcements. The date range is limited to 90 days.

Type:

date

symbol

The symbol of the company initiating the announcement.

Type:

Optional[str]

cusip

The CUSIP of the company initiating the announcement.

Type:

Optional[str]

date_type

The date type for the announcement.

Type:

Optional[CorporateActionDateType]