py_alpaca_api.stock.trades

Exceptions

APIRequestError	Raised when an API request fails.
ValidationError	Raised when input validation fails.

Classes

Requests
TradeModel	Model for individual stock trade data.
TradesResponse	Response model for trades endpoint with pagination.
Trades

Functions

trade_class_from_dict(→ TradeModel)

Create TradeModel from API response dictionary.

Module Contents

exception py_alpaca_api.stock.trades.APIRequestError(status_code: int | None = None, message: str = '')

Bases: PyAlpacaAPIError

Raised when an API request fails.

exception py_alpaca_api.stock.trades.ValidationError

Bases: PyAlpacaAPIError

Raised when input validation fails.

class py_alpaca_api.stock.trades.Requests

request(method: str, url: str, headers: dict[str, str] | None = None, params: dict[str, str | bool | float | int] | None = None, json: dict[str, Any] | None = None, raw_response: bool = False)

Execute HTTP request with retry logic.

Parameters:

• method – A string representing the HTTP method to be used in the request.

• url – A string representing the URL to send the request to.

• headers – An optional dictionary containing the headers for the request.

• params – An optional dictionary containing the query parameters for the request.

• json – An optional dictionary containing the JSON payload for the request.

• raw_response – If True, return the raw response object without status checks. Defaults to False.

Returns:

The response object returned by the server.

Raises:

APIRequestError – If the response status code is not one of the acceptable statuses (200, 204, 207) and raw_response is False.

class py_alpaca_api.stock.trades.TradeModel

Model for individual stock trade data.

timestamp: str

symbol: str

exchange: str

price: float

size: int

conditions: list[str] | None

id: int

tape: str

class py_alpaca_api.stock.trades.TradesResponse

Response model for trades endpoint with pagination.

trades: list[TradeModel]

symbol: str

next_page_token: str | None = None

py_alpaca_api.stock.trades.trade_class_from_dict(data: dict[str, Any], symbol: str | None = None) → TradeModel

Create TradeModel from API response dictionary.

Parameters:

• data – Dictionary containing trade data from API

• symbol – Optional symbol to use if not in data

Returns:

TradeModel instance

class py_alpaca_api.stock.trades.Trades(headers: dict[str, str])

get_trades(symbol: str, start: str, end: str, limit: int = 1000, feed: Literal['iex', 'sip', 'otc'] | None = None, page_token: str | None = None, asof: str | None = None) → py_alpaca_api.models.trade_model.TradesResponse

Retrieve historical trades for a symbol.

Parameters:

• symbol – The stock symbol to retrieve trades for

• start – Start time in RFC-3339 format (YYYY-MM-DDTHH:MM:SSZ)

• end – End time in RFC-3339 format (YYYY-MM-DDTHH:MM:SSZ)

• limit – Number of trades to return (1-10000, default 1000)

• feed – Data feed to use (iex, sip, otc)

• page_token – Token for pagination

• asof – As-of time for historical data in RFC-3339 format

Returns:

TradesResponse with list of trades and pagination token

Raises:

• ValidationError – If parameters are invalid

• APIRequestError – If the API request fails

get_latest_trade(symbol: str, feed: Literal['iex', 'sip', 'otc'] | None = None, asof: str | None = None) → py_alpaca_api.models.trade_model.TradeModel

Get the latest trade for a symbol.

Parameters:

• symbol – The stock symbol to retrieve latest trade for

• feed – Data feed to use (iex, sip, otc)

• asof – As-of time for historical data in RFC-3339 format

Returns:

TradeModel with the latest trade data

Raises:

• ValidationError – If symbol is invalid

• APIRequestError – If the API request fails

get_trades_multi(symbols: list[str], start: str, end: str, limit: int = 1000, feed: Literal['iex', 'sip', 'otc'] | None = None, page_token: str | None = None, asof: str | None = None) → dict[str, py_alpaca_api.models.trade_model.TradesResponse]

Retrieve historical trades for multiple symbols.

Parameters:

• symbols – List of stock symbols (max 100)

• start – Start time in RFC-3339 format

• end – End time in RFC-3339 format

• limit – Number of trades per symbol (1-10000, default 1000)

• feed – Data feed to use

• page_token – Token for pagination

• asof – As-of time for historical data

Returns:

Dictionary mapping symbols to TradesResponse objects

Raises:

• ValidationError – If parameters are invalid

• APIRequestError – If the API request fails

get_latest_trades_multi(symbols: list[str], feed: Literal['iex', 'sip', 'otc'] | None = None, asof: str | None = None) → dict[str, py_alpaca_api.models.trade_model.TradeModel]

Get latest trades for multiple symbols.

Parameters:

• symbols – List of stock symbols (max 100)

• feed – Data feed to use

• asof – As-of time for historical data

Returns:

Dictionary mapping symbols to their latest TradeModel

Raises:

• ValidationError – If parameters are invalid

• APIRequestError – If the API request fails

get_all_trades(symbol: str, start: str, end: str, feed: Literal['iex', 'sip', 'otc'] | None = None, asof: str | None = None) → list[py_alpaca_api.models.trade_model.TradeModel]

Retrieve all trades for a symbol with automatic pagination.

Parameters:

• symbol – The stock symbol

• start – Start time in RFC-3339 format

• end – End time in RFC-3339 format

• feed – Data feed to use

• asof – As-of time for historical data

Returns:

List of all TradeModel objects across all pages

Raises:

• ValidationError – If parameters are invalid

• APIRequestError – If the API request fails