ctrader-api-client 0.10.0__tar.gz → 0.12.0__tar.gz

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrader-api-client
-Version: 0.10.0
+Version: 0.12.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -133,6 +133,9 @@ await client.auth.authenticate_trader(
 # Tokens are automatically refreshed before expiry. A refresh that fails is
 # retried on the next check rather than dropping the session, and surfaces as a
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
+# An access token that has already expired is refreshed before the account is
+# authenticated, so a process that starts after the expiry needs no new token.
+# Only a refresh token the server refuses raises TokenExpiredError.
 ```
 
 ### Persisting Rotated Tokens
@@ -249,6 +252,7 @@ await client.trading.close_position(account_id, close_position)
 ```python
 from ctrader_api_client import (
     ExecutionEvent,
+    ExecutionType,
     ReadyEvent,
     ReconnectedEvent,
     SpotEvent,
@@ -261,10 +265,16 @@ from ctrader_api_client import (
 async def on_spot(event: SpotEvent):
     print(f"{event.bid}/{event.ask}")
 
-# Order executions
+# Order executions. The event carries the Order, Position and Deal models
+# that the trading API returns. Each one is None when the server sent none.
 @client.on(ExecutionEvent, account_id=account_id)
 async def on_execution(event: ExecutionEvent):
-    print(f"Order {event.order_id}: {event.execution_type}")
+    if event.order is None:
+        return  # A swap or a deposit has no order.
+    print(f"Order {event.order.order_id}: {event.execution_type}")
+    if event.execution_type is ExecutionType.ORDER_FILLED and event.order.is_closing_order:
+        # The order type says why the position closed.
+        print(f"Closed by {event.order.order_type.name}, stop-out={event.order.is_stop_out}")
 
 # 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.

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/README.md

@@ -114,6 +114,9 @@ await client.auth.authenticate_trader(
 # Tokens are automatically refreshed before expiry. A refresh that fails is
 # retried on the next check rather than dropping the session, and surfaces as a
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
+# An access token that has already expired is refreshed before the account is
+# authenticated, so a process that starts after the expiry needs no new token.
+# Only a refresh token the server refuses raises TokenExpiredError.
 ```
 
 ### Persisting Rotated Tokens
@@ -230,6 +233,7 @@ await client.trading.close_position(account_id, close_position)
 ```python
 from ctrader_api_client import (
     ExecutionEvent,
+    ExecutionType,
     ReadyEvent,
     ReconnectedEvent,
     SpotEvent,
@@ -242,10 +246,16 @@ from ctrader_api_client import (
 async def on_spot(event: SpotEvent):
     print(f"{event.bid}/{event.ask}")
 
-# Order executions
+# Order executions. The event carries the Order, Position and Deal models
+# that the trading API returns. Each one is None when the server sent none.
 @client.on(ExecutionEvent, account_id=account_id)
 async def on_execution(event: ExecutionEvent):
-    print(f"Order {event.order_id}: {event.execution_type}")
+    if event.order is None:
+        return  # A swap or a deposit has no order.
+    print(f"Order {event.order.order_id}: {event.execution_type}")
+    if event.execution_type is ExecutionType.ORDER_FILLED and event.order.is_closing_order:
+        # The order type says why the position closed.
+        print(f"Closed by {event.order.order_type.name}, stop-out={event.order.is_stop_out}")
 
 # 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.

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/api/client.md

@@ -70,7 +70,9 @@ Token-refresh and session-recovery timing, passed via
 
 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.
+authenticating trading accounts and asking after the sessions they hold. An
+account whose access token has expired is refreshed before it is authenticated,
+so the refresh token in the credentials is what a restart depends on.
 
 ::: ctrader_api_client.auth.AuthManager
     options:

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/api/events.md

@@ -14,7 +14,7 @@ async def on_spot(event: SpotEvent):
 
 @client.on(ExecutionEvent, account_id=12345)  # Filter by account
 async def on_execution(event: ExecutionEvent):
-    print(f"Order {event.order_id}: {event.execution_type}")
+    print(f"Order {event.order.order_id}: {event.execution_type}")
 ```
 
 ### Filtering
@@ -24,7 +24,7 @@ Different events support different filters:
 | Event | `account_id` | `symbol_id` |
 |-------|--------------|-------------|
 | SpotEvent | Yes | Yes |
-| ExecutionEvent | Yes | Yes |
+| ExecutionEvent | Yes | No |
 | DepthEvent | Yes | Yes |
 | ReadyEvent | Yes | No |
 | OrderErrorEvent | Yes | No |
@@ -72,6 +72,30 @@ async def on_spot(event: SpotEvent):
 
 ## Trading Events
 
+An execution event carries the `Order`, `Position` and `Deal` models that the
+trading API returns. Each one is `None` when the server sent no such message.
+A swap or a deposit has no order. An accepted order has no position and no deal
+yet.
+
+The order says why a position closed:
+
+```python
+from ctrader_api_client import ExecutionEvent, ExecutionType, OrderType
+
+@client.on(ExecutionEvent, account_id=12345)
+async def on_execution(event: ExecutionEvent):
+    if event.execution_type is not ExecutionType.ORDER_FILLED or event.order is None:
+        return
+    if not event.order.is_closing_order:
+        return  # An entry fill.
+    if event.order.is_stop_out:
+        print("Closed by a margin stop-out")
+    elif event.order.order_type is OrderType.STOP_LOSS_TAKE_PROFIT:
+        print("Closed by a stop loss or a take profit")
+    else:
+        print("Closed by a market order")
+```
+
 ::: ctrader_api_client.events.ExecutionEvent
     options:
       show_source: false
@@ -113,6 +137,9 @@ suppressed for `TOKEN_REFRESH` (session intact).
       show_source: false
       members: true
 
+A trader update carries the `Account` model that the accounts API returns.
+Its balance is a `Decimal` in account currency units.
+
 ::: ctrader_api_client.events.TraderUpdateEvent
     options:
       show_source: false

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/api/exceptions.md

@@ -19,7 +19,7 @@ CTraderError
 ├── AuthenticationError
 │   ├── ApplicationAuthError            the server rejected client_id/secret
 │   ├── AccountAuthError                the server rejected the account
-│   ├── TokenExpiredError               the access token is expired or invalid
+│   ├── TokenExpiredError               the server refused the access or refresh token
 │   ├── TokenRefreshError               a refresh exhausted its retries
 │   └── AccountNotFoundError            no account matches that trader login
 ├── APIError                            an error response to a request
@@ -69,9 +69,11 @@ except AccountAuthError as e:
     print(f"Account {e.ctid_trader_account_id} rejected: {e.error_code}")
 ```
 
-`TokenExpiredError` covers both a token the client knows has expired and one the
-server rejects as invalid. Neither can be retried back to life — it needs a new
-token.
+`TokenExpiredError` means the server refused a token: the access token at
+authentication, or the refresh token when the client refreshed an expired access
+token first. Neither can be retried back to life. It needs a new OAuth
+authorization. An access token that has merely expired does not raise, because
+the client refreshes it before it authenticates the account.
 
 ### Requests
 

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/api/models.md

@@ -190,6 +190,11 @@ symbol's quote currency, or in the currency that `minimum_asset` names. A `minim
 means the broker sets no minimum.
 
 
+::: ctrader_api_client.models.Swap
+    options:
+      show_source: false
+
+
 ::: ctrader_api_client.models.TradingHours
     options:
       show_source: false

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/api/symbols.md

@@ -87,6 +87,34 @@ charge lands in USD for the first two types, and in the symbol's quote currency
 [Models](models.md#ctrader_api_client.models.Commission) for the arithmetic of each type,
 and for how to apply `minimum`.
 
+## Swap
+
+A broker states a swap as two rates and a type. The type says what the rates count, so
+you must read them together. The same rate of `-1.5` is pips per lot for one symbol, and
+an annual percent for another. A negative rate is a charge.
+
+```python
+from ctrader_api_client import SwapCalculationType
+
+symbol = await client.symbols.get_by_id(account_id, 270)
+swap = symbol.swap
+
+print(f"{swap.long} / {swap.short} ({swap.calculation_type.value})")
+print(f"Tripled on {swap.triple_day.value}")
+print(f"Charged every {swap.period_hours} hours from {swap.charge_time} UTC")
+```
+
+| Type | Meaning of the rates |
+|------|----------------------|
+| `PIPS` | Pips per lot, per charge period. |
+| `PERCENTAGE` | Annual percent of the position value. |
+| `POINTS` | Points per lot, per charge period. |
+
+The broker charges the swap once per `period_hours`, starting at `charge_time` UTC. On
+`triple_day` the charge is three times the rate, to cover the weekend. `period_hours` is
+`None` when the broker does not publish it. See
+[Models](models.md#ctrader_api_client.models.Swap) for every field.
+
 ## Trading Hours
 
 Every `Symbol` arrives with its trading calendar attached, so asking when a symbol is open

{ctrader_api_client-0.10.0 → ctrader_api_client-0.12.0}/docs/getting-started.md

@@ -146,7 +146,8 @@ async def on_price(event: SpotEvent):
 @client.on(ExecutionEvent)
 async def on_execution(event: ExecutionEvent):
     """Called when orders are executed."""
-    print(f"Execution: {event.execution_type} for order {event.order_id}")
+    if event.order is not None:
+        print(f"Execution: {event.execution_type} for order {event.order.order_id}")
 
 
 async def main():
@@ -235,6 +236,12 @@ The contract is write-only. Reading back at startup is yours, since only you kno
 which accounts a given process is responsible for. See
 [TokenStore](api/client.md#tokenstore) for the full contract.
 
+A stored pair whose access token has expired still works. `authenticate_trader`
+refreshes it first and saves the new pair through the store, so a process that
+starts after the expiry needs no new token from the outside. Only a refresh token
+that the server refuses raises `TokenExpiredError`, and that needs a new OAuth
+authorization.
+
 ## Handling Errors
 
 Everything the library raises derives from `CTraderError`. Bringing the client up

ctrader_api_client-0.12.0/justfile

@@ -0,0 +1,88 @@
+# cTrader API client justfile
+set shell := ["bash", "-euo", "pipefail", "-c"]
+set script-interpreter := ["bash", "-euo", "pipefail"]
+set positional-arguments
+
+# Variables
+proto_path := "protos/vendor"
+python_out_path := "src/ctrader_api_client/_internal/proto"
+
+# Default recipe. List all available recipes.
+[private]
+default:
+    @just --list
+
+# Verify that the required toolchains are present
+[group('build')]
+[script]
+check-deps:
+    if ! command -v uv &> /dev/null; then
+        echo "uv not found. Install from https://docs.astral.sh/uv/getting-started/installation/" >&2
+        exit 1
+    fi
+    echo "==> All required toolchains are present"
+
+# Install the pre-commit hooks, then build the project. Extra arguments go to `uv sync`.
+[group('build')]
+[script]
+setup *args: check-deps
+    echo "==> Install the pre-commit hooks"
+    uv tool install prek
+    uv tool run prek install --hook-type pre-commit
+    echo "==> Build the project"
+    just build "$@"
+
+# Sync the Python dependencies. Extra arguments go to `uv sync`.
+[group('build')]
+build *args:
+    uv sync "$@"
+
+# Format the code. Extra arguments go to `ruff format`.
+[group('dev')]
+fmt *args:
+    uv run ruff format "$@"
+
+# Lint the code. Extra arguments go to `ruff check`.
+[group('dev')]
+lint *args:
+    uv run ruff check --fix "$@"
+
+# Type-check the code. Extra arguments go to `zuban check`.
+[group('dev')]
+type-check *args:
+    uv run zuban check "$@"
+
+# Run the tests. Extra arguments go to pytest.
+[group('dev')]
+test *args:
+    uv run pytest "$@"
+
+# Run the whole CI pipeline
+[group('dev')]
+@ci:
+    just fmt
+    just lint
+    just type-check
+    just test
+
+# Serve the documentation locally. Extra arguments go to `mkdocs serve`.
+[group('tools')]
+documentation *args:
+    uv run mkdocs serve "$@"
+
+# Fetch the .proto files at the given version into the vendor directory
+[group('tools')]
+update-proto version='main':
+    ./protos/update.sh "$1"
+
+# Generate the Python code from the .proto files. Run this after `update-proto`.
+[group('tools')]
+[script]
+compile-proto:
+    echo "==> Compile the .proto files from {{ proto_path }}/ into {{ python_out_path }}/"
+    uv run protoc -I={{ proto_path }} --python_betterproto_out={{ python_out_path }} {{ proto_path }}/*.proto
+    echo "==> Fix the cross-module imports"
+    uv run python scripts/fix_proto_imports.py
+    echo "==> Format the generated code"
+    uv run ruff check --fix {{ python_out_path }}
+    uv run ruff format {{ python_out_path }}

ctrader_api_client-0.12.0/plans/nested-event-models.md

@@ -0,0 +1,187 @@
+# Nested event models
+
+Status: steps 1 to 3 done on 2026-10-21. The version bump to 0.12.0 waits for another change that ships with it.
+
+## Problem
+
+A consumer cannot tell why a position closed from the live event stream.
+
+- A close arrives as a `ProtoOAExecutionEvent` of type `ORDER_FILLED`. Its
+  embedded `ProtoOAOrder` says why: `order_type` is `STOP_LOSS_TAKE_PROFIT` for
+  a protection close and `MARKET` for a manual close, `closing_order` marks a
+  close, and `is_stop_out` marks a margin close.
+- `execution_event_from_proto` keeps only the side, the order id and the symbol
+  id from the order. It keeps only the filled volume, the price and the
+  timestamp from the deal. It keeps only the position id from the position.
+- The only public path to the order type is `TradingAPI.get_orders`, which is a
+  second round trip that races the next event.
+
+The same shape repeats in `TraderUpdateEvent`. The server sends a full
+`ProtoOATrader`, and the router keeps three of its thirty-two fields.
+
+The library already has a faithful model for each embedded message: `Order`,
+`Position`, `Deal` and `Account`. The events translate the same data a second
+time, and translate less of it.
+
+## Facts from the source
+
+- `events/_execution.py`: `execution_event_from_proto` reads presence of the
+  order, the position and the deal with `betterproto.serialized_on_wire`. It
+  falls back to `datetime.now(UTC)` for the timestamp when the event has no
+  deal. Both `TradingAPI` and `EventRouter` call it.
+- `models/order.py`, `models/position.py`: `from_proto` tolerates an absent
+  `trade_data`. Both require a known `order_type`, `order_status` or
+  `position_status`; an unset enum raises `UnknownEnumValueError`.
+- `models/deal.py`: `from_proto` requires a known `trade_side` and
+  `deal_status`. It reads the close detail only when its balance is positive.
+- `models/account.py`: `Account.from_proto` scales `balance` by
+  `money_divisor(money_digits)`, which reads 0 as cents. `TraderUpdateEvent`
+  carries the raw integer plus `money_digits` instead, so a live balance and a
+  fetched balance are in different units.
+- `events/router.py`: `_handle_trader_update` drops the event when the trader
+  is absent. `_handle_execution` logs `event.order_id`.
+- `events/emitter.py`: `_validate_filter` checks `__dataclass_fields__` for
+  `account_id` and `symbol_id`. `_matches_filter` reads them with `getattr`.
+- `client.py`: `T_BothFilters` names `SpotEvent`, `ExecutionEvent` and
+  `DepthEvent` as the events that accept a `symbol_id` filter. No test pins the
+  symbol filter on `ExecutionEvent`.
+- Tests that construct or read the two events: `tests/behavior/events/test_routing.py`,
+  `tests/behavior/api/test_trading.py`, `tests/unit/test_enum_mapping.py`. The
+  routing tests build orders without an order type or status, and deals without
+  a side or status.
+- Docs that show `event.order_id`: `README.md`, `docs/getting-started.md`,
+  `docs/api/events.md`, and the docstrings of `Client.on` and `TradingAPI`.
+
+## Design
+
+1. `ExecutionEvent` becomes:
+
+   ```python
+   account_id: int
+   execution_type: ExecutionType
+   order: Order | None
+   position: Position | None
+   deal: Deal | None
+   is_server_event: bool = False
+   error_code: str | None = None
+   ```
+
+   Each nested field is `None` when the sub-message was not on the wire. The
+   converter calls the three existing `from_proto` methods. `order_id`,
+   `position_id`, `symbol_id`, `side`, `filled_volume`, `fill_price` and
+   `timestamp` leave. The execution timestamp lives on `deal.execution_timestamp`,
+   and an event with no deal has no timestamp instead of a fabricated one.
+
+2. `TraderUpdateEvent` becomes:
+
+   ```python
+   account_id: int
+   account: Account
+   ```
+
+   The router already drops an event with no trader, so `account` is not
+   optional. `balance`, `leverage_in_cents` and `money_digits` leave. The
+   balance is a scaled `Decimal` from the one converter that owns the scaling.
+
+3. `ExecutionEvent` loses the `symbol_id` filter. The symbol lives on the nested
+   order, and a swap or a deposit event has no order at all. `T_BothFilters`
+   drops `ExecutionEvent`, and the filter table in `docs/api/events.md` says
+   `No`. A consumer that wants one symbol reads `event.order.symbol_id` in the
+   handler.
+
+4. The reason for a close reads from one event:
+
+   ```python
+   if event.execution_type is ExecutionType.ORDER_FILLED and event.order.is_closing_order:
+       ...  # event.order.order_type, event.order.is_stop_out
+   ```
+
+### What does not change
+
+- An execution type the client does not know still raises from the converter.
+  The API layer lets it reach the caller, and the router drops the event. A
+  nested message with an unknown enum now takes the same path, because the
+  model converters raise the same error.
+- `account_id` stays on both events. It is the routing key that the account
+  filter reads, and every event in `events/types.py` carries it.
+- `MarginCallTriggerEvent` keeps its flat shape. There is no `MarginCall` model,
+  and no consumer asks for the fields the event drops.
+- `DepthEvent` keeps `DepthQuote` in `events/types.py`. No other message uses it.
+- `bonus_deposit_withdraw` and `deposit_withdraw` stay unread. There is no
+  model for them and no consumer asks for them.
+- The `Order`, `Position`, `Deal` and `Account` models do not change.
+
+### Attribute counts
+
+- `ExecutionEvent`: 10 today, 7 after.
+- `TraderUpdateEvent`: 4 today, 2 after.
+
+## Steps
+
+One step per turn. Each step leaves the suite green.
+
+### Step 1: `ExecutionEvent` nests `Order`, `Position` and `Deal`
+
+- `events/types.py`: the new field list. The docstring states that each nested
+  field is `None` when the server sent no such message.
+- `events/_execution.py`: call `Order.from_proto`, `Position.from_proto` and
+  `Deal.from_proto` behind the existing presence checks. Remove the timestamp
+  fallback and the `Decimal` and `order_side` imports.
+- `events/router.py`: the debug line reads the order id through
+  `event.order`, and logs `None` when there is no order.
+- `client.py`: `T_BothFilters` drops `ExecutionEvent`. The `Client.on`
+  docstring example reads `event.order.order_id`.
+- `api/trading.py`: the class docstring example reads `execution.order.order_id`.
+- `docs/api/events.md`: the filter table marks `ExecutionEvent` as `No` for
+  `symbol_id`. The code example reads `event.order.order_id`.
+- `tests/behavior/events/test_routing.py`: the `order()` helper carries an
+  order type and a status. Deals carry a side and a status. Positions carry a
+  status. The assertions read through `event.order`, `event.position` and
+  `event.deal`. Replace the four tests on the flat fields with:
+  1. A fill carries its order, position and deal: `event.order.order_id`,
+     `event.position.position_id`, `event.deal.filled_volume`,
+     `event.deal.execution_price` and `event.deal.execution_timestamp`.
+  2. A sell execution reports the sell side through `event.order.side`.
+  3. An accepted order has no position and no deal: both are `None`.
+  4. A swap has no order: `event.order is None`.
+  5. A close reports its reason: an `ORDER_FILLED` event whose order has
+     `order_type=STOP_LOSS_TAKE_PROFIT` and `closing_order=True` yields
+     `event.order.is_closing_order` and `event.order.order_type is
+     OrderType.STOP_LOSS_TAKE_PROFIT`.
+- `tests/behavior/api/test_trading.py`: the two tests that read the flat
+  fields of a placed order read through the nested models instead.
+- `tests/unit/test_enum_mapping.py`: `test_an_unknown_execution_type_is_an_error`
+  passes unchanged.
+
+### Step 2: `TraderUpdateEvent` nests `Account`
+
+- `events/types.py`: the new field list.
+- `events/router.py`: `_handle_trader_update` builds `Account.from_proto(trader)`.
+  Remove the `DEFAULT_MONEY_DIGITS` use from this handler only; the margin
+  handler keeps it.
+- `tests/behavior/events/test_routing.py`: replace the two trader update tests
+  with:
+  1. A trader update carries the account: `event.account.balance ==
+     Decimal("10000.00")` for a wire balance of `1_000_000` at two money
+     digits, and `event.account.leverage_in_cents == 10_000`.
+  2. A trader update without money digits scales as cents: a wire balance of
+     `1_000_000` with no `money_digits` yields `Decimal("10000.00")`.
+
+### Step 3: docs and version
+
+- `README.md` and `docs/getting-started.md`: the execution handler example
+  reads `event.order.order_id`. Add a short example that reads the reason for a
+  close from `event.order`.
+- `docs/api/events.md`: the `ExecutionEvent` section states that the three
+  nested models are the same types that `TradingAPI` returns.
+- `pyproject.toml`: 0.12.0. Deferred: another change ships in the same bump.
+
+## Consumer follow-up
+
+Out of scope for this repository. Recorded so the two changes stay aligned.
+
+Each consumer bumps its pin to 0.12.0 and reads `event.order`, `event.position`
+and `event.deal` instead of the flat fields. A handler on `ExecutionEvent` that
+filtered by `symbol_id` moves the check into the handler body. A handler on
+`TraderUpdateEvent` reads `event.account.balance` as a `Decimal` in account
+currency units and drops its own scaling.