ctrader-api-client 0.1.0__py3-none-any.whl

ctrader_api_client/models/requests.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from ctrader_api_client.enums import OrderSide, OrderType, StopTriggerMethod, TimeInForce
+
+from .._internal.proto import (
+    ProtoOAAmendOrderReq,
+    ProtoOAAmendPositionSLTPReq,
+    ProtoOAClosePositionReq,
+    ProtoOANewOrderReq,
+    ProtoOAOrderTriggerMethod,
+    ProtoOAOrderType,
+    ProtoOAPayloadType,
+    ProtoOATimeInForce,
+    ProtoOATradeSide,
+)
+from ._base import FrozenModel
+
+
+# Reverse mappings for to_proto conversions
+
+_ORDER_TYPE_TO_PROTO: dict[OrderType, int] = {
+    OrderType.MARKET: ProtoOAOrderType.MARKET,
+    OrderType.LIMIT: ProtoOAOrderType.LIMIT,
+    OrderType.STOP: ProtoOAOrderType.STOP,
+    OrderType.STOP_LOSS_TAKE_PROFIT: ProtoOAOrderType.STOP_LOSS_TAKE_PROFIT,
+    OrderType.MARKET_RANGE: ProtoOAOrderType.MARKET_RANGE,
+    OrderType.STOP_LIMIT: ProtoOAOrderType.STOP_LIMIT,
+}
+
+_TIME_IN_FORCE_TO_PROTO: dict[TimeInForce, int] = {
+    TimeInForce.GOOD_TILL_DATE: ProtoOATimeInForce.GOOD_TILL_DATE,
+    TimeInForce.GOOD_TILL_CANCEL: ProtoOATimeInForce.GOOD_TILL_CANCEL,
+    TimeInForce.IMMEDIATE_OR_CANCEL: ProtoOATimeInForce.IMMEDIATE_OR_CANCEL,
+    TimeInForce.FILL_OR_KILL: ProtoOATimeInForce.FILL_OR_KILL,
+    TimeInForce.MARKET_ON_OPEN: ProtoOATimeInForce.MARKET_ON_OPEN,
+}
+
+_TRIGGER_TO_PROTO: dict[StopTriggerMethod, int] = {
+    StopTriggerMethod.TRADE: ProtoOAOrderTriggerMethod.TRADE,
+    StopTriggerMethod.OPPOSITE: ProtoOAOrderTriggerMethod.OPPOSITE,
+    StopTriggerMethod.DOUBLE_TRADE: ProtoOAOrderTriggerMethod.DOUBLE_TRADE,
+    StopTriggerMethod.DOUBLE_OPPOSITE: ProtoOAOrderTriggerMethod.DOUBLE_OPPOSITE,
+}
+
+
+class NewOrderRequest(FrozenModel):
+    """Request to place a new order.
+
+    Attributes:
+        symbol_id: Symbol to trade.
+        side: Order direction (BUY/SELL).
+        volume: Volume in cents (100 = 0.01 lots).
+        order_type: Type of order.
+        limit_price: Limit price for LIMIT/STOP_LIMIT orders.
+        stop_price: Stop trigger price for STOP/STOP_LIMIT orders.
+        stop_loss: Stop loss price.
+        take_profit: Take profit price.
+        time_in_force: Order duration type.
+        expiration_timestamp: Expiration for GTD orders.
+        position_id: Position ID to close (for closing orders).
+        client_order_id: User-defined order ID.
+        label: User-defined label (max 100 chars).
+        comment: User-defined comment (max 256 chars).
+        base_slippage_price: Base price for slippage calculation.
+        slippage_in_points: Max allowed slippage.
+        trailing_stop_loss: Enable trailing stop loss.
+        guaranteed_stop_loss: Enable guaranteed stop loss.
+        relative_stop_loss: Stop loss distance in points.
+        relative_take_profit: Take profit distance in points.
+        stop_trigger_method: How to trigger stop orders.
+    """
+
+    symbol_id: int
+    side: OrderSide
+    volume: int
+    order_type: OrderType = OrderType.MARKET
+
+    # Prices (as float for convenience)
+    limit_price: float | None = None
+    stop_price: float | None = None
+    stop_loss: float | None = None
+    take_profit: float | None = None
+
+    # Duration
+    time_in_force: TimeInForce = TimeInForce.GOOD_TILL_CANCEL
+    expiration_timestamp: datetime | None = None
+
+    # Position reference
+    position_id: int | None = None
+
+    # Metadata
+    client_order_id: str = ""
+    label: str = ""
+    comment: str = ""
+
+    # Slippage
+    base_slippage_price: float | None = None
+    slippage_in_points: int | None = None
+
+    # Relative SL/TP
+    relative_stop_loss: int | None = None
+    relative_take_profit: int | None = None
+
+    # Flags
+    trailing_stop_loss: bool = False
+    guaranteed_stop_loss: bool = False
+    stop_trigger_method: StopTriggerMethod | None = None
+
+    def to_proto(self, account_id: int) -> ProtoOANewOrderReq:
+        """Convert to proto message.
+
+        Args:
+            account_id: The trading account ID.
+
+        Returns:
+            Proto request message.
+        """
+
+        # Map enums to proto values
+        order_type_value = ProtoOAOrderType(_ORDER_TYPE_TO_PROTO[self.order_type])
+        trade_side_value = ProtoOATradeSide.BUY if self.side == OrderSide.BUY else ProtoOATradeSide.SELL
+        time_in_force_value = ProtoOATimeInForce(_TIME_IN_FORCE_TO_PROTO[self.time_in_force])
+
+        trigger_method = None
+        if self.stop_trigger_method:
+            trigger_method = ProtoOAOrderTriggerMethod(_TRIGGER_TO_PROTO[self.stop_trigger_method])
+
+        return ProtoOANewOrderReq(
+            payload_type=ProtoOAPayloadType.PROTO_OA_NEW_ORDER_REQ,
+            ctid_trader_account_id=account_id,
+            symbol_id=self.symbol_id,
+            order_type=order_type_value,
+            trade_side=trade_side_value,
+            volume=self.volume,
+            limit_price=self.limit_price or 0.0,
+            stop_price=self.stop_price or 0.0,
+            time_in_force=time_in_force_value,
+            expiration_timestamp=int(self.expiration_timestamp.timestamp() * 1000) if self.expiration_timestamp else 0,
+            stop_loss=self.stop_loss or 0.0,
+            take_profit=self.take_profit or 0.0,
+            comment=self.comment,
+            base_slippage_price=self.base_slippage_price or 0.0,
+            slippage_in_points=self.slippage_in_points or 0,
+            label=self.label,
+            position_id=self.position_id or 0,
+            client_order_id=self.client_order_id,
+            relative_stop_loss=self.relative_stop_loss or 0,
+            relative_take_profit=self.relative_take_profit or 0,
+            guaranteed_stop_loss=self.guaranteed_stop_loss,
+            trailing_stop_loss=self.trailing_stop_loss,
+            stop_trigger_method=trigger_method,  # ty: ignore[invalid-argument-type]
+        )
+
+
+class AmendOrderRequest(FrozenModel):
+    """Request to modify a pending order.
+
+    Only include fields you want to change.
+
+    Attributes:
+        order_id: The order to modify.
+        volume: New volume in cents.
+        limit_price: New limit price.
+        stop_price: New stop trigger price.
+        stop_loss: New stop loss price.
+        take_profit: New take profit price.
+        expiration_timestamp: New expiration time.
+        slippage_in_points: New max slippage.
+        trailing_stop_loss: Enable/disable trailing stop.
+        guaranteed_stop_loss: Enable/disable guaranteed stop.
+        relative_stop_loss: New relative stop loss in points.
+        relative_take_profit: New relative take profit in points.
+        stop_trigger_method: New trigger method.
+    """
+
+    order_id: int
+
+    # Optional updates
+    volume: int | None = None
+    limit_price: float | None = None
+    stop_price: float | None = None
+    stop_loss: float | None = None
+    take_profit: float | None = None
+    expiration_timestamp: datetime | None = None
+    slippage_in_points: int | None = None
+    trailing_stop_loss: bool | None = None
+    guaranteed_stop_loss: bool | None = None
+    relative_stop_loss: int | None = None
+    relative_take_profit: int | None = None
+    stop_trigger_method: StopTriggerMethod | None = None
+
+    def to_proto(self, account_id: int) -> ProtoOAAmendOrderReq:
+        """Convert to proto message.
+
+        Args:
+            account_id: The trading account ID.
+
+        Returns:
+            Proto request message.
+        """
+
+        trigger_method = ProtoOAOrderTriggerMethod.TRADE
+        if self.stop_trigger_method:
+            trigger_method = ProtoOAOrderTriggerMethod(_TRIGGER_TO_PROTO[self.stop_trigger_method])
+
+        return ProtoOAAmendOrderReq(
+            payload_type=ProtoOAPayloadType.PROTO_OA_AMEND_ORDER_REQ,
+            ctid_trader_account_id=account_id,
+            order_id=self.order_id,
+            volume=self.volume or 0,
+            limit_price=self.limit_price or 0.0,
+            stop_price=self.stop_price or 0.0,
+            expiration_timestamp=int(self.expiration_timestamp.timestamp() * 1000) if self.expiration_timestamp else 0,
+            stop_loss=self.stop_loss or 0.0,
+            take_profit=self.take_profit or 0.0,
+            slippage_in_points=self.slippage_in_points or 0,
+            relative_stop_loss=self.relative_stop_loss or 0,
+            relative_take_profit=self.relative_take_profit or 0,
+            guaranteed_stop_loss=self.guaranteed_stop_loss if self.guaranteed_stop_loss is not None else False,
+            trailing_stop_loss=self.trailing_stop_loss if self.trailing_stop_loss is not None else False,
+            stop_trigger_method=trigger_method,
+        )
+
+
+class AmendPositionRequest(FrozenModel):
+    """Request to modify a position's stop loss and take profit.
+
+    Attributes:
+        position_id: The position to modify.
+        stop_loss: New stop loss price, or None to remove.
+        take_profit: New take profit price, or None to remove.
+        trailing_stop_loss: Enable/disable trailing stop.
+        guaranteed_stop_loss: Enable/disable guaranteed stop.
+        stop_loss_trigger_method: Trigger method for stop loss.
+    """
+
+    position_id: int
+    stop_loss: float | None = None
+    take_profit: float | None = None
+    trailing_stop_loss: bool = False
+    guaranteed_stop_loss: bool = False
+    stop_loss_trigger_method: StopTriggerMethod | None = None
+
+    def to_proto(self, account_id: int) -> ProtoOAAmendPositionSLTPReq:
+        """Convert to proto message.
+
+        Args:
+            account_id: The trading account ID.
+
+        Returns:
+            Proto request message.
+        """
+
+        trigger_method = ProtoOAOrderTriggerMethod.TRADE
+        if self.stop_loss_trigger_method:
+            trigger_method = ProtoOAOrderTriggerMethod(_TRIGGER_TO_PROTO[self.stop_loss_trigger_method])
+
+        return ProtoOAAmendPositionSLTPReq(
+            payload_type=ProtoOAPayloadType.PROTO_OA_AMEND_POSITION_SLTP_REQ,
+            ctid_trader_account_id=account_id,
+            position_id=self.position_id,
+            stop_loss=self.stop_loss or 0.0,
+            take_profit=self.take_profit or 0.0,
+            guaranteed_stop_loss=self.guaranteed_stop_loss,
+            trailing_stop_loss=self.trailing_stop_loss,
+            stop_loss_trigger_method=trigger_method,
+        )
+
+
+class ClosePositionRequest(FrozenModel):
+    """Request to close a position.
+
+    Attributes:
+        position_id: The position to close.
+        volume: Volume to close in cents. Use position's full volume
+            for complete close, or partial volume for partial close.
+    """
+
+    position_id: int
+    volume: int
+
+    def to_proto(self, account_id: int) -> ProtoOAClosePositionReq:
+        """Convert to proto message.
+
+        Args:
+            account_id: The trading account ID.
+
+        Returns:
+            Proto request message.
+        """
+
+        return ProtoOAClosePositionReq(
+            payload_type=ProtoOAPayloadType.PROTO_OA_CLOSE_POSITION_REQ,
+            ctid_trader_account_id=account_id,
+            position_id=self.position_id,
+            volume=self.volume,
+        )

