ctrader-api-client 0.6.0__tar.gz → 0.7.1__tar.gz

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.1}/.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(git -C \"/home/tek/Desktop/Algo Trading/Live Trading/cTrader/ctrader-api-client\" log --oneline -10)"
+      "Bash(git -C \"/home/tek/Desktop/Algo Trading/Live Trading/cTrader/ctrader-api-client\" log --oneline -10)",
+      "Bash(git add *)"
     ]
   }
 }

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.6.0
+Version: 0.7.1
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -51,8 +51,13 @@ pip install ctrader-api-client
 
 ```python
 import asyncio
-from ctrader_api_client import CTraderClient, ClientConfig
-from ctrader_api_client.events import ReadyEvent, SpotEvent
+from ctrader_api_client import (
+    AccountCredentials,
+    ClientConfig,
+    CTraderClient,
+    ReadyEvent,
+    SpotEvent,
+)
 
 config = ClientConfig(
     client_id="your_client_id",
@@ -67,21 +72,23 @@ async def on_price(event: SpotEvent):
     print(f"Price update: {event.bid}/{event.ask}")
 
 
-@client.on(ReadyEvent)
-async def on_ready(event: ReadyEvent):
-    """Called when account is authenticated and ready."""
-    await client.market_data.subscribe_spots(event.account_id, [270])
-
-
 async def main():
     async with client:
-        await client.auth.authenticate_app()
-        await client.auth.authenticate_by_trader_login(
+        account_id = await client.accounts.resolve_account_id(
+            "your_access_token",
             trader_login=12345678,
-            access_token="your_access_token",
-            refresh_token="your_refresh_token",
-            expires_at=1778617423,
         )
+        await client.auth.authenticate_trader(
+            AccountCredentials(
+                account_id=account_id,
+                access_token="your_access_token",
+                refresh_token="your_refresh_token",
+                expires_at=1778617423,
+            )
+        )
+
+        # Subscribe once. The client re-applies this after any reconnection.
+        await client.market_data.subscribe_spots(account_id, [270])
 
         # Keep running to receive events
         await asyncio.Event().wait()
@@ -108,15 +115,19 @@ For production applications, implement the OAuth flow according to the [cTrader
 ### Authentication
 
 ```python
-# Authenticate the application
-await client.auth.authenticate_app()
+# The application is authenticated as the client connects.
+
+# Discover the account behind a trader login
+account_id = await client.accounts.resolve_account_id("...", trader_login=12345678)
 
 # Authenticate a trading account
