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

ctrader_api_client/api/trading.py

@@ -0,0 +1,506 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .._internal.proto import (
+    ProtoOACancelOrderReq,
+    ProtoOADealListByPositionIdReq,
+    ProtoOADealListByPositionIdRes,
+    ProtoOADealListReq,
+    ProtoOADealListRes,
+    ProtoOAExecutionEvent,
+    ProtoOAExecutionType,
+    ProtoOAOrderErrorEvent,
+    ProtoOAOrderListReq,
+    ProtoOAOrderListRes,
+    ProtoOAReconcileReq,
+    ProtoOAReconcileRes,
+)
+from ..enums import ExecutionType, OrderSide
+from ..events import ExecutionEvent
+from ..exceptions import APIError
+from ..models import Deal, Order, Position
+from ..models.requests import (
+    AmendOrderRequest,
+    AmendPositionRequest,
+    ClosePositionRequest,
+    NewOrderRequest,
+)
+
+
+if TYPE_CHECKING:
+    from ..connection import Protocol
+
+
+def _raise_if_order_error(response: object) -> None:
+    """Raise APIError if response is an order error event.
+
+    Args:
+        response: The response to check.
+
+    Raises:
+        APIError: If response is a ProtoOAOrderErrorEvent.
+    """
+    if isinstance(response, ProtoOAOrderErrorEvent):
+        raise APIError(
+            error_code=response.error_code or "ORDER_ERROR",
+            description=response.description or None,
+            ctid_trader_account_id=response.ctid_trader_account_id or None,
+        )
+
+
+# Map ProtoOAExecutionType enum values to our ExecutionType
+_EXECUTION_TYPE_MAP: dict[int, ExecutionType] = {
+    ProtoOAExecutionType.ORDER_ACCEPTED: ExecutionType.ORDER_ACCEPTED,
+    ProtoOAExecutionType.ORDER_FILLED: ExecutionType.ORDER_FILLED,
+    ProtoOAExecutionType.ORDER_REPLACED: ExecutionType.ORDER_REPLACED,
+    ProtoOAExecutionType.ORDER_CANCELLED: ExecutionType.ORDER_CANCELLED,
+    ProtoOAExecutionType.ORDER_EXPIRED: ExecutionType.ORDER_EXPIRED,
+    ProtoOAExecutionType.ORDER_REJECTED: ExecutionType.ORDER_REJECTED,
+    ProtoOAExecutionType.ORDER_CANCEL_REJECTED: ExecutionType.ORDER_CANCEL_REJECTED,
+    ProtoOAExecutionType.SWAP: ExecutionType.SWAP,
+    ProtoOAExecutionType.DEPOSIT_WITHDRAW: ExecutionType.DEPOSIT_WITHDRAW,
+    ProtoOAExecutionType.ORDER_PARTIAL_FILL: ExecutionType.ORDER_PARTIAL_FILL,
+    ProtoOAExecutionType.BONUS_DEPOSIT_WITHDRAW: ExecutionType.BONUS_DEPOSIT_WITHDRAW,
+}
+
+
+def _proto_to_execution_event(proto: ProtoOAExecutionEvent) -> ExecutionEvent:
+    """Convert ProtoOAExecutionEvent to ExecutionEvent.
+
+    Args:
+        proto: The proto message to convert.
+
+    Returns:
+        ExecutionEvent instance.
+
+    Raises:
+        APIError: If execution type is unknown.
+    """
+    exec_type = _EXECUTION_TYPE_MAP.get(proto.execution_type)
+    if exec_type is None:
+        raise APIError(
+            error_code="UNKNOWN_EXECUTION_TYPE",
+            description=f"Unknown execution type: {proto.execution_type}",
+        )
+
+    # Map order side
+    side = OrderSide.BUY
+    if proto.order and proto.order.trade_data:
+        if proto.order.trade_data.trade_side == 2:
+            side = OrderSide.SELL
+
+    # Extract order details
+    order_id = proto.order.order_id if proto.order else 0
+    position_id = proto.position.position_id if proto.position else None
+    symbol_id = proto.order.trade_data.symbol_id if proto.order and proto.order.trade_data else 0
+
+    # Extract deal details
+    filled_volume = None
+    fill_price = None
+    timestamp = datetime.now(UTC)
+
+    if proto.deal:
+        filled_volume = proto.deal.filled_volume if proto.deal.filled_volume else None
+        if proto.deal.execution_price:
+            fill_price = Decimal(str(proto.deal.execution_price))
+        if proto.deal.execution_timestamp:
+            timestamp = datetime.fromtimestamp(proto.deal.execution_timestamp / 1000, tz=UTC)
+
+    return ExecutionEvent(
+        account_id=proto.ctid_trader_account_id,
+        execution_type=exec_type,
+        order_id=order_id,
+        position_id=position_id,
+        symbol_id=symbol_id,
+        side=side,
+        filled_volume=filled_volume,
+        fill_price=fill_price,
+        timestamp=timestamp,
+        is_server_event=proto.is_server_event if proto.is_server_event else False,
+        error_code=proto.error_code if proto.error_code else None,
+    )
+
+
+class TradingAPI:
+    """Trading operations: orders and positions.
+
+    Provides methods for order placement, modification, cancellation,
+    and position management.
+
+    Example:
+        ```python
+        from ctrader_api_client.models import NewOrderRequest
+        from ctrader_api_client.enums import OrderSide, OrderType
+
+        # Place a market order
+        request = NewOrderRequest(
+            symbol_id=270,
+            side=OrderSide.BUY,
+            volume=100,  # 0.01 lots
+            order_type=OrderType.MARKET,
+        )
+        execution = await client.trading.place_order(account_id, request)
+        print(f"Order {execution.order_id}: {execution.execution_type}")
+
+        # Get open positions
+        positions = await client.trading.get_open_positions(account_id)
+        for pos in positions:
+            print(f"Position {pos.position_id}: {pos.volume} @ {pos.entry_price}")
+        ```
+    """
+
+    def __init__(self, protocol: Protocol, default_timeout: float = 30.0) -> None:
+        """Initialize the trading API.
+
+        Args:
+            protocol: The protocol instance for sending requests.
+            default_timeout: Default request timeout in seconds.
+        """
+        self._protocol = protocol
+        self._default_timeout = default_timeout
+
+    async def place_order(
+        self,
+        account_id: int,
+        request: NewOrderRequest,
+        timeout: float | None = None,
+    ) -> ExecutionEvent:
+        """Place a new order.
+
+        Args:
+            account_id: The cTID trader account ID.
+            request: Order parameters.
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            ExecutionEvent with order details.
+
+        Note:
+            For market orders, the order may be immediately filled.
+            Check execution_type to determine the outcome:
+            - ORDER_ACCEPTED: Pending order created
+            - ORDER_FILLED: Order fully executed
+            - ORDER_PARTIAL_FILL: Order partially executed
+            - ORDER_REJECTED: Order was rejected
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        proto_request = request.to_proto(account_id)
+
+        response = await self._protocol.send_request(
+            proto_request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        _raise_if_order_error(response)
+
+        if not isinstance(response, ProtoOAExecutionEvent):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAExecutionEvent, got {type(response).__name__}",
+            )
+
+        return _proto_to_execution_event(response)
+
+    async def amend_order(
+        self,
+        account_id: int,
+        request: AmendOrderRequest,
+        timeout: float | None = None,
+    ) -> ExecutionEvent:
+        """Modify a pending order.
+
+        Args:
+            account_id: The cTID trader account ID.
+            request: Amendment parameters (order_id required).
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            ExecutionEvent confirming the amendment.
+
+        Raises:
+            APIError: If request fails or order not found.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        proto_request = request.to_proto(account_id)
+
+        response = await self._protocol.send_request(
+            proto_request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        _raise_if_order_error(response)
+
+        if not isinstance(response, ProtoOAExecutionEvent):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAExecutionEvent, got {type(response).__name__}",
+            )
+
+        return _proto_to_execution_event(response)
+
+    async def cancel_order(
+        self,
+        account_id: int,
+        order_id: int,
+        timeout: float | None = None,
+    ) -> ExecutionEvent:
+        """Cancel a pending order.
+
+        Args:
+            account_id: The cTID trader account ID.
+            order_id: The order to cancel.
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            ExecutionEvent confirming cancellation.
+
+        Raises:
+            APIError: If request fails or order not found.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOACancelOrderReq(
+            ctid_trader_account_id=account_id,
+            order_id=order_id,
+        )
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        _raise_if_order_error(response)
+
+        if not isinstance(response, ProtoOAExecutionEvent):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAExecutionEvent, got {type(response).__name__}",
+            )
+
+        return _proto_to_execution_event(response)
+
+    async def close_position(
+        self,
+        account_id: int,
+        request: ClosePositionRequest,
+        timeout: float | None = None,
+    ) -> ExecutionEvent:
+        """Close a position (fully or partially).
+
+        Args:
+            account_id: The cTID trader account ID.
+            request: Close parameters (position_id and volume required).
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            ExecutionEvent with closing details.
+
+        Raises:
+            APIError: If request fails or position not found.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        proto_request = request.to_proto(account_id)
+
+        response = await self._protocol.send_request(
+            proto_request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        _raise_if_order_error(response)
+
+        if not isinstance(response, ProtoOAExecutionEvent):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAExecutionEvent, got {type(response).__name__}",
+            )
+
+        return _proto_to_execution_event(response)
+
+    async def amend_position(
+        self,
+        account_id: int,
+        request: AmendPositionRequest,
+        timeout: float | None = None,
+    ) -> ExecutionEvent:
+        """Modify position stop loss and take profit.
+
+        Args:
+            account_id: The cTID trader account ID.
+            request: Amendment parameters (position_id required).
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            ExecutionEvent confirming the amendment.
+
+        Raises:
+            APIError: If request fails or position not found.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        proto_request = request.to_proto(account_id)
+
+        response = await self._protocol.send_request(
+            proto_request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        _raise_if_order_error(response)
+
+        if not isinstance(response, ProtoOAExecutionEvent):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAExecutionEvent, got {type(response).__name__}",
+            )
+
+        return _proto_to_execution_event(response)
+
+    async def get_open_positions(
+        self,
+        account_id: int,
+        timeout: float | None = None,
+    ) -> list[Position]:
+        """Get all open positions.
+
+        Args:
+            account_id: The cTID trader account ID.
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            List of open Position objects.
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOAReconcileReq(ctid_trader_account_id=account_id)
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        if not isinstance(response, ProtoOAReconcileRes):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAReconcileRes, got {type(response).__name__}",
+            )
+
+        return [Position.from_proto(p) for p in response.position]
+
+    async def get_pending_orders(
+        self,
+        account_id: int,
+        timeout: float | None = None,
+    ) -> list[Order]:
+        """Get all pending orders.
+
+        Args:
+            account_id: The cTID trader account ID.
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            List of pending Order objects.
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOAOrderListReq(ctid_trader_account_id=account_id)
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        if not isinstance(response, ProtoOAOrderListRes):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOAOrderListRes, got {type(response).__name__}",
+            )
+
+        return [Order.from_proto(o) for o in response.order]
+
+    async def get_deals_by_position_id(
+        self,
+        account_id: int,
+        position_id: int,
+    ) -> list[Deal]:
+        """Get all deals for a specific position.
+
+        Args:
+            account_id: The cTID trader account ID.
+            position_id: The position ID to filter deals by.
+
+        Returns:
+            List of Deal objects associated with the position.
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOADealListByPositionIdReq(
+            ctid_trader_account_id=account_id,
+            position_id=position_id,
+        )
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=self._default_timeout,
+        )
+
+        if not isinstance(response, ProtoOADealListByPositionIdRes):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOADealListRes, got {type(response).__name__}",
+            )
+
+        return [Deal.from_proto(d) for d in response.deal]
+
+    async def get_deals(
+        self,
+        account_id: int,
+        from_timestamp: datetime,
+        to_timestamp: datetime,
+        timeout: float | None = None,
+    ) -> list[Deal]:
+        """Get historical deals.
+
+        Args:
+            account_id: The cTID trader account ID.
+            from_timestamp: Start of time range (inclusive).
+            to_timestamp: End of time range (inclusive).
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            List of Deal objects in the time range.
+
+        Note:
+            The maximum time range may be limited by the server.
+            For large ranges, consider paginating with smaller windows.
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOADealListReq(
+            ctid_trader_account_id=account_id,
+            from_timestamp=int(from_timestamp.timestamp() * 1000),
+            to_timestamp=int(to_timestamp.timestamp() * 1000),
+        )
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        if not isinstance(response, ProtoOADealListRes):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOADealListRes, got {type(response).__name__}",
+            )
+
+        return [Deal.from_proto(d) for d in response.deal]

ctrader_api_client/auth/__init__.py

@@ -0,0 +1,14 @@
+"""Authentication layer for cTrader API.
+
+This module provides application and account authentication,
+with automatic token refresh management.
+"""
+
+from .credentials import AccountCredentials
+from .manager import AuthManager
+
+
+__all__ = [
+    "AccountCredentials",
+    "AuthManager",
+]

ctrader_api_client/auth/credentials.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class AccountCredentials:
+    """Stores authentication credentials for a trading account.
+
+    Attributes:
+        account_id: The cTID trader account ID.
+        access_token: OAuth access token for API authentication.
+        refresh_token: OAuth refresh token for obtaining new access tokens.
+        expires_at: Unix epoch timestamp when the access token expires.
+    """
+
+    account_id: int
+    access_token: str
+    refresh_token: str
+    expires_at: float
+
+    def expires_soon(self, buffer_seconds: float = 300.0) -> bool:
+        """Check if the access token expires within the buffer period.
+
+        Args:
+            buffer_seconds: Number of seconds before expiry to consider "soon".
+                Defaults to 300 (5 minutes).
+
+        Returns:
+            True if the token expires within buffer_seconds from now.
+        """
+        return time.time() >= (self.expires_at - buffer_seconds)
+
+    def is_expired(self) -> bool:
+        """Check if the access token has already expired.
+
+        Returns:
+            True if the token has expired.
+        """
+        return time.time() >= self.expires_at
+
+    def time_until_expiry(self) -> float:
+        """Get seconds remaining until token expires.
+
+        Returns:
+            Seconds until expiry. Negative if already expired.
+        """
+        return self.expires_at - time.time()
+
+    def with_refreshed_tokens(
+        self,
+        access_token: str,
+        refresh_token: str,
+        expires_in: int,
+    ) -> AccountCredentials:
+        """Create a new instance with refreshed tokens.
+
+        Args:
+            access_token: The new access token.
+            refresh_token: The new refresh token.
+            expires_in: Seconds until the new access token expires.
+
+        Returns:
+            A new AccountCredentials instance with updated tokens.
+        """
+        return AccountCredentials(
+            account_id=self.account_id,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=time.time() + expires_in,
+        )