feat(trading): align option contract schemas

alpaca/trading/enums.py

@@ -399,6 +399,45 @@ class ExerciseStyle(str, Enum):
     EUROPEAN = "european"
 
 
+class OptionDeliverableType(str, Enum):
+    """Type of deliverable for an option contract (OptionDeliverable)."""
+
+    CASH = "cash"
+    EQUITY = "equity"
+
+
+class OptionDeliverableSettlementType(str, Enum):
+    """
+    Settlement timing for an option deliverable (OptionDeliverable).
+
+    Values use ``T_PLUS_N`` naming because the spec values (``T+0`` … ``T+5``)
+    contain a ``+`` character that is not valid in Python identifiers.
+    """
+
+    T_PLUS_0 = "T+0"
+    T_PLUS_1 = "T+1"
+    T_PLUS_2 = "T+2"
+    T_PLUS_3 = "T+3"
+    T_PLUS_4 = "T+4"
+    T_PLUS_5 = "T+5"
+
+
+class OptionDeliverableSettlementMethod(str, Enum):
+    """
+    Settlement method for an option deliverable (OptionDeliverable).
+
+    - BTOB: Broker to Broker
+    - CADF: Cash Difference
+    - CAFX: Cash Fixed
+    - CCC: Correspondent Clearing Corp
+    """
+
+    BTOB = "BTOB"
+    CADF = "CADF"
+    CAFX = "CAFX"
+    CCC = "CCC"
+
+
 class ActivityCategory(str, Enum):
     """
     Represents the category of an Activity

alpaca/trading/models.py

@@ -9,6 +9,9 @@
     ContractType,
     DTBPCheck,
     ExerciseStyle,
+    OptionDeliverableSettlementMethod,
+    OptionDeliverableSettlementType,
+    OptionDeliverableType,
     OrderStatus,
     OrderType,
     OrderClass,
@@ -651,7 +654,7 @@ class OptionContract(BaseModel):
     Represents an option contract.
 
     Attributes:
-        id (str): The unique identifier of the option contract.
+        id (uuid): The unique identifier of the option contract.
         symbol (str): The symbol representing the option contract.
         name (str): The name of the option contract.
         status (AssetStatus): The status of the option contract.
@@ -662,31 +665,79 @@ class OptionContract(BaseModel):
         underlying_asset_id (UUID): The unique identifier of the underlying asset.
         type (ContractType): The type of the option contract.
         style (ExerciseStyle): The style of the option contract.
-        strike_price (float): The strike price of the option contract.
+        strike_price (Union[str, float]): The strike price of the option contract.
+        multiplier (Union[str, float]): The multiplier of the option contract is crucial for calculating both the trade premium and the extended strike price. In standard contracts, the multiplier is always set to 100.
         size (str): The size of the option contract. Usually contracts have size=100.
         open_interest (Optional[str]): The open interest of the option contract.
         open_interest_date (Optional[date]): The date of the open interest data.
         close_price (Optional[str]): The close price of the option contract.
         close_price_date (Optional[date]): The date of the close price data.
+        deliverables (Optional[List[OptionDeliverable]]): Represents the deliverables tied to the option contract. While standard contracts entail a single deliverable, non-standard ones can encompass multiple deliverables, each potentially customized with distinct parameters.
+
+    Note:
+        This model retains the intentional breaking schema alignments approved in
+        PR #698: ``id`` is parsed as a UUID, ``strike_price`` accepts strings or
+        floats, and ``multiplier`` is required.
     """
 
-    id: str
+    id: UUID
     symbol: str
     name: str
     status: AssetStatus
     tradable: bool
     expiration_date: date
-    root_symbol: str
+    root_symbol: Optional[str]
     underlying_symbol: str
     underlying_asset_id: UUID
     type: ContractType
     style: ExerciseStyle
-    strike_price: float
+    strike_price: Union[str, float]
+    multiplier: Union[str, float]
     size: str
     open_interest: Optional[str] = None
     open_interest_date: Optional[date] = None
     close_price: Optional[str] = None
     close_price_date: Optional[date] = None
+    deliverables: Optional[List["OptionDeliverable"]] = None
+
+
+class OptionDeliverable(BaseModel):
+    """
+    Describes what is delivered when an option contract is exercised or assigned.
+
+    Attributes:
+        type (OptionDeliverableType): Whether the deliverable is cash or equity.
+        symbol (str): Symbol of the deliverable asset.
+        amount (Optional[str]): Deliverable amount (100 for standard contracts; may be
+            null if delayed settlement is pending determination).
+        allocation_percentage (str): Cost allocation percentage used to determine the
+            cost basis of equity shares received from exercise.
+        settlement_type (OptionDeliverableSettlementType): Settlement timing relative to
+            the exercise/assignment date.
+        settlement_method (OptionDeliverableSettlementMethod): Settlement method (BTOB,
+            CADF, CAFX, or CCC).
+        delayed_settlement (bool): If ``True``, settlement of the deliverable is delayed.
+        asset_id (Optional[UUID]): Unique identifier of the deliverable asset. Not
+            returned for cash deliverables.
+    """
+
+    type: OptionDeliverableType
+    symbol: str
+    amount: Optional[str] = None
+    allocation_percentage: str
+    settlement_type: OptionDeliverableSettlementType
+    settlement_method: OptionDeliverableSettlementMethod
+    delayed_settlement: bool
+    asset_id: Optional[UUID] = None
+
+    @model_validator(mode="after")
+    def validate_amount_for_settlement(self) -> "OptionDeliverable":
+        if self.amount is None and not self.delayed_settlement:
+            raise ValueError("amount may be None only when delayed_settlement is True")
+        return self
+
+
+OptionContract.model_rebuild()
 
 
 class OptionContractsResponse(BaseModel):

alpaca/trading/requests.py

@@ -689,30 +689,34 @@ class GetOptionContractsRequest(NonEmptyRequest):
 
     Attributes:
         underlying_symbols (Optional[List[str]]): The underlying symbols for the option contracts to be returned. (e.g. ["AAPL", "SPY"])
+        show_deliverables (Optional[bool]): Include deliverables array in the response.
         status (Optional[AssetStatus]): The status of the asset.
         expiration_date (Optional[Union[date, str]]): The expiration date of the option contract. (YYYY-MM-DD)
         expiration_date_gte (Optional[Union[date, str]]): The expiration date of the option contract greater than or equal to. (YYYY-MM-DD)
         expiration_date_lte (Optional[Union[date, str]]): The expiration date of the option contract less than or equal to. (YYYY-MM-DD)
         root_symbol (Optional[str]): The option root symbol.
         type (Optional[ContractType]): The option contract type.
         style (Optional[ExerciseStyle]): The option contract style.
-        strike_price_gte (Optional[str]): The option contract strike price greater than or equal to.
-        strike_price_lte (Optional[str]): The option contract strike price less than or equal to.
+        strike_price_gte (Optional[float]): The option contract strike price greater than or equal to.
+        strike_price_lte (Optional[float]): The option contract strike price less than or equal to.
         limit (Optional[int]): The number of contracts to limit per page (default=100, max=10000).
+        ppind (Optional[bool]): The ppind(Penny Program Indicator) field indicates whether an option contract is eligible for penny price increments, with `true` meaning it is part of the Penny Program and `false` meaning it is not.
         page_token (Optional[str]): 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.
     """
 
     underlying_symbols: Optional[List[str]] = None
+    show_deliverables: Optional[bool] = True
     status: Optional[AssetStatus] = AssetStatus.ACTIVE
     expiration_date: Optional[Union[date, str]] = None
     expiration_date_gte: Optional[Union[date, str]] = None
     expiration_date_lte: Optional[Union[date, str]] = None
     root_symbol: Optional[str] = None
     type: Optional[ContractType] = None
     style: Optional[ExerciseStyle] = None
-    strike_price_gte: Optional[str] = None
-    strike_price_lte: Optional[str] = None
+    strike_price_gte: Optional[float] = None
+    strike_price_lte: Optional[float] = None
 
     limit: Optional[int] = None
+    ppind: Optional[bool] = None
     page_token: Optional[str] = None

docs/api_reference/trading/enums.rst

@@ -120,3 +120,21 @@ PositionIntent
 ----------------------
 
 .. autoenum:: alpaca.trading.enums.PositionIntent
+
+
+OptionDeliverableType
+---------------------
+
+.. autoenum:: alpaca.trading.enums.OptionDeliverableType
+
+
+OptionDeliverableSettlementType
+-------------------------------
+
+.. autoenum:: alpaca.trading.enums.OptionDeliverableSettlementType
+
+
+OptionDeliverableSettlementMethod
+---------------------------------
+
+.. autoenum:: alpaca.trading.enums.OptionDeliverableSettlementMethod

docs/api_reference/trading/models.rst

@@ -92,6 +92,12 @@ OptionContract
 .. autoclass:: alpaca.trading.models.OptionContract
 
 
+OptionDeliverable
+-----------------
+
+.. autoclass:: alpaca.trading.models.OptionDeliverable
+
+
 OptionContractsResponse
 -----------------------