-creds = await client.auth.authenticate_by_trader_login(
-    trader_login=12345678,
-    access_token="...",
-    refresh_token="...",
-    expires_at=1778617423,
+await client.auth.authenticate_trader(
+    AccountCredentials(
+        account_id=account_id,
+        access_token="...",
+        refresh_token="...",
+        expires_at=1778617423,
+    )
 )
 
 # Tokens are automatically refreshed before expiry. A refresh that fails is
@@ -124,6 +135,75 @@ creds = await client.auth.authenticate_by_trader_login(
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
 ```
 
+### Persisting Rotated Tokens
+
+Every refresh issues a new access **and** refresh token, and invalidates the old
+pair immediately. Pass a `TokenStore` and the client writes each new pair through
+as it is issued:
+
+```python
+from ctrader_api_client import AccountCredentials, CTraderClient, TokenStore
+
+
+class PostgresTokenStore(TokenStore):
+    def __init__(self, pool):
+        self._pool = pool
+
+    async def save(self, credentials: AccountCredentials) -> None:
+        await self._pool.execute(
+            """
+            INSERT INTO ctrader_tokens (account_id, access_token, refresh_token, expires_at)
+            VALUES ($1, $2, $3, $4)
+            ON CONFLICT (account_id) DO UPDATE SET
+                access_token = EXCLUDED.access_token,
+                refresh_token = EXCLUDED.refresh_token,
+                expires_at = EXCLUDED.expires_at
+            """,
+            credentials.account_id,
+            credentials.access_token,
+            credentials.refresh_token,
+            credentials.expires_at,
+        )
+
+    # Not part of the protocol. The client never reads the store; you do.
+    async def load(self, account_id: int) -> AccountCredentials | None:
+        row = await self._pool.fetchrow(
+            "SELECT access_token, refresh_token, expires_at FROM ctrader_tokens WHERE account_id = $1",
+            account_id,
+        )
+        if row is None:
+            return None
+        return AccountCredentials(account_id=account_id, **dict(row))
+
+
+client = CTraderClient(config, token_store=PostgresTokenStore(pool))
+```
+
+The save happens before the new token is put to use. A save that raises aborts
+that refresh, which is reported as a `TokenRefreshFailedEvent` and retried on the
+next check interval, so a transient storage outage recovers on its own.
+
+The protocol is write-only, because writing is the half the client has to do for
+you: rotation happens mid-session, at a moment you cannot observe. Reading back is
+yours, since only you know which accounts a given process is responsible for:
+
+```python
+store = PostgresTokenStore(pool)
+client = CTraderClient(config, token_store=store)
+
+async with client:
+    stored = await store.load(account_id)
+    if stored is None:
+        stored = AccountCredentials(
+            account_id=account_id,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+    await client.auth.authenticate_trader(stored)
+```
+
 ### Market Data
 
 ```python
@@ -142,8 +222,7 @@ bars = await client.market_data.get_trendbars(
 ### Trading
 
 ```python
-from ctrader_api_client.models import NewOrderRequest, ClosePositionRequest
-from ctrader_api_client.enums import OrderType, OrderSide
+from ctrader_api_client import ClosePositionRequest, NewOrderRequest, OrderSide, OrderType
 
 # Place a market order
 request = NewOrderRequest(
@@ -168,11 +247,12 @@ await client.trading.close_position(account_id, close_position)
 ### Event Handling
 
 ```python
-from ctrader_api_client.events import (
-    SpotEvent,
+from ctrader_api_client import (
     ExecutionEvent,
     ReadyEvent,
     ReconnectedEvent,
+    SpotEvent,
+    SubscriptionRestoreFailedEvent,
     TokenRefreshFailedEvent,
 )
 
@@ -187,10 +267,11 @@ async def on_execution(event: ExecutionEvent):
     print(f"Order {event.order_id}: {event.execution_type}")
 
 # Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
+# Subscriptions are already restored by this point; use it to reconcile your own state.
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
-    # Set up subscriptions here
-    await client.market_data.subscribe_spots(event.account_id, symbols)
+    if event.is_reconnect:
+        positions = await client.trading.get_open_positions(event.account_id)
 
 # Connection restored
 @client.on(ReconnectedEvent)
@@ -202,6 +283,11 @@ async def on_reconnected(event: ReconnectedEvent):
 @client.on(TokenRefreshFailedEvent, account_id=account_id)
 async def on_refresh_failed(event: TokenRefreshFailedEvent):
     print(f"Token refresh failed for {event.account_id}: {event.error}")
+
+# Market data could not be re-applied after a reconnection (retried on the next one)
+@client.on(SubscriptionRestoreFailedEvent, account_id=account_id)
+async def on_restore_failed(event: SubscriptionRestoreFailedEvent):
+    print(f"Account {event.account_id} is missing market data: {event.error}")
 ```
 
 ### Symbols
@@ -231,23 +317,28 @@ The client automatically handles connection drops:
 
 1. Reconnects with exponential backoff
 2. Re-authenticates the app and all accounts
-3. Emits `ReadyEvent` for each restored account (for resubscribing to market data)
-4. Emits `ReconnectedEvent` with summary of restored/failed accounts
+3. Re-applies each account's market data subscriptions
+4. Emits `ReadyEvent` for each restored account
+5. Emits `ReconnectedEvent` with summary of restored/failed accounts
 
 It also handles **server-side account disconnects** (e.g. a broker dropping the
 account session over the weekend while the connection stays up): the account is
-re-authenticated on the existing connection with backoff until it succeeds, then
-a `ReadyEvent` is emitted so subscriptions can be restored. Account
+re-authenticated on the existing connection with backoff until it succeeds, its
+subscriptions are re-applied, and then a `ReadyEvent` is emitted. Account
 authorization is observable via `client.is_account_authorized(account_id)`,
 which is distinct from the transport-level `client.is_connected`.
 
-Use `ReadyEvent` to set up subscriptions that persist across reconnections.
+Subscribe once, when you first authenticate. The client remembers what each
+account asked for and re-applies it before announcing the account as ready, so
+do not re-subscribe from a `ReadyEvent` handler — the server rejects a duplicate
+subscription. If restoration fails it stops at the first failure and emits a
+`SubscriptionRestoreFailedEvent`, keeping the intent so the next reconnection
+tries again.
 
 ## Configuration
 
 ```python
-from ctrader_api_client import ClientConfig
-from ctrader_api_client.auth import ReauthPolicy, RefreshPolicy
+from ctrader_api_client import ClientConfig, ReauthPolicy, RefreshPolicy
 
 config = ClientConfig(
     client_id="your_client_id",

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.1}/README.md

@@ -32,8 +32,13 @@ pip install ctrader-api-client
 
 ```python
 import asyncio
-from ctrader_api_client import CTraderClient, ClientConfig
-from ctrader_api_client.events import ReadyEvent, SpotEvent
+from ctrader_api_client import (
+    AccountCredentials,
+    ClientConfig,
+    CTraderClient,
+    ReadyEvent,
+    SpotEvent,
+)
 
 config = ClientConfig(
     client_id="your_client_id",
@@ -48,21 +53,23 @@ async def on_price(event: SpotEvent):
     print(f"Price update: {event.bid}/{event.ask}")
 
 
-@client.on(ReadyEvent)
-async def on_ready(event: ReadyEvent):
-    """Called when account is authenticated and ready."""
-    await client.market_data.subscribe_spots(event.account_id, [270])
-
-
 async def main():
     async with client:
-        await client.auth.authenticate_app()
-        await client.auth.authenticate_by_trader_login(
+        account_id = await client.accounts.resolve_account_id(
+            "your_access_token",
             trader_login=12345678,
-            access_token="your_access_token",
-            refresh_token="your_refresh_token",
-            expires_at=1778617423,
         )
+        await client.auth.authenticate_trader(
+            AccountCredentials(
+                account_id=account_id,
+                access_token="your_access_token",
+                refresh_token="your_refresh_token",
+                expires_at=1778617423,
+            )
+        )
+
+        # Subscribe once. The client re-applies this after any reconnection.
+        await client.market_data.subscribe_spots(account_id, [270])
 
         # Keep running to receive events
         await asyncio.Event().wait()
@@ -89,15 +96,19 @@ For production applications, implement the OAuth flow according to the [cTrader
 ### Authentication
 
 ```python
-# Authenticate the application
-await client.auth.authenticate_app()
+# The application is authenticated as the client connects.
+
+# Discover the account behind a trader login
+account_id = await client.accounts.resolve_account_id("...", trader_login=12345678)
 
 # Authenticate a trading account
-creds = await client.auth.authenticate_by_trader_login(
-    trader_login=12345678,
-    access_token="...",
-    refresh_token="...",
-    expires_at=1778617423,
+await client.auth.authenticate_trader(
+    AccountCredentials(
+        account_id=account_id,
+        access_token="...",
+        refresh_token="...",
+        expires_at=1778617423,
+    )
 )
 
 # Tokens are automatically refreshed before expiry. A refresh that fails is
@@ -105,6 +116,75 @@ creds = await client.auth.authenticate_by_trader_login(
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
 ```
 
+### Persisting Rotated Tokens
+
+Every refresh issues a new access **and** refresh token, and invalidates the old
+pair immediately. Pass a `TokenStore` and the client writes each new pair through
+as it is issued:
+
+```python
+from ctrader_api_client import AccountCredentials, CTraderClient, TokenStore
+
+
+class PostgresTokenStore(TokenStore):
+    def __init__(self, pool):
+        self._pool = pool
+
+    async def save(self, credentials: AccountCredentials) -> None:
+        await self._pool.execute(
+            """
+            INSERT INTO ctrader_tokens (account_id, access_token, refresh_token, expires_at)
+            VALUES ($1, $2, $3, $4)
+            ON CONFLICT (account_id) DO UPDATE SET
+                access_token = EXCLUDED.access_token,
+                refresh_token = EXCLUDED.refresh_token,
+                expires_at = EXCLUDED.expires_at
+            """,
+            credentials.account_id,
+            credentials.access_token,
+            credentials.refresh_token,
+            credentials.expires_at,
+        )
+
+    # Not part of the protocol. The client never reads the store; you do.
+    async def load(self, account_id: int) -> AccountCredentials | None:
+        row = await self._pool.fetchrow(
+            "SELECT access_token, refresh_token, expires_at FROM ctrader_tokens WHERE account_id = $1",
+            account_id,
+        )
+        if row is None:
+            return None
+        return AccountCredentials(account_id=account_id, **dict(row))
+
+
+client = CTraderClient(config, token_store=PostgresTokenStore(pool))
+```
+
+The save happens before the new token is put to use. A save that raises aborts
+that refresh, which is reported as a `TokenRefreshFailedEvent` and retried on the
+next check interval, so a transient storage outage recovers on its own.
+
+The protocol is write-only, because writing is the half the client has to do for
+you: rotation happens mid-session, at a moment you cannot observe. Reading back is
+yours, since only you know which accounts a given process is responsible for:
+
+```python
+store = PostgresTokenStore(pool)
+client = CTraderClient(config, token_store=store)
+
+async with client:
+    stored = await store.load(account_id)
+    if stored is None:
+        stored = AccountCredentials(
+            account_id=account_id,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+    await client.auth.authenticate_trader(stored)
+```
+
 ### Market Data
 
 ```python
@@ -123,8 +203,7 @@ bars = await client.market_data.get_trendbars(
 ### Trading
 
 ```python
-from ctrader_api_client.models import NewOrderRequest, ClosePositionRequest
-from ctrader_api_client.enums import OrderType, OrderSide
+from ctrader_api_client import ClosePositionRequest, NewOrderRequest, OrderSide, OrderType
 
 # Place a market order
 request = NewOrderRequest(
@@ -149,11 +228,12 @@ await client.trading.close_position(account_id, close_position)
 ### Event Handling
 
 ```python
-from ctrader_api_client.events import (
-    SpotEvent,
+from ctrader_api_client import (
     ExecutionEvent,
     ReadyEvent,
     ReconnectedEvent,
+    SpotEvent,
+    SubscriptionRestoreFailedEvent,
     TokenRefreshFailedEvent,
 )
 
@@ -168,10 +248,11 @@ async def on_execution(event: ExecutionEvent):
     print(f"Order {event.order_id}: {event.execution_type}")
 
 # Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
+# Subscriptions are already restored by this point; use it to reconcile your own state.
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
-    # Set up subscriptions here
-    await client.market_data.subscribe_spots(event.account_id, symbols)
+    if event.is_reconnect:
+        positions = await client.trading.get_open_positions(event.account_id)
 
 # Connection restored
 @client.on(ReconnectedEvent)
@@ -183,6 +264,11 @@ async def on_reconnected(event: ReconnectedEvent):
 @client.on(TokenRefreshFailedEvent, account_id=account_id)
 async def on_refresh_failed(event: TokenRefreshFailedEvent):
     print(f"Token refresh failed for {event.account_id}: {event.error}")
+
+# Market data could not be re-applied after a reconnection (retried on the next one)
+@client.on(SubscriptionRestoreFailedEvent, account_id=account_id)
+async def on_restore_failed(event: SubscriptionRestoreFailedEvent):
+    print(f"Account {event.account_id} is missing market data: {event.error}")
 ```
 
 ### Symbols
@@ -212,23 +298,28 @@ The client automatically handles connection drops:
 
 1. Reconnects with exponential backoff
 2. Re-authenticates the app and all accounts
-3. Emits `ReadyEvent` for each restored account (for resubscribing to market data)
-4. Emits `ReconnectedEvent` with summary of restored/failed accounts
+3. Re-applies each account's market data subscriptions
+4. Emits `ReadyEvent` for each restored account
+5. Emits `ReconnectedEvent` with summary of restored/failed accounts
 
 It also handles **server-side account disconnects** (e.g. a broker dropping the
 account session over the weekend while the connection stays up): the account is
-re-authenticated on the existing connection with backoff until it succeeds, then
-a `ReadyEvent` is emitted so subscriptions can be restored. Account
+re-authenticated on the existing connection with backoff until it succeeds, its
+subscriptions are re-applied, and then a `ReadyEvent` is emitted. Account
 authorization is observable via `client.is_account_authorized(account_id)`,
 which is distinct from the transport-level `client.is_connected`.
 
-Use `ReadyEvent` to set up subscriptions that persist across reconnections.
+Subscribe once, when you first authenticate. The client remembers what each
+account asked for and re-applies it before announcing the account as ready, so
+do not re-subscribe from a `ReadyEvent` handler — the server rejects a duplicate
+subscription. If restoration fails it stops at the first failure and emits a
+`SubscriptionRestoreFailedEvent`, keeping the intent so the next reconnection
+tries again.
 
 ## Configuration
 
 ```python
-from ctrader_api_client import ClientConfig
-from ctrader_api_client.auth import ReauthPolicy, RefreshPolicy
+from ctrader_api_client import ClientConfig, ReauthPolicy, RefreshPolicy
 
 config = ClientConfig(
     client_id="your_client_id",

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.1}/docs/api/accounts.md

@@ -11,6 +11,8 @@ Access via `client.accounts`.
       show_source: false
       members:
         - get_trader
+        - list_by_token
+        - resolve_account_id
 
 ## Usage Examples
 
@@ -27,15 +29,17 @@ print(f"Broker name: {account.broker_name}")
 
 ## Account Discovery
 
-To discover available accounts for an access token, use the auth manager:
+The accounts an access token covers can be listed without authenticating any of
+them:
 
 ```python
 # Get all accounts associated with a token
-accounts = await client.auth.get_accounts(access_token)
-
-for acc in accounts:
+for acc in await client.accounts.list_by_token(access_token):
     print(f"Login: {acc.trader_login}, Account ID: {acc.account_id}")
     print(f"  Live: {acc.is_live}, Broker: {acc.broker_name}")
+
+# Or resolve a single login straight to its account ID
+account_id = await client.accounts.resolve_account_id(access_token, trader_login=12345678)
 ```
 
 ## Related

ctrader_api_client-0.7.1/docs/api/client.md

@@ -0,0 +1,133 @@
+# Client
+
+The main entry point for interacting with the cTrader API.
+
+A client is used inside `async with`. The block owns the connection and the
+background tasks that keep it alive, so leaving it — normally or by exception —
+winds them down, and a background task that dies is raised at the end of the
+block rather than discovered later.
+
+## CTraderClient
+
+::: ctrader_api_client.CTraderClient
+    options:
+      show_source: false
+      members:
+        - __init__
+        - from_graph
+        - "on"
+        - "off"
+        - auth
+        - accounts
+        - symbols
+        - trading
+        - market_data
+        - is_connected
+        - protocol
+
+## Composition
+
+`CTraderClient(config)` assembles its own collaborators, which is all most
+callers need. When you have to substitute one of them, assemble the graph
+yourself and hand it over:
+
+```python
+from ctrader_api_client import CTraderClient
+from ctrader_api_client.composition import build_graph
+
+graph = build_graph(config, clock=my_clock)
+client = CTraderClient.from_graph(graph)
+```
+
+::: ctrader_api_client.composition.build_graph
+    options:
+      show_source: false
+
+::: ctrader_api_client.composition.ClientGraph
+    options:
+      show_source: false
+
+## ClientConfig
+
+::: ctrader_api_client.ClientConfig
+    options:
+      show_source: false
+
+## Authentication Policies
+
+Token-refresh and session-recovery timing, passed via
+`ClientConfig(refresh_policy=..., reauth_policy=...)`.
+
+::: ctrader_api_client.auth.RefreshPolicy
+    options:
+      show_source: false
+
+::: ctrader_api_client.auth.ReauthPolicy
+    options:
+      show_source: false
+
+## Authentication
+
+The `client.auth` property provides access to authentication operations. The
+application is authenticated as the client connects, so what is left here is
+authenticating trading accounts and asking after the sessions they hold.
+
+::: ctrader_api_client.auth.AuthManager
+    options:
+      show_source: false
+      members:
+        - authenticate_trader
+        - is_account_authorized
+        - get_credentials
+        - all_credentials
+        - remove_account
+        - is_app_authenticated
+        - authenticated_accounts
+        - authorized_accounts
+
+## AccountCredentials
+
+::: ctrader_api_client.auth.AccountCredentials
+    options:
+      show_source: false
+
+## TokenStore
+
+Passed as `CTraderClient(config, token_store=...)`. cTrader rotates both tokens
+on every refresh and invalidates the old pair immediately, so a process that
+restarts holding the pair it was originally given can no longer authenticate.
+
+::: ctrader_api_client.auth.TokenStore
+    options:
+      show_source: false
+      members: true
+
+The contract is write-only, because writing is the half the client has to do for
+you: rotation happens mid-session, at a moment you cannot observe. Reading back at
+startup is yours, since only you know which accounts a given process is
+responsible for. Nothing stops the same class from doing both:
+
+```python
+class PostgresTokenStore(TokenStore):
+    async def save(self, credentials: AccountCredentials) -> None:
+        ...  # required by the protocol, called by the client
+
+    async def load(self, account_id: int) -> AccountCredentials | None:
+        ...  # not part of the protocol, called by you at startup
+
+
+store = PostgresTokenStore(pool)
+client = CTraderClient(config, token_store=store)
+
+async with client:
+    stored = await store.load(account_id)
+    if stored is None:
+        stored = AccountCredentials(
+            account_id=account_id,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+    await client.auth.authenticate_trader(stored)
+```

{ctrader_api_client-0.6.0 → ctrader_api_client-0.7.1}/docs/api/enums.md

@@ -3,7 +3,7 @@
 Enumeration types used throughout the API.
 
 ```python
-from ctrader_api_client.enums import OrderType, OrderSide, ExecutionType
+from ctrader_api_client import ExecutionType, OrderSide, OrderType
 ```
 
 ## Trading Enums
@@ -51,12 +51,6 @@ from ctrader_api_client.enums import OrderType, OrderSide, ExecutionType
 ## Account Enums
 
 
-::: ctrader_api_client.enums.Environment
-    options:
-      show_source: false
-      members: true
-
-
 ::: ctrader_api_client.enums.AccessRights
     options:
       show_source: false