ctrader_api_client/models/symbol.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .._internal.proto import ProtoOATradingMode
+from ..enums import TradingMode
+from ._base import FrozenModel
+
+
+if TYPE_CHECKING:
+    from .._internal.proto import ProtoOALightSymbol, ProtoOASymbol
+
+
+_TRADING_MODE_MAP: dict[int, TradingMode] = {
+    ProtoOATradingMode.ENABLED: TradingMode.ENABLED,
+    ProtoOATradingMode.DISABLED_WITHOUT_PENDINGS_EXECUTION: TradingMode.DISABLED_WITHOUT_PENDINGS_EXECUTION,
+    ProtoOATradingMode.DISABLED_WITH_PENDINGS_EXECUTION: TradingMode.DISABLED_WITH_PENDINGS_EXECUTION,
+    ProtoOATradingMode.CLOSE_ONLY_MODE: TradingMode.CLOSE_ONLY,
+}
+
+
+class SymbolInfo(FrozenModel):
+    """Basic symbol information from symbol list.
+
+    This is the lightweight representation returned when listing symbols.
+    Use Symbol for full trading parameters.
+
+    Attributes:
+        symbol_id: The unique symbol identifier.
+        name: Symbol name (e.g., "EURUSD").
+        enabled: Whether the symbol is enabled for trading.
+        base_asset_id: Asset ID of the base currency.
+        quote_asset_id: Asset ID of the quote currency.
+        category_id: Symbol category ID.
+        description: Human-readable description.
+    """
+
+    symbol_id: int
+    name: str
+    enabled: bool
+    base_asset_id: int
+    quote_asset_id: int
+    category_id: int | None = None
+    description: str = ""
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOALightSymbol) -> SymbolInfo:
+        """Create SymbolInfo from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new SymbolInfo instance.
+        """
+        return cls(
+            symbol_id=proto.symbol_id,
+            name=proto.symbol_name,
+            enabled=proto.enabled,
+            base_asset_id=proto.base_asset_id,
+            quote_asset_id=proto.quote_asset_id,
+            category_id=proto.symbol_category_id if proto.symbol_category_id else None,
+            description=proto.description or "",
+        )
+
+
+class Symbol(FrozenModel):
+    """Full symbol trading parameters.
+
+    Contains all information needed for trading calculations including
+    pip position, lot size, volume limits, and swap rates.
+
+    Attributes:
+        symbol_id: The unique symbol identifier.
+        digits: Price decimal places.
+        pip_position: Position of pip in price (e.g., 4 means 0.0001).
+        lot_size: Contract size in base units (e.g., 100000 for forex).
+        min_volume: Minimum order volume in cents.
+        max_volume: Maximum order volume in cents.
+        step_volume: Volume step in cents.
+        trading_mode: Current trading mode.
+        swap_long: Swap rate for long positions.
+        swap_short: Swap rate for short positions.
+        commission: Commission rate.
+        max_exposure: Maximum allowed exposure.
+        leverage_id: ID of dynamic leverage profile, if any.
+        enable_short_selling: Whether short selling is allowed.
+        guaranteed_stop_loss: Whether guaranteed stop loss is available.
+        sl_distance: Minimum stop loss distance.
+        tp_distance: Minimum take profit distance.
+        schedule_timezone: Timezone for trading schedule.
+        measurement_units: Measurement units (e.g., "oz" for gold).
+    """
+
+    symbol_id: int
+    digits: int
+    pip_position: int
+    lot_size: int
+    min_volume: int
+    max_volume: int
+    step_volume: int
+    trading_mode: TradingMode
+    swap_long: float
+    swap_short: float
+
+    # Optional fields
+    commission: int = 0
+    max_exposure: int | None = None
+    leverage_id: int | None = None
+    enable_short_selling: bool = True
+    guaranteed_stop_loss: bool = False
+    sl_distance: int = 0
+    tp_distance: int = 0
+    schedule_timezone: str = ""
+    measurement_units: str = ""
+
+    def price_to_decimal(self, raw_price: int) -> Decimal:
+        """Convert raw price integer to Decimal.
+
+        Args:
+            raw_price: Raw price from API.
+
+        Returns:
+            Price as Decimal with correct precision.
+        """
+        return Decimal(raw_price) / Decimal(10**self.digits)
+
+    def decimal_to_price(self, price: Decimal) -> int:
+        """Convert Decimal price to raw integer.
+
+        Args:
+            price: Price as Decimal.
+
+        Returns:
+            Raw price integer for API.
+        """
+        return int(price * Decimal(10**self.digits))
+
+    @staticmethod
+    def volume_to_lots(volume_cents: int) -> Decimal:
+        """Convert volume in cents to lots.
+
+        Args:
+            volume_cents: Volume in cents (100 = 0.01 lots).
+
+        Returns:
+            Volume in lots.
+        """
+        return Decimal(volume_cents) / Decimal(100)
+
+    @staticmethod
+    def lots_to_volume(lots: Decimal) -> int:
+        """Convert lots to volume in cents.
+
+        Args:
+            lots: Volume in lots.
+
+        Returns:
+            Volume in cents for API.
+        """
+        return int(lots * 100)
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOASymbol) -> Symbol:
+        """Create Symbol from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new Symbol instance.
+        """
+        return cls(
+            symbol_id=proto.symbol_id,
+            digits=proto.digits,
+            pip_position=proto.pip_position,
+            lot_size=proto.lot_size,
+            min_volume=proto.min_volume,
+            max_volume=proto.max_volume,
+            step_volume=proto.step_volume,
+            trading_mode=_TRADING_MODE_MAP.get(proto.trading_mode, TradingMode.ENABLED),
+            swap_long=proto.swap_long,
+            swap_short=proto.swap_short,
+            commission=proto.commission if proto.commission else 0,
+            max_exposure=proto.max_exposure if proto.max_exposure else None,
+            leverage_id=proto.leverage_id if proto.leverage_id else None,
+            enable_short_selling=proto.enable_short_selling,
+            guaranteed_stop_loss=proto.guaranteed_stop_loss,
+            sl_distance=proto.sl_distance if proto.sl_distance else 0,
+            tp_distance=proto.tp_distance if proto.tp_distance else 0,
+            schedule_timezone=proto.schedule_time_zone or "",
+            measurement_units=proto.measurement_units or "",
+        )