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

ctrader_api_client/models/account.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .._internal.proto import ProtoOAAccessRights, ProtoOAAccountType
+from ..enums import AccessRights, AccountType
+from ._base import FrozenModel
+
+
+if TYPE_CHECKING:
+    from .._internal.proto import ProtoOACtidTraderAccount, ProtoOATrader
+
+
+def _timestamp_to_datetime(timestamp_ms: int) -> datetime:
+    """Convert millisecond timestamp to datetime."""
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC)
+
+
+_ACCOUNT_TYPE_MAP: dict[int, AccountType] = {
+    ProtoOAAccountType.HEDGED: AccountType.HEDGED,
+    ProtoOAAccountType.NETTED: AccountType.NETTED,
+    ProtoOAAccountType.SPREAD_BETTING: AccountType.SPREAD_BETTING,
+}
+
+_ACCESS_RIGHTS_MAP: dict[int, AccessRights] = {
+    ProtoOAAccessRights.FULL_ACCESS: AccessRights.FULL_ACCESS,
+    ProtoOAAccessRights.CLOSE_ONLY: AccessRights.CLOSE_ONLY,
+    ProtoOAAccessRights.NO_TRADING: AccessRights.NO_TRADING,
+    ProtoOAAccessRights.NO_LOGIN: AccessRights.NO_LOGIN,
+}
+
+
+class AccountSummary(FrozenModel):
+    """Summary of a trading account from account list.
+
+    This is the lightweight representation returned when listing accounts
+    associated with an access token. Use Account for full details after
+    authorization.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        is_live: True if this is a live account, False for demo.
+        trader_login: The trader's login number.
+        broker_name: Short name of the broker.
+        last_closing_deal_timestamp: Timestamp of last closing deal, or None.
+        last_balance_update_timestamp: Timestamp of last balance update, or None.
+    """
+
+    account_id: int
+    is_live: bool
+    trader_login: int
+    broker_name: str
+    last_closing_deal_timestamp: datetime | None = None
+    last_balance_update_timestamp: datetime | None = None
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOACtidTraderAccount) -> AccountSummary:
+        """Create AccountSummary from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new AccountSummary instance.
+        """
+        return cls(
+            account_id=proto.ctid_trader_account_id,
+            is_live=proto.is_live,
+            trader_login=proto.trader_login,
+            broker_name=proto.broker_title_short or "",
+            last_closing_deal_timestamp=(
+                _timestamp_to_datetime(proto.last_closing_deal_timestamp) if proto.last_closing_deal_timestamp else None
+            ),
+            last_balance_update_timestamp=(
+                _timestamp_to_datetime(proto.last_balance_update_timestamp)
+                if proto.last_balance_update_timestamp
+                else None
+            ),
+        )
+
+
+class Account(FrozenModel):
+    """Full trading account details.
+
+    Retrieved after authorizing a specific account. Contains balance,
+    leverage, and other trading parameters.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        trader_login: The trader's login number.
+        balance: Account balance (raw integer, use get_balance() for Decimal).
+        money_digits: Decimal places for monetary values.
+        leverage_in_cents: Account leverage in cents (e.g., 10000 = 1:100).
+        account_type: Account type (HEDGED, NETTED, SPREAD_BETTING).
+        access_rights: Current access rights for the account.
+        broker_name: Name of the broker.
+        deposit_asset_id: Asset ID of the deposit currency.
+        swap_free: Whether account is swap-free (Islamic Banking).
+        is_limited_risk: Whether account has limited risk mode.
+        registration_timestamp: When the account was registered.
+        max_leverage: Maximum allowed leverage.
+        balance_version: Version number for balance updates.
+        manager_bonus: Manager bonus amount (raw integer).
+        ib_bonus: IB bonus amount (raw integer).
+        non_withdrawable_bonus: Non-withdrawable bonus amount (raw integer).
+    """
+
+    account_id: int
+    trader_login: int
+    balance: int
+    money_digits: int
+    leverage_in_cents: int
+    account_type: AccountType
+    access_rights: AccessRights
+    broker_name: str
+    deposit_asset_id: int
+    swap_free: bool
+    is_limited_risk: bool
+    registration_timestamp: datetime | None = None
+
+    # Optional fields
+    max_leverage: int | None = None
+    balance_version: int | None = None
+    manager_bonus: int | None = None
+    ib_bonus: int | None = None
+    non_withdrawable_bonus: int | None = None
+
+    def get_balance(self) -> Decimal:
+        """Get balance as Decimal.
+
+        Returns:
+            Balance divided by 10^money_digits.
+        """
+        return Decimal(self.balance) / Decimal(10**self.money_digits)
+
+    def get_leverage(self) -> str:
+        """Get leverage as human-readable string.
+
+        Returns:
+            Leverage string like "1:100".
+        """
+        leverage = self.leverage_in_cents // 100
+        return f"1:{leverage}"
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOATrader) -> Account:
+        """Create Account from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new Account instance.
+        """
+        return cls(
+            account_id=proto.ctid_trader_account_id,
+            trader_login=proto.trader_login,
+            balance=proto.balance,
+            money_digits=proto.money_digits if proto.money_digits else 2,
+            leverage_in_cents=proto.leverage_in_cents,
+            account_type=_ACCOUNT_TYPE_MAP.get(proto.account_type, AccountType.HEDGED),
+            access_rights=_ACCESS_RIGHTS_MAP.get(proto.access_rights, AccessRights.FULL_ACCESS),
+            broker_name=proto.broker_name or "",
+            deposit_asset_id=proto.deposit_asset_id,
+            swap_free=proto.swap_free,
+            is_limited_risk=proto.is_limited_risk,
+            registration_timestamp=(
+                _timestamp_to_datetime(proto.registration_timestamp) if proto.registration_timestamp else None
+            ),
+            max_leverage=proto.max_leverage if proto.max_leverage else None,
+            balance_version=proto.balance_version if proto.balance_version else None,
+            manager_bonus=proto.manager_bonus if proto.manager_bonus else None,
+            ib_bonus=proto.ib_bonus if proto.ib_bonus else None,
+            non_withdrawable_bonus=proto.non_withdrawable_bonus if proto.non_withdrawable_bonus else None,
+        )

