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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrader-api-client
-Version: 0.11.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
@@ -252,6 +252,7 @@ await client.trading.close_position(account_id, close_position)
 ```python
 from ctrader_api_client import (
     ExecutionEvent,
+    ExecutionType,
     ReadyEvent,
     ReconnectedEvent,
     SpotEvent,
@@ -264,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.11.0 → ctrader_api_client-0.12.0}/README.md

@@ -233,6 +233,7 @@ await client.trading.close_position(account_id, close_position)
 ```python
 from ctrader_api_client import (
     ExecutionEvent,
+    ExecutionType,
     ReadyEvent,
     ReconnectedEvent,
     SpotEvent,
@@ -245,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.11.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.11.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.11.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.11.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():

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.

ctrader_api_client-0.12.0/plans/symbol-swaps.md

@@ -0,0 +1,209 @@
+# Symbol swaps
+
+Status: complete on 2026-10-21. Ships in the 0.12.0 bump with the nested
+event models.
+
+## Problem
+
+A consumer cannot compute what a position costs to hold overnight.
+
+- `Symbol` keeps `swap_long` and `swap_short` as bare decimals. The server sends
+  them with `swapCalculationType`, which says whether a rate is pips per lot,
+  an annual percentage, or points. A rate read without its type is meaningless.
+  The commission module makes the same argument for the commission rate, and
+  keeps the rate with its type. The swap rate does not get that treatment.
+- `Symbol.from_proto` drops `swapRollover3Days`, `swapPeriod`, `swapTime`,
+  `skipSWAPPeriods` and `chargeSwapAtWeekends`. A consumer that wants to know
+  when a swap is charged, and on which day it is tripled, has no path to it.
+
+## Facts from the source
+
+- `models/commission.py`: `Commission.from_proto(proto: ProtoOASymbol)` reads a
+  group of related fields out of the symbol proto into one sub-model. `Symbol`
+  holds it as `commission: Commission = Field(default_factory=Commission)`.
+  This is the pattern to copy.
+- `_internal/proto/OpenApiModelMessages.py`: `ProtoOASwapCalculationType` has
+  `PIPS = 0`, `PERCENTAGE = 1`, `POINTS = 2`. The vendor docs name only the
+  first two. `ProtoOADayOfWeek` has `NONE = 0` through `SUNDAY = 7`. The
+  generated name for `skipSWAPPeriods` is `skip_s_w_a_p_periods`.
+- `protos/vendor/OpenApiModelMessages.proto`: `swapRollover3Days` and
+  `rolloverCommission3Days` declare `[default = MONDAY]`. `swapCalculationType`
+  declares `[default = PIPS]`. `swapPeriod`, `swapTime`, `skipSWAPPeriods` and
+  `chargeSwapAtWeekends` declare no default. The generated code applies no
+  proto2 default, so each of these reads as 0 when the broker omits it.
+- `_internal/conversions.py`: `enum_member(mapping, value, unset=...)` reads 0
+  as the declared default when the caller passes one, and raises on 0 when the
+  caller passes none.
+- `tests/unit/test_symbol_conversion.py`: `forex_symbol()` builds a `Symbol`
+  with `swap_long` and `swap_short`. `tests/unit/test_enum_mapping.py` lists
+  each optional enum with its declared default in `OPTIONAL`.
+- `tests/unit/test_commission_conversion.py`: two tests pin values a live
+  broker sent, with the raw wire value and the expected reading in the
+  docstring. This is how a playground finding becomes a test.
+- The playground script outside the repository holds the live credentials and
+  an editable install of this package. `client.protocol.request(...)` returns
+  raw protos. The account exposes 202 symbols.
+
+## Design
+
+1. A `Swap` sub-model in `models/swap.py`:
+
+   ```python
+   class Swap(FrozenModel):
+       calculation_type: SwapCalculationType = SwapCalculationType.PIPS
+       long: Decimal = Decimal(0)
+       short: Decimal = Decimal(0)
+       triple_day: DayOfWeek = DayOfWeek.MONDAY
+       period_hours: int | None = None
+       charge_time: time = time(0)
+       skip_periods: int = 0
+       charged_at_weekends: bool = False
+   ```
+
+   `Swap.from_proto(proto: ProtoOASymbol)` reads the eight fields. `Symbol`
+   gains `swap: Swap = Field(default_factory=Swap)`, and `swap_long` and
+   `swap_short` leave `Symbol`. The two rates stay as the server sends them.
+   The type says what they count, the same as the commission rate.
+
+2. Two enums in `enums.py`. `SwapCalculationType` has `PIPS`, `PERCENTAGE` and
+   `POINTS`. `DayOfWeek` has `NONE` and the seven days. The proto maps live in
+   `models/swap.py`, the same as the commission maps.
+
+3. How each unset value reads:
+   - `calculation_type`: 0 is `PIPS` on the wire and is also the declared
+     default, so there is nothing to decide.
+   - `triple_day`: 0 is `NONE` on the wire, and the declared default is
+     `MONDAY`. The wire cannot tell the two apart. Every other enum with a
+     declared default reads 0 as that default, so this one does too. Step 3
+     checks against the live broker whether this reading loses a real `NONE`.
+   - `period_hours`: 0 means the broker said nothing. The model reports `None`.
+     It does not guess 24, because the library never guesses at a value the
+     broker did not send.
+   - `charge_time`: 0 is midnight UTC, which is both the literal reading and
+     the sensible default. The model converts minutes from midnight to a
+     `datetime.time`.
+   - `skip_periods` and `charged_at_weekends`: 0 and `False` are the literal
+     readings and need no default.
+
+4. The playground check comes after the implementation, not before. The model
+   gives the check something to compare the raw protos against, and a finding
+   that contradicts the design changes the design in a later step.
+
+### What does not change
+
+- The rollover fields stay unread: `rolloverCommission`, `skipRolloverDays`
+  and `rolloverCommission3Days`. They are the administrative fee that replaces
+  swaps on a swap-free account. The docs give no scale for the amount, and no
+  consumer account is swap-free. Step 3 records whether the live broker sends
+  them, so a later plan has the facts.
+- `Account.swap_free` stays where it is.
+- `Commission`, `TradingHours` and the rest of `Symbol` do not change.
+- `distanceSetIn`, `gslDistance` and `gslCharge` stay out of scope. The stop
+  distances have the same shape of problem as the swap rate, a number without
+  its unit, and get their own plan.
+
+### Attribute counts
+
+- `Symbol`: 20 today, 19 after. `swap_long` and `swap_short` leave, `swap`
+  arrives.
+- `Swap`: 8.
+
+## Steps
+
+One step per turn. Each step leaves the suite green.
+
+### Step 1: the `Swap` model
+
+- `enums.py`: add `SwapCalculationType` and `DayOfWeek`.
+- `models/swap.py`: the `Swap` model, the two proto maps, and `from_proto`.
+  The module docstring states why the rate travels with its type, in the
+  same words the commission module uses.
+- `models/symbol.py`: `swap: Swap = Field(default_factory=Swap)` replaces the
+  two rates. `from_proto` calls `Swap.from_proto(proto)`. The class docstring
+  describes `swap` and drops the two rate lines.
+- `models/__init__.py` and `__init__.py`: export `Swap`, `SwapCalculationType`
+  and `DayOfWeek`.
+- `tests/unit/test_swap_conversion.py`, new:
+  1. Each calculation type is translated, including `POINTS`.
+  2. A calculation type the broker omits reads as `PIPS`.
+  3. The long and short rates keep their decimal value.
+  4. A triple day the broker omits reads as `MONDAY`.
+  5. Each named day is translated.
+  6. A swap period the broker omits reads as `None`, and a period of 8 reads
+     as 8.
+  7. A charge time of 90 minutes reads as 01:30 UTC, and an omitted one reads
+     as midnight.
+  8. The skip count and the weekend flag are carried over.
+  9. A symbol without any swap field reports the default `Swap`.
+- `tests/unit/test_symbol_conversion.py`: `forex_symbol()` drops the two rate
+  settings. Nothing in the file reads them.
+- `tests/unit/test_enum_mapping.py`: `OPTIONAL` gains `swap_calculation_type`
+  with default `PIPS` and `swap_rollover3_days` with default `MONDAY`.
+
+### Step 2: docs
+
+- `docs/api/symbols.md`: a `## Swap` section after `## Commission`. It states
+  that the rate and the type are read together, gives a table of the three
+  types, and shows `symbol.swap.long`, `symbol.swap.triple_day` and
+  `symbol.swap.period_hours`.
+- `docs/api/models.md`: `::: ctrader_api_client.models.Swap` after
+  `Commission`.
+
+### Step 3: check the live broker
+
+A script in the scratchpad directory imports the credentials from the
+playground. It never copies them. It authenticates, requests
+`ProtoOASymbolByIdReq` for a forex pair, a metal, an index and a crypto
+symbol, and prints for each one:
+
+- the raw wire values of the eight swap fields and the three rollover fields,
+- the converted `Swap`.
+
+The questions it answers, recorded in this file under `## Findings`:
+
+1. Does any symbol send `swapRollover3Days` as 0? If so, the `MONDAY` reading
+   is wrong for that broker, and the next step decides between a `NONE`
+   reading and a documented limit.
+2. What does `swapCalculationType` carry, and does any symbol send `POINTS`?
+3. What do `swapPeriod`, `swapTime` and `skipSWAPPeriods` carry? Does any
+   symbol omit `swapPeriod`?
+4. Does the broker send the three rollover fields at all, and at what scale?
+
+### Step 4: pin the findings
+
+- For each finding that fixes a reading, a test in
+  `test_swap_conversion.py` with the raw wire value and the expected reading
+  in its docstring, the same as the two live commission tests.
+- If finding 1 shows a real `NONE`, this plan gains a step that changes the
+  `triple_day` reading, and the version bump waits for it.
+
+## Findings
+
+Checked on 2026-10-21 against the demo broker in the playground, over all 202
+symbols the account exposes. The scratchpad script reads the playground
+constants with `ast` so that it never runs the playground or copies a secret.
+
+1. **No symbol sends `swapRollover3Days` as 0.** Every symbol sends
+   `WEDNESDAY` (87, every forex pair and every metal) or `FRIDAY` (115, every
+   index, commodity, crypto and equity). The `MONDAY` reading of 0 is never
+   exercised by this broker, so it stays as the declared default. `DayOfWeek`
+   keeps no `NONE` member.
+2. **`swapCalculationType` is `PIPS` for 171 symbols and `PERCENTAGE` for
+   31.** No symbol sends `POINTS`. Every `PERCENTAGE` symbol is a crypto pair
+   and sends `-30.0` for both rates: an annual charge of 30 percent either
+   way. A `PIPS` example is EURUSD at `-1.084` long and `0.051` short.
+3. **`swapPeriod` is 24, `swapTime` is 1259 and `skipSWAPPeriods` is 0 on
+   every symbol.** The broker charges once a day at 20:59 UTC. No symbol omits
+   the period, so the `None` reading is never exercised here. One symbol,
+   BRK.B, sets `chargeSwapAtWeekends`.
+4. **The broker sends the rollover schedule but no rollover fee.**
+   `rolloverCommission` is 0, `skipRolloverDays` is 3 and
+   `rolloverCommission3Days` is `WEDNESDAY` on every symbol. The account is
+   not swap-free, so the fee amount and its scale stay unknown. The rollover
+   fields stay out of the model.
+
+Also seen: 34 exotic forex pairs send 0 for both rates with `PIPS`, which the
+model reports as a zero swap, which is what the broker says.
+
+No finding contradicts the design. Step 4 pins findings 2 and 3 as tests with
+the raw wire values.

{ctrader_api_client-0.11.0 → ctrader_api_client-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.11.0"
+version = "0.12.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [