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

ctrader_api_client/events/types.py

@@ -0,0 +1,340 @@
+"""
+Not yet implemented:
+    - ProtoOAMarginCallUpdateEvent: Margin call threshold configuration changed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+
+from ..enums import ExecutionType, OrderSide
+
+
+@dataclass(frozen=True, slots=True)
+class SpotEvent:
+    """Price tick event.
+
+    Emitted when bid/ask prices update for a subscribed symbol.
+
+    Note: Prices are raw integer values from the server. To convert to
+    actual prices, divide by 10^5 (e.g., 123000 = 1.23000). The exact
+    decimal places depend on symbol configuration.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        symbol_id: The symbol identifier.
+        bid: Current bid price as raw integer, or None if unchanged.
+        ask: Current ask price as raw integer, or None if unchanged.
+        timestamp: Server timestamp of the tick.
+    """
+
+    account_id: int
+    symbol_id: int
+    bid: int | None
+    ask: int | None
+    timestamp: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionEvent:
+    """Order execution event.
+
+    Emitted when an order is accepted, filled, modified, canceled, etc.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        execution_type: Type of execution (fill, cancel, etc.).
+        order_id: The order identifier.
+        position_id: The position identifier (if applicable).
+        symbol_id: The symbol identifier.
+        side: Order side (buy/sell).
+        filled_volume: Volume filled in this execution (in cents).
+        fill_price: Execution price (if filled).
+        timestamp: Server timestamp of the execution.
+        is_server_event: True if generated by server (e.g., stop-out).
+        error_code: Error code if execution failed.
+    """
+
+    account_id: int
+    execution_type: ExecutionType
+    order_id: int
+    position_id: int | None
+    symbol_id: int
+    side: OrderSide
+    filled_volume: int | None
+    fill_price: Decimal | None
+    timestamp: datetime
+    is_server_event: bool = False
+    error_code: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OrderErrorEvent:
+    """Order error event.
+
+    Emitted when an order operation fails.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        order_id: The order identifier (if available).
+        position_id: The position identifier (if available).
+        error_code: The error code from the server.
+        description: Human-readable error description.
+    """
+
+    account_id: int
+    order_id: int | None
+    position_id: int | None
+    error_code: str
+    description: str
+
+
+@dataclass(frozen=True, slots=True)
+class TraderUpdateEvent:
+    """Trader account update event.
+
+    Emitted when account information changes (balance, leverage, etc.).
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        balance: Current account balance (raw, divide by 10^moneyDigits).
+        leverage_in_cents: Account leverage in cents (5000 = 1:50).
+        money_digits: Exponent for monetary values.
+    """
+
+    account_id: int
+    balance: int
+    leverage_in_cents: int | None
+    money_digits: int
+
+
+@dataclass(frozen=True, slots=True)
+class MarginChangeEvent:
+    """Position margin change event.
+
+    Emitted when the margin allocated to a position changes.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        position_id: The position identifier.
+        used_margin: New margin value (raw, divide by 10^moneyDigits).
+        money_digits: Exponent for monetary values.
+    """
+
+    account_id: int
+    position_id: int
+    used_margin: int
+    money_digits: int
+
+
+@dataclass(frozen=True, slots=True)
+class DepthQuote:
+    """
+    Single depth of market quote.
+
+    Attributes:
+        quote_id: Unique identifier for the quote (used for updates/deletions).
+        price: Quote price (raw integer, divide by 10^priceDigits).
+        size: Quote size (volume in cents).
+        is_bid: True if this is a bid quote, False if it's an ask quote.
+    """
+
+    quote_id: int
+    price: int
+    size: int
+    is_bid: bool
+
+
+@dataclass(frozen=True, slots=True)
+class DepthEvent:
+    """Market depth (order book) event.
+
+    Emitted when the order book updates for a subscribed symbol.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        symbol_id: The symbol identifier.
+        new_quotes: New or updated quotes.
+        deleted_quote_ids: IDs of quotes that were removed.
+    """
+
+    account_id: int
+    symbol_id: int
+    new_quotes: tuple[DepthQuote, ...]
+    deleted_quote_ids: tuple[int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenInvalidatedEvent:
+    """Token invalidated event.
+
+    Emitted when access tokens are revoked or expired.
+
+    Attributes:
+        account_ids: List of affected account IDs.
+        reason: Reason for invalidation.
+    """
+
+    account_ids: tuple[int, ...]
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ClientDisconnectEvent:
+    """Client disconnect event.
+
+    Emitted when the server terminates the client connection.
+
+    Attributes:
+        reason: Reason for disconnection.
+    """
+
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class AccountDisconnectEvent:
+    """Account disconnect event.
+
+    Emitted when a specific account session is terminated.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+    """
+
+    account_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolChangedEvent:
+    """Symbol configuration changed event.
+
+    Emitted when a symbol's configuration is updated (trading hours,
+    margin requirements, spreads, etc.).
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        symbol_ids: List of symbol IDs that changed.
+    """
+
+    account_id: int
+    symbol_ids: tuple[int, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TrailingStopChangedEvent:
+    """Trailing stop loss level changed event.
+
+    Emitted when a trailing stop loss price is updated due to
+    favorable price movement.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        position_id: The position identifier.
+        order_id: The stop loss order identifier.
+        stop_price: New stop loss price.
+        timestamp: Server timestamp of the update.
+    """
+
+    account_id: int
+    position_id: int
+    order_id: int
+    stop_price: Decimal
+    timestamp: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class MarginCallTriggerEvent:
+    """Margin call triggered event.
+
+    Emitted when account margin level reaches a configured threshold.
+    Sent at most once every 10 minutes per threshold to avoid spam.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        margin_call_type: Type of margin call (1, 2, or 3 for different thresholds).
+        margin_level_threshold: The threshold that was breached (percentage).
+    """
+
+    account_id: int
+    margin_call_type: int
+    margin_level_threshold: Decimal
+
+
+@dataclass(frozen=True, slots=True)
+class PnLChangeEvent:
+    """Unrealized PnL change event.
+
+    Emitted when unrealized profit/loss changes due to market movement.
+    Requires subscription via ProtoOAv1PnLChangeSubscribeReq.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        gross_unrealized_pnl: Gross unrealized PnL (raw, divide by 10^moneyDigits).
+        net_unrealized_pnl: Net unrealized PnL (raw, divide by 10^moneyDigits).
+        money_digits: Exponent for monetary values.
+    """
+
+    account_id: int
+    gross_unrealized_pnl: int
+    net_unrealized_pnl: int
+    money_digits: int
+
+
+@dataclass(frozen=True, slots=True)
+class ReconnectedEvent:
+    """Emitted after automatic reconnection and re-authentication.
+
+    When a connection is lost and automatically restored, the client
+    re-authenticates the app and all previously authenticated accounts.
+    Subscriptions (spots, trendbars, depth) are NOT automatically restored
+    and should be handled using ReadyEvent instead.
+    Use this event for any custom logic that depends on reconnection, such as logging or alerting.
+
+    Attributes:
+        app_auth_restored: Whether app authentication succeeded.
+        restored_accounts: Account IDs that were successfully re-authenticated.
+        failed_accounts: Accounts that failed, as (account_id, error_message) tuples.
+    """
+
+    app_auth_restored: bool
+    restored_accounts: tuple[int, ...]
+    failed_accounts: tuple[tuple[int, str], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ReadyEvent:
+    """Emitted when an account is authenticated and ready for use.
+
+    Fired after both initial authentication and reconnection re-authentication.
+    Use this to set up subscriptions that should persist across reconnections.
+
+    Attributes:
+        account_id: The cTID trader account ID that is now ready.
+        is_reconnect: True if this follows a reconnection, False for initial auth.
+    """
+
+    account_id: int
+    is_reconnect: bool
+
+
+# Type alias for any event type
+type Event = (
+    SpotEvent
+    | ExecutionEvent
+    | OrderErrorEvent
+    | TraderUpdateEvent
+    | MarginChangeEvent
+    | DepthEvent
+    | TokenInvalidatedEvent
+    | ClientDisconnectEvent
+    | AccountDisconnectEvent
+    | SymbolChangedEvent
+    | TrailingStopChangedEvent
+    | MarginCallTriggerEvent
+    | PnLChangeEvent
+    | ReconnectedEvent
+    | ReadyEvent
+)

ctrader_api_client/exceptions.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._internal.proto import ProtoOAErrorCode
+
+
+if TYPE_CHECKING:
+    from ._internal.proto import ProtoOAErrorRes
+
+
+class CTraderError(Exception):
+    """Base exception for all cTrader API errors."""
+
+
+# =============================================================================
+# Connection Errors
+# =============================================================================
+
+
+class CTraderConnectionError(CTraderError):
+    """Base exception for connection-related errors."""
+
+
+class CTraderConnectionFailedError(CTraderConnectionError):
+    """Failed to establish connection to the server."""
+
+    def __init__(self, host: str, port: int, cause: Exception | None = None) -> None:
+        self.host = host
+        self.port = port
+        self.cause = cause
+        message = f"Failed to connect to {host}:{port}"
+        if cause:
+            message += f": {cause}"
+        super().__init__(message)
+
+
+class CTraderConnectionClosedError(CTraderConnectionError):
+    """Connection was closed unexpectedly."""
+
+    def __init__(self, reason: str | None = None, was_clean: bool = False) -> None:
+        self.reason = reason
+        self.was_clean = was_clean
+        message = "Connection closed"
+        if was_clean:
+            message += " cleanly"
+        if reason:
+            message += f": {reason}"
+        super().__init__(message)
+
+
+class CTraderConnectionTimeoutError(CTraderConnectionError):
+    """Connection operation timed out."""
+
+    def __init__(self, timeout_seconds: float, operation: str = "operation") -> None:
+        self.timeout_seconds = timeout_seconds
+        self.operation = operation
+        super().__init__(f"{operation} timed out after {timeout_seconds}s")
+
+
+# =============================================================================
+# Authentication Errors
+# =============================================================================
+
+
+class AuthenticationError(CTraderError):
+    """Base exception for authentication-related errors."""
+
+
+class ApplicationAuthError(AuthenticationError):
+    """Application authentication failed."""
+
+    def __init__(self, error_code: str, description: str | None = None) -> None:
+        self.error_code = error_code
+        self.description = description
+        message = f"Application authentication failed: {error_code}"
+        if description:
+            message += f" - {description}"
+        super().__init__(message)
+
+
+class AccountAuthError(AuthenticationError):
+    """Account authentication failed."""
+
+    def __init__(
+        self,
+        error_code: str,
+        description: str | None = None,
+        ctid_trader_account_id: int | None = None,
+    ) -> None:
+        self.error_code = error_code
+        self.description = description
+        self.ctid_trader_account_id = ctid_trader_account_id
+        message = f"Account authentication failed: {error_code}"
+        if ctid_trader_account_id:
+            message += f" (account: {ctid_trader_account_id})"
+        if description:
+            message += f" - {description}"
+        super().__init__(message)
+
+
+class TokenExpiredError(AuthenticationError):
+    """Access token has expired."""
+
+    def __init__(self, ctid_trader_account_id: int | None = None) -> None:
+        self.ctid_trader_account_id = ctid_trader_account_id
+        message = "Access token has expired"
+        if ctid_trader_account_id:
+            message += f" for account {ctid_trader_account_id}"
+        super().__init__(message)
+
+
+class TokenRefreshError(AuthenticationError):
+    """Failed to refresh access token."""
+
+    def __init__(
+        self,
+        ctid_trader_account_id: int | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        self.ctid_trader_account_id = ctid_trader_account_id
+        self.cause = cause
+        message = "Failed to refresh access token"
+        if ctid_trader_account_id:
+            message += f" for account {ctid_trader_account_id}"
+        if cause:
+            message += f": {cause}"
+        super().__init__(message)
+
+
+class AccountNotFoundError(AuthenticationError):
+    """No account found matching the given criteria."""
+
+    def __init__(
+        self,
+        trader_login: int,
+        available_logins: list[int] | None = None,
+    ) -> None:
+        self.trader_login = trader_login
+        self.available_logins = available_logins
+        message = f"No account found with trader login {trader_login}"
+        if available_logins:
+            message += f". Available logins: {available_logins}"
+        super().__init__(message)
+
+
+# =============================================================================
+# API Errors
+# =============================================================================
+
+
+class APIError(CTraderError):
+    """Error response from the cTrader API."""
+
+    def __init__(
+        self,
+        error_code: str,
+        description: str | None = None,
+        ctid_trader_account_id: int | None = None,
+        maintenance_end_timestamp: int | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        self.error_code = error_code
+        self.description = description
+        self.ctid_trader_account_id = ctid_trader_account_id
+        self.maintenance_end_timestamp = maintenance_end_timestamp
+        self.retry_after = retry_after
+
+        message = f"API error: {error_code}"
+        if ctid_trader_account_id:
+            message += f" (account: {ctid_trader_account_id})"
+        if description:
+            message += f" - {description}"
+        super().__init__(message)
+
+    @classmethod
+    def from_proto(cls, error_res: ProtoOAErrorRes) -> APIError:
+        """Create an APIError from a ProtoOAErrorRes message."""
+        return cls(
+            error_code=error_res.error_code,
+            description=error_res.description or None,
+            ctid_trader_account_id=error_res.ctid_trader_account_id or None,
+            maintenance_end_timestamp=error_res.maintenance_end_timestamp or None,
+            retry_after=error_res.retry_after or None,
+        )
+
+    def is_rate_limited(self) -> bool:
+        """Check if this error indicates rate limiting."""
+        return self.error_code == ProtoOAErrorCode.REQUEST_FREQUENCY_EXCEEDED.name or self.retry_after is not None
+
+    def is_maintenance(self) -> bool:
+        """Check if this error indicates server maintenance."""
+        return (
+            self.error_code == ProtoOAErrorCode.SERVER_IS_UNDER_MAINTENANCE.name
+            or self.maintenance_end_timestamp is not None
+        )
+
+
+# =============================================================================
+# Protocol Errors
+# =============================================================================
+
+
+class ProtocolError(CTraderError):
+    """Base exception for protocol-level errors."""
+
+
+class FramingError(ProtocolError):
+    """Error in wire protocol framing."""
+
+    def __init__(self, expected_bytes: int, received_bytes: int) -> None:
+        self.expected_bytes = expected_bytes
+        self.received_bytes = received_bytes
+        super().__init__(f"Framing error: expected {expected_bytes} bytes, received {received_bytes}")
+
+
+class DeserializationError(ProtocolError):
+    """Failed to deserialize a protobuf message."""
+
+    def __init__(self, payload_type: int, raw_data: bytes) -> None:
+        self.payload_type = payload_type
+        self.raw_data = raw_data
+        super().__init__(f"Failed to deserialize message with payload type {payload_type} ({len(raw_data)} bytes)")
+
+
+class UnknownPayloadTypeError(ProtocolError):
+    """Received a message with an unknown payload type."""
+
+    def __init__(self, payload_type: int) -> None:
+        self.payload_type = payload_type
+        super().__init__(f"Unknown payload type: {payload_type}")

ctrader_api_client/models/__init__.py

@@ -0,0 +1,50 @@
+"""High-level Pydantic models for cTrader API.
+
+This module provides Pythonic wrappers over raw protobuf types,
+with conversion methods and price/volume utilities.
+
+Example:
+    ```python
+    from ctrader_api_client.models import (
+        Account,
+        Symbol,
+        Position,
+        NewOrderRequest,
+    )
+    from ctrader_api_client.enums import OrderType, OrderSide
+
+    # Create an order request
+    request = NewOrderRequest(
+        symbol_id=1,
+        side=OrderSide.BUY,
+        volume=100,  # 0.01 lots
+        order_type=OrderType.MARKET,
+    )
+    ```
+"""
+
+from .account import Account, AccountSummary
+from .deal import CloseDetail, Deal
+from .market_data import TickData, Trendbar
+from .order import Order
+from .position import Position
+from .requests import AmendOrderRequest, AmendPositionRequest, ClosePositionRequest, NewOrderRequest
+from .symbol import Symbol, SymbolInfo
+
+
+__all__ = [
+    "Account",
+    "AccountSummary",
+    "AmendOrderRequest",
+    "AmendPositionRequest",
+    "CloseDetail",
+    "ClosePositionRequest",
+    "Deal",
+    "NewOrderRequest",
+    "Order",
+    "Position",
+    "Symbol",
+    "SymbolInfo",
+    "TickData",
+    "Trendbar",
+]

ctrader_api_client/models/_base.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FrozenModel(BaseModel):
+    """Base class for all immutable models.
+
+    All models derived from this class are:
+    - Frozen (immutable after creation)
+    - Strict (no type coercion)
+    - Forbid extra fields
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        strict=True,
+        extra="forbid",
+    )