ctrader_api_client/models/deal.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .._internal.proto import ProtoOADealStatus
+from ..enums import DealStatus, OrderSide
+from ._base import FrozenModel
+
+
+if TYPE_CHECKING:
+    from .._internal.proto import ProtoOAClosePositionDetail, ProtoOADeal
+    from .symbol import Symbol
+
+
+def _timestamp_to_datetime(timestamp_ms: int) -> datetime:
+    """Convert millisecond timestamp to datetime."""
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC)
+
+
+_DEAL_STATUS_MAP: dict[int, DealStatus] = {
+    ProtoOADealStatus.FILLED: DealStatus.FILLED,
+    ProtoOADealStatus.PARTIALLY_FILLED: DealStatus.PARTIALLY_FILLED,
+    ProtoOADealStatus.REJECTED: DealStatus.REJECTED,
+    ProtoOADealStatus.INTERNALLY_REJECTED: DealStatus.INTERNALLY_REJECTED,
+    ProtoOADealStatus.ERROR: DealStatus.ERROR,
+    ProtoOADealStatus.MISSED: DealStatus.MISSED,
+}
+
+
+class CloseDetail(FrozenModel):
+    """Details about position closure from a deal.
+
+    Present only when a deal results in closing (fully or partially)
+    a position.
+
+    Attributes:
+        entry_price: Original entry price of the position.
+        closed_volume: Volume that was closed.
+        gross_profit: Gross profit/loss (raw integer).
+        swap: Swap charged (raw integer).
+        commission: Commission charged (raw integer).
+        balance: Account balance after close (raw integer).
+        money_digits: Decimal places for monetary values.
+        pnl_conversion_fee: Fee for P&L currency conversion (raw integer).
+        quote_to_deposit_rate: Conversion rate from quote to deposit currency.
+        balance_version: Version number for balance updates.
+    """
+
+    entry_price: float
+    closed_volume: int
+    gross_profit: int
+    swap: int
+    commission: int
+    balance: int
+    money_digits: int
+    pnl_conversion_fee: int = 0
+    quote_to_deposit_rate: float | None = None
+    balance_version: int | None = None
+
+    def get_gross_profit(self) -> Decimal:
+        """Get gross profit as Decimal.
+
+        Returns:
+            Gross profit divided by 10^money_digits.
+        """
+        return Decimal(self.gross_profit) / Decimal(10**self.money_digits)
+
+    def get_net_profit(self) -> Decimal:
+        """Get net profit (gross - swap - commission - fee) as Decimal.
+
+        Returns:
+            Net profit divided by 10^money_digits.
+        """
+        net = self.gross_profit - self.swap - self.commission - self.pnl_conversion_fee
+        return Decimal(net) / Decimal(10**self.money_digits)
+
+    def get_swap(self) -> Decimal:
+        """Get swap as Decimal.
+
+        Returns:
+            Swap divided by 10^money_digits.
+        """
+        return Decimal(self.swap) / Decimal(10**self.money_digits)
+
+    def get_commission(self) -> Decimal:
+        """Get commission as Decimal.
+
+        Returns:
+            Commission divided by 10^money_digits.
+        """
+        return Decimal(self.commission) / Decimal(10**self.money_digits)
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOAClosePositionDetail) -> CloseDetail:
+        """Create CloseDetail from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new CloseDetail instance.
+        """
+        return cls(
+            entry_price=proto.entry_price,
+            closed_volume=proto.closed_volume,
+            gross_profit=proto.gross_profit,
+            swap=proto.swap,
+            commission=proto.commission,
+            balance=proto.balance,
+            money_digits=proto.money_digits if proto.money_digits else 2,
+            pnl_conversion_fee=proto.pnl_conversion_fee if proto.pnl_conversion_fee else 0,
+            quote_to_deposit_rate=proto.quote_to_deposit_conversion_rate
+            if proto.quote_to_deposit_conversion_rate
+            else None,
+            balance_version=proto.balance_version if proto.balance_version else None,
+        )
+
+
+class Deal(FrozenModel):
+    """A trade execution (deal).
+
+    Represents a single execution that fills an order. An order may have
+    multiple deals if it's filled in parts.
+
+    Attributes:
+        deal_id: Unique deal identifier.
+        order_id: The order that was executed.
+        position_id: The position affected by this deal.
+        symbol_id: The symbol traded.
+        side: Trade direction (BUY/SELL).
+        volume: Requested volume in cents.
+        filled_volume: Actually filled volume in cents.
+        execution_price: Price at which the deal was executed.
+        execution_timestamp: When the deal was executed.
+        status: Deal status.
+        commission: Commission charged (raw integer).
+        money_digits: Decimal places for monetary values.
+        create_timestamp: When the deal was created.
+        last_update_timestamp: When the deal was last updated.
+        margin_rate: Margin rate for the deal.
+        base_to_usd_rate: Conversion rate from base currency to USD.
+        close_detail: Details if this deal closed a position, or None.
+    """
+
+    deal_id: int
+    order_id: int
+    position_id: int
+    symbol_id: int
+    side: OrderSide
+    volume: int
+    filled_volume: int
+    execution_price: float
+    execution_timestamp: datetime
+    status: DealStatus
+    commission: int
+    money_digits: int
+
+    # Optional
+    create_timestamp: datetime | None = None
+    last_update_timestamp: datetime | None = None
+    margin_rate: float | None = None
+    base_to_usd_rate: float | None = None
+    close_detail: CloseDetail | None = None
+
+    def get_execution_price(self, symbol: Symbol) -> Decimal:
+        """Get execution price as Decimal.
+
+        Args:
+            symbol: Symbol for price precision.
+
+        Returns:
+            Execution price with correct decimal places.
+        """
+        return Decimal(str(self.execution_price)).quantize(Decimal(10) ** -symbol.digits)
+
+    def get_commission(self) -> Decimal:
+        """Get commission as Decimal.
+
+        Returns:
+            Commission divided by 10^money_digits.
+        """
+        return Decimal(self.commission) / Decimal(10**self.money_digits)
+
+    def get_volume_in_lots(self, symbol: Symbol) -> Decimal:
+        """Get filled volume in lots.
+
+        Args:
+            symbol: Symbol for lot conversion.
+
+        Returns:
+            Volume in lots.
+        """
+        return symbol.volume_to_lots(self.filled_volume)
+
+    @property
+    def is_closing_deal(self) -> bool:
+        """Whether this deal closed (or partially closed) a position."""
+        if self.close_detail is not None:
+            return self.close_detail.balance > 0
+        else:
+            return False
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOADeal) -> Deal:
+        """Create Deal from proto message.
+
+        Args:
+            proto: The proto message to convert.
+
+        Returns:
+            A new Deal instance.
+        """
+        close_detail = None
+        if proto.close_position_detail:
+            close_detail = CloseDetail.from_proto(proto.close_position_detail)
+
+        # Determine side
+        side = OrderSide.BUY if proto.trade_side == 1 else OrderSide.SELL
+
+        return cls(
+            deal_id=proto.deal_id,
+            order_id=proto.order_id,
+            position_id=proto.position_id,
+            symbol_id=proto.symbol_id,
+            side=side,
+            volume=proto.volume,
+            filled_volume=proto.filled_volume,
+            execution_price=proto.execution_price,
+            execution_timestamp=_timestamp_to_datetime(proto.execution_timestamp),
+            status=_DEAL_STATUS_MAP.get(proto.deal_status, DealStatus.FILLED),
+            commission=proto.commission if proto.commission else 0,
+            money_digits=proto.money_digits if proto.money_digits else 2,
+            create_timestamp=_timestamp_to_datetime(proto.create_timestamp) if proto.create_timestamp else None,
+            last_update_timestamp=(
+                _timestamp_to_datetime(proto.utc_last_update_timestamp) if proto.utc_last_update_timestamp else None
+            ),
+            margin_rate=proto.margin_rate if proto.margin_rate else None,
+            base_to_usd_rate=proto.base_to_usd_conversion_rate if proto.base_to_usd_conversion_rate else None,
+            close_detail=close_detail,
+        )

