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

ctrader_api_client/_internal/proto/__init__.py

@@ -0,0 +1,320 @@
+"""Generated protobuf messages for cTrader Open API."""
+
+from .OpenApiCommonMessages import (
+    ProtoErrorRes,
+    ProtoHeartbeatEvent,
+    ProtoMessage,
+)
+from .OpenApiCommonModelMessages import (
+    ProtoErrorCode,
+    ProtoPayloadType,
+)
+from .OpenApiMessages import (
+    ProtoOAAccountAuthReq,
+    ProtoOAAccountAuthRes,
+    ProtoOAAccountDisconnectEvent,
+    ProtoOAAccountLogoutReq,
+    ProtoOAAccountLogoutRes,
+    ProtoOAAccountsTokenInvalidatedEvent,
+    ProtoOAAmendOrderReq,
+    ProtoOAAmendPositionSLTPReq,
+    ProtoOAApplicationAuthReq,
+    ProtoOAApplicationAuthRes,
+    ProtoOAAssetClassListReq,
+    ProtoOAAssetClassListRes,
+    ProtoOAAssetListReq,
+    ProtoOAAssetListRes,
+    ProtoOACancelOrderReq,
+    ProtoOACashFlowHistoryListReq,
+    ProtoOACashFlowHistoryListRes,
+    ProtoOAClientDisconnectEvent,
+    ProtoOAClosePositionReq,
+    ProtoOADealListByPositionIdReq,
+    ProtoOADealListByPositionIdRes,
+    ProtoOADealListReq,
+    ProtoOADealListRes,
+    ProtoOADealOffsetListReq,
+    ProtoOADealOffsetListRes,
+    ProtoOADepthEvent,
+    ProtoOAErrorRes,
+    ProtoOAExecutionEvent,
+    ProtoOAExpectedMarginReq,
+    ProtoOAExpectedMarginRes,
+    ProtoOAGetAccountListByAccessTokenReq,
+    ProtoOAGetAccountListByAccessTokenRes,
+    ProtoOAGetCtidProfileByTokenReq,
+    ProtoOAGetCtidProfileByTokenRes,
+    ProtoOAGetDynamicLeverageByIDReq,
+    ProtoOAGetDynamicLeverageByIDRes,
+    ProtoOAGetPositionUnrealizedPnLReq,
+    ProtoOAGetPositionUnrealizedPnLRes,
+    ProtoOAGetTickDataReq,
+    ProtoOAGetTickDataRes,
+    ProtoOAGetTrendbarsReq,
+    ProtoOAGetTrendbarsRes,
+    ProtoOAMarginCallListReq,
+    ProtoOAMarginCallListRes,
+    ProtoOAMarginCallTriggerEvent,
+    ProtoOAMarginCallUpdateEvent,
+    ProtoOAMarginCallUpdateReq,
+    ProtoOAMarginCallUpdateRes,
+    ProtoOAMarginChangedEvent,
+    ProtoOANewOrderReq,
+    ProtoOAOrderDetailsReq,
+    ProtoOAOrderDetailsRes,
+    ProtoOAOrderErrorEvent,
+    ProtoOAOrderListByPositionIdReq,
+    ProtoOAOrderListByPositionIdRes,
+    ProtoOAOrderListReq,
+    ProtoOAOrderListRes,
+    ProtoOAReconcileReq,
+    ProtoOAReconcileRes,
+    ProtoOARefreshTokenReq,
+    ProtoOARefreshTokenRes,
+    ProtoOASpotEvent,
+    ProtoOASubscribeDepthQuotesReq,
+    ProtoOASubscribeDepthQuotesRes,
+    ProtoOASubscribeLiveTrendbarReq,
+    ProtoOASubscribeLiveTrendbarRes,
+    ProtoOASubscribeSpotsReq,
+    ProtoOASubscribeSpotsRes,
+    ProtoOASymbolByIdReq,
+    ProtoOASymbolByIdRes,
+    ProtoOASymbolCategoryListReq,
+    ProtoOASymbolCategoryListRes,
+    ProtoOASymbolChangedEvent,
+    ProtoOASymbolsForConversionReq,
+    ProtoOASymbolsForConversionRes,
+    ProtoOASymbolsListReq,
+    ProtoOASymbolsListRes,
+    ProtoOATraderReq,
+    ProtoOATraderRes,
+    ProtoOATraderUpdatedEvent,
+    ProtoOATrailingSLChangedEvent,
+    ProtoOAUnsubscribeDepthQuotesReq,
+    ProtoOAUnsubscribeDepthQuotesRes,
+    ProtoOAUnsubscribeLiveTrendbarReq,
+    ProtoOAUnsubscribeLiveTrendbarRes,
+    ProtoOAUnsubscribeSpotsReq,
+    ProtoOAUnsubscribeSpotsRes,
+    ProtoOAv1PnLChangeEvent,
+    ProtoOAv1PnLChangeSubscribeReq,
+    ProtoOAv1PnLChangeSubscribeRes,
+    ProtoOAv1PnLChangeUnSubscribeReq,
+    ProtoOAv1PnLChangeUnSubscribeRes,
+    ProtoOAVersionReq,
+    ProtoOAVersionRes,
+)
+from .OpenApiModelMessages import (
+    ProtoOAAccessRights,
+    ProtoOAAccountType,
+    ProtoOAArchivedSymbol,
+    ProtoOAAsset,
+    ProtoOAAssetClass,
+    ProtoOABonusDepositWithdraw,
+    ProtoOAChangeBalanceType,
+    ProtoOAChangeBonusType,
+    ProtoOAClientPermissionScope,
+    ProtoOAClosePositionDetail,
+    ProtoOACommissionType,
+    ProtoOACtidProfile,
+    ProtoOACtidTraderAccount,
+    ProtoOADayOfWeek,
+    ProtoOADeal,
+    ProtoOADealOffset,
+    ProtoOADealStatus,
+    ProtoOADepositWithdraw,
+    ProtoOADepthQuote,
+    ProtoOADynamicLeverage,
+    ProtoOADynamicLeverageTier,
+    ProtoOAErrorCode,
+    ProtoOAExecutionType,
+    ProtoOAExpectedMargin,
+    ProtoOAHoliday,
+    ProtoOAInterval,
+    ProtoOALightSymbol,
+    ProtoOALimitedRiskMarginCalculationStrategy,
+    ProtoOAMarginCall,
+    ProtoOAMinCommissionType,
+    ProtoOANotificationType,
+    ProtoOAOrder,
+    ProtoOAOrderStatus,
+    ProtoOAOrderTriggerMethod,
+    ProtoOAOrderType,
+    ProtoOAPayloadType,
+    ProtoOAPosition,
+    ProtoOAPositionStatus,
+    ProtoOAPositionUnrealizedPnL,
+    ProtoOAQuoteType,
+    ProtoOAStopOutStrategy,
+    ProtoOASwapCalculationType,
+    ProtoOASymbol,
+    ProtoOASymbolCategory,
+    ProtoOASymbolDistanceType,
+    ProtoOATickData,
+    ProtoOATimeInForce,
+    ProtoOATotalMarginCalculationType,
+    ProtoOATradeData,
+    ProtoOATrader,
+    ProtoOATradeSide,
+    ProtoOATradingMode,
+    ProtoOATrendbar,
+    ProtoOATrendbarPeriod,
+)
+
+
+__all__ = [
+    "ProtoErrorCode",
+    "ProtoErrorRes",
+    "ProtoHeartbeatEvent",
+    "ProtoMessage",
+    "ProtoOAAccessRights",
+    "ProtoOAAccountAuthReq",
+    "ProtoOAAccountAuthRes",
+    "ProtoOAAccountDisconnectEvent",
+    "ProtoOAAccountLogoutReq",
+    "ProtoOAAccountLogoutRes",
+    "ProtoOAAccountType",
+    "ProtoOAAccountsTokenInvalidatedEvent",
+    "ProtoOAAmendOrderReq",
+    "ProtoOAAmendPositionSLTPReq",
+    "ProtoOAApplicationAuthReq",
+    "ProtoOAApplicationAuthRes",
+    "ProtoOAArchivedSymbol",
+    "ProtoOAAsset",
+    "ProtoOAAssetClass",
+    "ProtoOAAssetClassListReq",
+    "ProtoOAAssetClassListRes",
+    "ProtoOAAssetListReq",
+    "ProtoOAAssetListRes",
+    "ProtoOABonusDepositWithdraw",
+    "ProtoOACancelOrderReq",
+    "ProtoOACashFlowHistoryListReq",
+    "ProtoOACashFlowHistoryListRes",
+    "ProtoOAChangeBalanceType",
+    "ProtoOAChangeBonusType",
+    "ProtoOAClientDisconnectEvent",
+    "ProtoOAClientPermissionScope",
+    "ProtoOAClosePositionDetail",
+    "ProtoOAClosePositionReq",
+    "ProtoOACommissionType",
+    "ProtoOACtidProfile",
+    "ProtoOACtidTraderAccount",
+    "ProtoOADayOfWeek",
+    "ProtoOADeal",
+    "ProtoOADealListByPositionIdReq",
+    "ProtoOADealListByPositionIdRes",
+    "ProtoOADealListReq",
+    "ProtoOADealListRes",
+    "ProtoOADealOffset",
+    "ProtoOADealOffsetListReq",
+    "ProtoOADealOffsetListRes",
+    "ProtoOADealStatus",
+    "ProtoOADepositWithdraw",
+    "ProtoOADepthEvent",
+    "ProtoOADepthQuote",
+    "ProtoOADynamicLeverage",
+    "ProtoOADynamicLeverageTier",
+    "ProtoOAErrorCode",
+    "ProtoOAErrorRes",
+    "ProtoOAExecutionEvent",
+    "ProtoOAExecutionType",
+    "ProtoOAExpectedMargin",
+    "ProtoOAExpectedMarginReq",
+    "ProtoOAExpectedMarginRes",
+    "ProtoOAGetAccountListByAccessTokenReq",
+    "ProtoOAGetAccountListByAccessTokenRes",
+    "ProtoOAGetCtidProfileByTokenReq",
+    "ProtoOAGetCtidProfileByTokenRes",
+    "ProtoOAGetDynamicLeverageByIDReq",
+    "ProtoOAGetDynamicLeverageByIDRes",
+    "ProtoOAGetPositionUnrealizedPnLReq",
+    "ProtoOAGetPositionUnrealizedPnLRes",
+    "ProtoOAGetTickDataReq",
+    "ProtoOAGetTickDataRes",
+    "ProtoOAGetTrendbarsReq",
+    "ProtoOAGetTrendbarsRes",
+    "ProtoOAHoliday",
+    "ProtoOAInterval",
+    "ProtoOALightSymbol",
+    "ProtoOALimitedRiskMarginCalculationStrategy",
+    "ProtoOAMarginCall",
+    "ProtoOAMarginCallListReq",
+    "ProtoOAMarginCallListRes",
+    "ProtoOAMarginCallTriggerEvent",
+    "ProtoOAMarginCallUpdateEvent",
+    "ProtoOAMarginCallUpdateReq",
+    "ProtoOAMarginCallUpdateRes",
+    "ProtoOAMarginChangedEvent",
+    "ProtoOAMinCommissionType",
+    "ProtoOANewOrderReq",
+    "ProtoOANotificationType",
+    "ProtoOAOrder",
+    "ProtoOAOrderDetailsReq",
+    "ProtoOAOrderDetailsRes",
+    "ProtoOAOrderErrorEvent",
+    "ProtoOAOrderListByPositionIdReq",
+    "ProtoOAOrderListByPositionIdRes",
+    "ProtoOAOrderListReq",
+    "ProtoOAOrderListRes",
+    "ProtoOAOrderStatus",
+    "ProtoOAOrderTriggerMethod",
+    "ProtoOAOrderType",
+    "ProtoOAPayloadType",
+    "ProtoOAPosition",
+    "ProtoOAPositionStatus",
+    "ProtoOAPositionUnrealizedPnL",
+    "ProtoOAQuoteType",
+    "ProtoOAReconcileReq",
+    "ProtoOAReconcileRes",
+    "ProtoOARefreshTokenReq",
+    "ProtoOARefreshTokenRes",
+    "ProtoOASpotEvent",
+    "ProtoOAStopOutStrategy",
+    "ProtoOASubscribeDepthQuotesReq",
+    "ProtoOASubscribeDepthQuotesRes",
+    "ProtoOASubscribeLiveTrendbarReq",
+    "ProtoOASubscribeLiveTrendbarRes",
+    "ProtoOASubscribeSpotsReq",
+    "ProtoOASubscribeSpotsRes",
+    "ProtoOASwapCalculationType",
+    "ProtoOASymbol",
+    "ProtoOASymbolByIdReq",
+    "ProtoOASymbolByIdRes",
+    "ProtoOASymbolCategory",
+    "ProtoOASymbolCategoryListReq",
+    "ProtoOASymbolCategoryListRes",
+    "ProtoOASymbolChangedEvent",
+    "ProtoOASymbolDistanceType",
+    "ProtoOASymbolsForConversionReq",
+    "ProtoOASymbolsForConversionRes",
+    "ProtoOASymbolsListReq",
+    "ProtoOASymbolsListRes",
+    "ProtoOATickData",
+    "ProtoOATimeInForce",
+    "ProtoOATotalMarginCalculationType",
+    "ProtoOATradeData",
+    "ProtoOATradeSide",
+    "ProtoOATrader",
+    "ProtoOATraderReq",
+    "ProtoOATraderRes",
+    "ProtoOATraderUpdatedEvent",
+    "ProtoOATradingMode",
+    "ProtoOATrailingSLChangedEvent",
+    "ProtoOATrendbar",
+    "ProtoOATrendbarPeriod",
+    "ProtoOAUnsubscribeDepthQuotesReq",
+    "ProtoOAUnsubscribeDepthQuotesRes",
+    "ProtoOAUnsubscribeLiveTrendbarReq",
+    "ProtoOAUnsubscribeLiveTrendbarRes",
+    "ProtoOAUnsubscribeSpotsReq",
+    "ProtoOAUnsubscribeSpotsRes",
+    "ProtoOAVersionReq",
+    "ProtoOAVersionRes",
+    "ProtoOAv1PnLChangeEvent",
+    "ProtoOAv1PnLChangeSubscribeReq",
+    "ProtoOAv1PnLChangeSubscribeRes",
+    "ProtoOAv1PnLChangeUnSubscribeReq",
+    "ProtoOAv1PnLChangeUnSubscribeRes",
+    "ProtoPayloadType",
+]

ctrader_api_client/_internal/serialization.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import struct
+
+import betterproto
+from anyio.abc import ByteReceiveStream
+
+from ..exceptions import FramingError
+
+
+# Big-endian unsigned 4-byte integer format
+_LENGTH_PREFIX_FORMAT = ">I"
+_LENGTH_PREFIX_SIZE = 4
+
+# Safety limit to prevent memory exhaustion from malformed messages
+_MAX_MESSAGE_SIZE = 1024 * 1024  # 1MB
+
+
+def encode_with_length_prefix(message: betterproto.Message) -> bytes:
+    """Encode a protobuf message with 4-byte big-endian length prefix.
+
+    Args:
+        message: A betterproto message to encode.
+
+    Returns:
+        The serialized message prefixed with its length as a 4-byte big-endian integer.
+    """
+    payload = bytes(message)
+    length_prefix = struct.pack(_LENGTH_PREFIX_FORMAT, len(payload))
+    return length_prefix + payload
+
+
+async def read_exact(stream: ByteReceiveStream, num_bytes: int) -> bytes:
+    """Read exactly num_bytes from the stream.
+
+    Args:
+        stream: An async byte stream to read from.
+        num_bytes: The exact number of bytes to read.
+
+    Returns:
+        Exactly num_bytes of data.
+
+    Raises:
+        FramingError: If the stream closes before num_bytes are read.
+    """
+    chunks: list[bytes] = []
+    bytes_remaining = num_bytes
+
+    while bytes_remaining > 0:
+        chunk = await stream.receive(bytes_remaining)
+        if not chunk:
+            received = num_bytes - bytes_remaining
+            raise FramingError(expected_bytes=num_bytes, received_bytes=received)
+        chunks.append(chunk)
+        bytes_remaining -= len(chunk)
+
+    return b"".join(chunks)
+
+
+async def read_framed_message(stream: ByteReceiveStream) -> bytes:
+    """Read a length-prefixed message from the stream.
+
+    Reads a 4-byte big-endian length prefix, then reads that many bytes as the payload.
+
+    Args:
+        stream: An async byte stream to read from.
+
+    Returns:
+        The message payload (without the length prefix).
+
+    Raises:
+        FramingError: If the stream closes before the complete message is read,
+            or if the message size exceeds _MAX_MESSAGE_SIZE.
+    """
+    # Read the 4-byte length prefix
+    length_bytes = await read_exact(stream, _LENGTH_PREFIX_SIZE)
+    (length,) = struct.unpack(_LENGTH_PREFIX_FORMAT, length_bytes)
+
+    # Validate message size
+    if length > _MAX_MESSAGE_SIZE:
+        raise FramingError(expected_bytes=_MAX_MESSAGE_SIZE, received_bytes=length)
+
+    # Read the payload
+    return await read_exact(stream, length)

ctrader_api_client/api/__init__.py

@@ -0,0 +1,21 @@
+"""Domain-specific API classes for cTrader operations.
+
+This module provides namespaced APIs for different aspects of trading:
+- AccountsAPI: Account information retrieval
+- SymbolsAPI: Symbol lookup and search
+- TradingAPI: Order placement and position management
+- MarketDataAPI: Market data subscriptions and historical data
+"""
+
+from .accounts import AccountsAPI
+from .market_data import MarketDataAPI
+from .symbols import SymbolsAPI
+from .trading import TradingAPI
+
+
+__all__ = [
+    "AccountsAPI",
+    "MarketDataAPI",
+    "SymbolsAPI",
+    "TradingAPI",
+]

ctrader_api_client/api/accounts.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._internal.proto import (
+    ProtoOATraderReq,
+    ProtoOATraderRes,
+)
+from ..exceptions import APIError
+from ..models import Account
+
+
+if TYPE_CHECKING:
+    from ..connection import Protocol
+
+
+class AccountsAPI:
+    """Account information operations.
+
+    Provides methods to retrieve account/trader details.
+
+    Example:
+        ```python
+        account = await client.accounts.get_trader(account_id)
+        print(f"Balance: {account.get_balance()}")
+        print(f"Leverage: {account.get_leverage()}")
+        ```
+    """
+
+    def __init__(self, protocol: Protocol, default_timeout: float = 30.0) -> None:
+        """Initialize the accounts 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 get_trader(
+        self,
+        account_id: int,
+        timeout: float | None = None,
+    ) -> Account:
+        """Get full account/trader information.
+
+        Args:
+            account_id: The cTID trader account ID.
+            timeout: Request timeout (uses default if None).
+
+        Returns:
+            Full Account details including balance, leverage, etc.
+
+        Raises:
+            APIError: If request fails.
+            CTraderConnectionTimeoutError: If request times out.
+        """
+        request = ProtoOATraderReq(ctid_trader_account_id=account_id)
+
+        response = await self._protocol.send_request(
+            request,
+            timeout=timeout or self._default_timeout,
+        )
+
+        if not isinstance(response, ProtoOATraderRes):
+            raise APIError(
+                error_code="UNEXPECTED_RESPONSE",
+                description=f"Expected ProtoOATraderRes, got {type(response).__name__}",
+            )
+
+        return Account.from_proto(response.trader)