ctrader_api_client/models/market_data.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .._internal.proto import ProtoOATrendbarPeriod
+from ..enums import TrendbarPeriod
+from ._base import FrozenModel
+
+
+if TYPE_CHECKING:
+    from .._internal.proto import ProtoOATickData, ProtoOATrendbar
+    from .symbol import Symbol
+
+
+_PERIOD_MAP: dict[int, TrendbarPeriod] = {
+    ProtoOATrendbarPeriod.M1: TrendbarPeriod.M1,
+    ProtoOATrendbarPeriod.M2: TrendbarPeriod.M2,
+    ProtoOATrendbarPeriod.M3: TrendbarPeriod.M3,
+    ProtoOATrendbarPeriod.M4: TrendbarPeriod.M4,
+    ProtoOATrendbarPeriod.M5: TrendbarPeriod.M5,
+    ProtoOATrendbarPeriod.M10: TrendbarPeriod.M10,
+    ProtoOATrendbarPeriod.M15: TrendbarPeriod.M15,
+    ProtoOATrendbarPeriod.M30: TrendbarPeriod.M30,
+    ProtoOATrendbarPeriod.H1: TrendbarPeriod.H1,
+    ProtoOATrendbarPeriod.H4: TrendbarPeriod.H4,
+    ProtoOATrendbarPeriod.H12: TrendbarPeriod.H12,
+    ProtoOATrendbarPeriod.D1: TrendbarPeriod.D1,
+    ProtoOATrendbarPeriod.W1: TrendbarPeriod.W1,
+    ProtoOATrendbarPeriod.MN1: TrendbarPeriod.MN1,
+}
+
+
+class Trendbar(FrozenModel):
+    """Historical OHLC bar (candlestick).
+
+    Note: The raw proto stores prices as deltas from low. This model
+    exposes computed open/high/close values.
+
+    Attributes:
+        timestamp: Bar open time.
+        period: Bar period (M1, H1, D1, etc.).
+        low: Low price (raw integer).
+        open: Open price (raw integer).
+        high: High price (raw integer).
+        close: Close price (raw integer).
+        volume: Trade volume.
+    """
+
+    timestamp: datetime
+    period: TrendbarPeriod
+    low: int
+    open: int
+    high: int
+    close: int
+    volume: int
+
+    def get_ohlc(self, symbol: Symbol) -> tuple[Decimal, Decimal, Decimal, Decimal]:
+        """Get OHLC prices as Decimals.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            Tuple of (open, high, low, close) as Decimals.
+        """
+        return (
+            symbol.price_to_decimal(self.open),
+            symbol.price_to_decimal(self.high),
+            symbol.price_to_decimal(self.low),
+            symbol.price_to_decimal(self.close),
+        )
+
+    def get_open(self, symbol: Symbol) -> Decimal:
+        """Get open price as Decimal.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            Open price.
+        """
+        return symbol.price_to_decimal(self.open)
+
+    def get_high(self, symbol: Symbol) -> Decimal:
+        """Get high price as Decimal.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            High price.
+        """
+        return symbol.price_to_decimal(self.high)
+
+    def get_low(self, symbol: Symbol) -> Decimal:
+        """Get low price as Decimal.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            Low price.
+        """
+        return symbol.price_to_decimal(self.low)
+
+    def get_close(self, symbol: Symbol) -> Decimal:
+        """Get close price as Decimal.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            Close price.
+        """
+        return symbol.price_to_decimal(self.close)
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOATrendbar) -> Trendbar:
+        """Create Trendbar from proto message.
+
+        Args:
+            proto: The proto message.
+
+        Returns:
+            A new Trendbar instance.
+        """
+        # Calculate timestamp from utc_timestamp_in_minutes
+        ts = datetime.now(UTC)
+        if proto.utc_timestamp_in_minutes:
+            ts = datetime.fromtimestamp(proto.utc_timestamp_in_minutes * 60, tz=UTC)
+
+        # Proto stores: low as absolute, others as deltas from low
+        low = proto.low
+        open_price = low + proto.delta_open
+        high = low + proto.delta_high
+        close = low + proto.delta_close
+
+        return cls(
+            timestamp=ts,
+            period=_PERIOD_MAP.get(proto.period, TrendbarPeriod.M1),
+            low=low,
+            open=open_price,
+            high=high,
+            close=close,
+            volume=proto.volume,
+        )
+
+
+class TickData(FrozenModel):
+    """Historical tick data point.
+
+    Represents a single price tick from tick history.
+
+    Attributes:
+        timestamp: Tick time.
+        price: Tick price (raw integer).
+    """
+
+    timestamp: datetime
+    price: int
+
+    def get_price(self, symbol: Symbol) -> Decimal:
+        """Get price as Decimal.
+
+        Args:
+            symbol: Symbol for price conversion.
+
+        Returns:
+            Price as Decimal.
+        """
+        return symbol.price_to_decimal(self.price)
+
+    @classmethod
+    def from_proto(cls, proto: ProtoOATickData, base_timestamp_ms: int = 0) -> TickData:
+        """Create TickData from proto message.
+
+        Args:
+            proto: The proto message.
+            base_timestamp_ms: Base timestamp in milliseconds. Proto timestamp
+                is a delta from this base.
+
+        Returns:
+            A new TickData instance.
+        """
+        # Proto timestamp is delta from base in milliseconds
+        actual_ts = base_timestamp_ms + proto.timestamp
+        return cls(
+            timestamp=datetime.fromtimestamp(actual_ts / 1000, tz=UTC),
+            price=proto.tick,
+        )