ctrader-api-client 0.1.2__tar.gz → 0.2.0__tar.gz

ctrader_api_client-0.2.0/.claude/settings.local.json

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

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/Justfile

@@ -26,7 +26,7 @@ fmt directory='':
 
 # Run type checking using ty, optionally specifying a directory to check.
 type-check directory='':
-    uv run ty check {{directory}}
+    uv run zuban check {{directory}}
 
 # Run tests using pytest, optionally specifying a directory to test.
 test directory='':

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.1.2
+Version: 0.2.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/accounts.md

@@ -19,7 +19,7 @@ Access via `client.accounts`.
 ```python
 account = await client.accounts.get_trader(account_id)
 
-print(f"Balance: {account.get_balance()}")
+print(f"Balance: {account.balance}")
 print(f"Leverage: {account.get_leverage()}")
 print(f"Account type: {account.account_type}")
 print(f"Broker name: {account.broker_name}")

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/events.md

@@ -41,6 +41,26 @@ Using an unsupported filter raises `ValueError` at registration time.
     options:
       show_source: false
 
+**SpotEvent contains live trendbar data when subscribed:**
+
+```python
+from ctrader_api_client.enums import TrendbarPeriod
+
+# Subscribe to both spot prices and M1 trendbars
+await client.market_data.subscribe_spots(account_id, [270])
+await client.market_data.subscribe_trendbars(account_id, 270, TrendbarPeriod.M1)
+
+@client.on(SpotEvent, symbol_id=270)
+async def on_spot(event: SpotEvent):
+    # Prices are floats
+    print(f"Bid: {event.bid}, Ask: {event.ask}")
+
+    # Trendbar is included when subscribed
+    if event.trendbar:
+        bar = event.trendbar
+        print(f"Candle: O={bar.open} H={bar.high} L={bar.low} C={bar.close}")
+```
+
 ::: ctrader_api_client.events.DepthEvent
     options:
       show_source: false

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/market-data.md

@@ -30,12 +30,32 @@ from ctrader_api_client.events import SpotEvent
 await client.market_data.subscribe_spots(account_id, [270, 271])
 
 
-# Handle price updates
+# Handle price updates - bid/ask are floats
 @client.on(SpotEvent, symbol_id=270)
 async def on_price(event: SpotEvent):
     print(f"Bid: {event.bid}, Ask: {event.ask}")
 ```
 
+### Subscribe to Live Trendbars
+
+```python
+from ctrader_api_client.events import SpotEvent
+from ctrader_api_client.enums import TrendbarPeriod
+
+# Subscribe to M1 trendbars
+await client.market_data.subscribe_trendbars(account_id, symbol_id=270, period=TrendbarPeriod.M1)
+
+# Trendbar data is delivered inside SpotEvent
+@client.on(SpotEvent, symbol_id=270)
+async def on_spot(event: SpotEvent):
+    print(f"Price: {event.bid}/{event.ask}")
+
+    # Check if this event contains trendbar data
+    if event.trendbar:
+        bar = event.trendbar
+        print(f"Bar: O={bar.open} H={bar.high} L={bar.low} C={bar.close} V={bar.volume}")
+```
+
 ### Subscribe to Depth of Market
 
 ```python
@@ -55,32 +75,36 @@ async def on_depth(event: DepthEvent):
 ### Get Historical Trendbars
 
 ```python
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, UTC
 from ctrader_api_client.enums import TrendbarPeriod
 
 trendbars = await client.market_data.get_trendbars(
     account_id,
     symbol_id=270,
     period=TrendbarPeriod.H1,
-    from_timestamp=datetime.now() - timedelta(days=7),
-    to_timestamp=datetime.now(),
+    from_timestamp=datetime.now(UTC) - timedelta(days=7),
+    to_timestamp=datetime.now(UTC),
 )
 
+# OHLC values are already floats (converted from raw integers)
 for bar in trendbars:
-    print(f"O:{bar.open} H:{bar.high} L:{bar.low} C:{bar.close} V:{bar.volume}")
+    print(f"{bar.timestamp}: O={bar.open} H={bar.high} L={bar.low} C={bar.close} V={bar.volume}")
 ```
 
 ### Get Tick Data
 
 ```python
+from datetime import datetime, timedelta, UTC
+
 ticks = await client.market_data.get_tick_data(
     account_id,
     symbol_id=270,
-    from_timestamp=datetime.now() - timedelta(hours=1),
-    to_timestamp=datetime.now(),
+    from_timestamp=datetime.now(UTC) - timedelta(hours=1),
+    to_timestamp=datetime.now(UTC),
     quote_type="BID",  # or "ASK"
 )
 
+# Price is already a float
 for tick in ticks:
     print(f"{tick.timestamp}: {tick.price}")
 ```
@@ -109,9 +133,11 @@ It is recommended to use `ReadyEvent` to keep all subscriptions centralized in o
 
 ```python
 from ctrader_api_client.events import ReadyEvent
+from ctrader_api_client.enums import TrendbarPeriod
 
 @client.on(ReadyEvent)
 async def on_ready(event: ReadyEvent):
     # This runs on initial auth AND after reconnection
     await client.market_data.subscribe_spots(event.account_id, [270, 271])
+    await client.market_data.subscribe_trendbars(event.account_id, 270, TrendbarPeriod.M1)
 ```

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/models.md

@@ -16,12 +16,15 @@ Request for placing a new order.
 from ctrader_api_client.models import NewOrderRequest
 from ctrader_api_client.enums import OrderType, OrderSide, TimeInForce
 
+# Get symbol for volume conversion
+symbol = await client.symbols.get_by_id(account_id, 270)
+
 # Market order
 market_order = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.MARKET,
     side=OrderSide.BUY,
-    volume=100,  # 0.01 lots
+    volume=symbol.lots_to_volume(0.01),  # 0.01 lots
 )
 
 # Limit order with SL/TP
@@ -29,19 +32,29 @@ limit_order = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.LIMIT,
     side=OrderSide.BUY,
-    volume=100,
+    volume=symbol.lots_to_volume(0.1),
     limit_price=5000.0,
     stop_loss=4950.0,
     take_profit=5100.0,
     time_in_force=TimeInForce.GOOD_TILL_CANCEL,
 )
 
+# Order with relative SL/TP (distance from entry price)
+relative_order = NewOrderRequest(
+    symbol_id=270,
+    order_type=OrderType.MARKET,
+    side=OrderSide.BUY,
+    volume=symbol.lots_to_volume(0.1),
+    relative_stop_loss=50.0,   # 50 price units below entry
+    relative_take_profit=100.0,  # 100 price units above entry
+)
+
 # Stop order
 stop_order = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.STOP,
     side=OrderSide.SELL,
-    volume=100,
+    volume=symbol.lots_to_volume(0.1),
     stop_price=4900.0,
 )
 ```
@@ -59,16 +72,22 @@ stop_order = NewOrderRequest(
 ```python
 from ctrader_api_client.models import ClosePositionRequest
 
+# Get position to know its volume
+positions = await client.trading.get_open_positions(account_id)
+position = positions[0]
+
 # Close entire position
 close_all = ClosePositionRequest(
-    position_id=123456,
-    volume=100,  # Must match position volume for full close
+    position_id=position.position_id,
+    volume=position.volume,  # Must match position volume for full close
 )
 
-# Partial close
+# Partial close - close half of the position
+symbol = await client.symbols.get_by_id(account_id, position.symbol_id)
+current_lots = symbol.volume_to_lots(position.volume)
 partial_close = ClosePositionRequest(
-    position_id=123456,
-    volume=50,  # Close half
+    position_id=position.position_id,
+    volume=symbol.lots_to_volume(current_lots / 2),  # Close half
 )
 ```
 
@@ -128,34 +147,46 @@ partial_close = ClosePositionRequest(
     options:
       show_source: false
 
-## Volume and Price Conversion
+## Volume Conversion
 
-Volumes in the cTrader API are expressed in **cents** (1/100 of the base unit):
+Volumes in the cTrader API are expressed in **cents** relative to the symbol's `lot_size`:
 
-- `100` = 0.01 lots
-- `10000` = 0.1 lots
-- `100000` = 1.0 lot
+- For standard forex (lot_size=100000): `100000` = 1.0 lots, `10000` = 0.1 lots, `1000` = 0.01 lots
+- For other instruments, lot_size may vary
 
 Use the `Symbol` model for conversions:
 
 ```python
 symbol = await client.symbols.get_by_id(account_id, 270)
 
-# Convert volume to lots
-volume_in_cents = 100
-lots = symbol.volume_to_lots(volume_in_cents)  # 1.0
+# Convert lots to volume for orders
+volume = symbol.lots_to_volume(0.1)  # Returns volume in cents
 
-# Convert lots to volume
-lots = 0.5
-volume = symbol.lots_to_volume(lots)  # 50
+# Convert volume to lots for display
+lots = symbol.volume_to_lots(position.volume)  # Returns lots as float
 ```
 
-Prices are returned as raw integers. Use the symbol's `digits` for conversion:
+## Price Values
 
-```python
-# Raw price from event
-raw_price = event.bid  # e.g., 123456
+Prices in events and models (bid, ask, OHLC, execution prices, etc.) are returned as **floats** - no conversion needed:
 
-# Convert to decimal
-decimal_price = Decimal(raw_price) / Decimal(10 ** 5)  # 1.23456
+```python
+@client.on(SpotEvent)
+async def on_price(event: SpotEvent):
+    # bid and ask are already floats
+    spread = event.ask - event.bid
+    print(f"Spread: {spread}")
+
+# Trendbar OHLC are floats
+for bar in trendbars:
+    range_size = bar.high - bar.low
+    print(f"Range: {range_size}")
+
+# Account balance is a float
+account = await client.accounts.get_trader(account_id)
+print(f"Balance: {account.balance}")
+
+# Position values are floats
+for pos in positions:
+    print(f"Swap: {pos.swap}, Commission: {pos.commission}")
 ```

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/symbols.md

@@ -24,7 +24,7 @@ Access via `client.symbols`.
 symbols = await client.symbols.list_all(account_id)
 
 for sym in symbols:
-    print(f"{sym.symbol_id}: {sym.symbol_name}")
+    print(f"{sym.symbol_id}: {sym.name}")
 ```
 
 ### Get Symbol by ID
@@ -33,7 +33,6 @@ for sym in symbols:
 # Get full symbol details
 symbol = await client.symbols.get_by_id(account_id, 270)
 
-print(f"Name: {symbol.symbol_name}")
 print(f"Digits: {symbol.digits}")
 print(f"Lot size: {symbol.lot_size}")
 print(f"Min volume: {symbol.min_volume}")
@@ -46,7 +45,7 @@ print(f"Max volume: {symbol.max_volume}")
 symbols = await client.symbols.get_by_ids(account_id, [270, 271, 272])
 
 for sym in symbols:
-    print(f"{sym.symbol_name}: {sym.digits} digits")
+    print(f"{sym.name}: {sym.digits} digits, lot_size={sym.lot_size}")
 ```
 
 ### Search Symbols
@@ -56,36 +55,31 @@ for sym in symbols:
 eur_pairs = await client.symbols.search(account_id, "EUR")
 
 for sym in eur_pairs:
-    print(sym.symbol_name)
+    print(sym.name)
 ```
 
-## Price Conversion
+## Volume Conversion
 
-Prices in the cTrader API are represented as integers (e.g. 12345 for 1.2345) and the decimal place varies from one symbol to another.
-Use `Symbol` methods to convert between price and decimal:
+The cTrader API uses volume in "cents" (smallest volume units). The relationship between lots and volume depends on the symbol's `lot_size`:
 
 ```python
 symbol = await client.symbols.get_by_id(account_id, 270)
 
-# Price to decimal
-decimal_price = symbol.price_to_decimal(12345)  # 1.2345
-
-# Decimal to price
-price = symbol.decimal_to_price(1.2345)  # 12345
+# Lots to volume (for placing orders)
+volume = symbol.lots_to_volume(1.0)    # e.g., 10000000 for standard forex
 
+# Volume to lots (for display)
+lots = symbol.volume_to_lots(10000000)   # e.g., 1.0 for standard forex
 ```
 
-
-## Volume Conversion
-
-Use `Symbol` methods to convert between lots and volume:
+**Note:** Different instruments have different lot sizes. Always use the symbol's methods for conversion:
 
 ```python
-symbol = await client.symbols.get_by_id(account_id, 270)
-
-# Lots to volume (cents)
-volume = symbol.lots_to_volume(1.0)  # 100000
+# Standard forex (lot_size=100000)
+forex_symbol = await client.symbols.get_by_id(account_id, 1)  # EURUSD (lot_size=10000000)
+forex_volume = forex_symbol.lots_to_volume(0.1)  # 1000000
 
-# Volume to lots
-lots = symbol.volume_to_lots(100000)  # 1.0
+# Index CFD might have different lot_size
+index_symbol = await client.symbols.get_by_id(account_id, 270)  # US500 (lot_size=100)
+index_volume = index_symbol.lots_to_volume(0.1)  # 10
 ```

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/api/trading.md

@@ -28,11 +28,15 @@ Access via `client.trading`.
 from ctrader_api_client.models import NewOrderRequest
 from ctrader_api_client.enums import OrderType, OrderSide
 
+# Get symbol info for volume conversion
+symbol = await client.symbols.get_by_id(account_id, 270)
+
+# Place a 0.1 lot buy order
 request = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.MARKET,
     side=OrderSide.BUY,
-    volume=100,  # 0.01 lots (volume in cents)
+    volume=symbol.lots_to_volume(0.1),  # Convert lots to volume
 )
 
 result = await client.trading.place_order(account_id, request)
@@ -42,19 +46,38 @@ print(f"Order {result.order_id}: {result.execution_type}")
 ### Place a Limit Order
 
 ```python
+# Get symbol info
+symbol = await client.symbols.get_by_id(account_id, 270)
+
 request = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.LIMIT,
     side=OrderSide.BUY,
-    volume=100,
+    volume=symbol.lots_to_volume(0.1),
     limit_price=5000.0,  # Limit price
-    stop_loss=4950.0,    # Optional SL
+    stop_loss=4950.0,  # Optional SL
     take_profit=5100.0,  # Optional TP
 )
 
 result = await client.trading.place_order(account_id, request)
 ```
 
+### Place an Order with Relative SL/TP
+
+```python
+# Relative SL/TP are specified in price units (distance from entry)
+request = NewOrderRequest(
+    symbol_id=270,
+    order_type=OrderType.MARKET,
+    side=OrderSide.BUY,
+    volume=symbol.lots_to_volume(0.1),
+    relative_stop_loss=50.0,   # 50 points below entry
+    relative_take_profit=100.0,  # 100 points above entry
+)
+
+result = await client.trading.place_order(account_id, request)
+```
+
 ### Cancel an Order
 
 ```python
@@ -67,9 +90,30 @@ print(f"Cancelled: {result.execution_type}")
 ```python
 from ctrader_api_client.models import ClosePositionRequest
 
+# First, get the position to know its volume
+positions = await client.trading.get_open_positions(account_id)
+position = next(p for p in positions if p.position_id == position_id)
+
+# Close the entire position
 request = ClosePositionRequest(
-    position_id=123456,
-    volume=100,  # Close 0.01 lots (or full volume)
+    position_id=position.position_id,
+    volume=position.volume,  # Use full volume for complete close
+)
+
+result = await client.trading.close_position(account_id, request)
+print(f"Position closed: {result.execution_type}")
+```
+
+### Partial Close a Position
+
+```python
+# Get symbol to convert lots
+symbol = await client.symbols.get_by_id(account_id, position.symbol_id)
+
+# Close half of a 1-lot position
+request = ClosePositionRequest(
+    position_id=position.position_id,
+    volume=symbol.lots_to_volume(0.5),  # Close 0.5 lots
 )
 
 result = await client.trading.close_position(account_id, request)
@@ -95,7 +139,12 @@ result = await client.trading.amend_position(account_id, request)
 positions = await client.trading.get_open_positions(account_id)
 
 for pos in positions:
-    print(f"Position {pos.position_id}: {pos.volume} @ {pos.entry_price}")
+    # Get symbol for volume conversion
+    symbol = await client.symbols.get_by_id(account_id, pos.symbol_id)
+    lots = symbol.volume_to_lots(pos.volume)
+
+    print(f"Position {pos.position_id}: {lots} lots @ {pos.entry_price}")
+    print(f"  Swap: {pos.swap}, Commission: {pos.commission}")
 ```
 
 ### Get Pending Orders
@@ -120,4 +169,9 @@ deals = await client.trading.get_deals(
 
 for deal in deals:
     print(f"Deal {deal.deal_id}: {deal.side} {deal.filled_volume}")
+    print(f"  Commission: {deal.commission}")
+
+    # Check if this deal closed a position
+    if deal.is_closing_deal and deal.close_detail:
+        print(f"  Gross P/L: {deal.close_detail.gross_profit}")
 ```

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/getting-started.md

@@ -85,11 +85,14 @@ await client.market_data.subscribe_spots(creds.account_id, [270])
 from ctrader_api_client.models import NewOrderRequest
 from ctrader_api_client.enums import OrderType, OrderSide
 
+# Get symbol info for volume conversion
+symbol = await client.symbols.get_by_id(creds.account_id, 270)
+
 request = NewOrderRequest(
     symbol_id=270,
     order_type=OrderType.MARKET,
     side=OrderSide.BUY,
-    volume=100,  # Volume in cents (100 = 0.01 lots)
+    volume=symbol.lots_to_volume(0.01),  # Convert 0.01 lots to volume
 )
 
 result = await client.trading.place_order(creds.account_id, request)
@@ -131,9 +134,6 @@ async def on_execution(event: ExecutionEvent):
     """Called when orders are executed."""
     print(f"Execution: {event.execution_type} for order {event.order_id}")
 
-    if event.is_closing_deal:
-        print(f"Position closed. Profit: {event.close_detail.get_net_profit()}")
-
 
 async def main():
     async with client:
@@ -145,12 +145,15 @@ async def main():
             expires_at=1778617423,
         )
 
+        # Get symbol for volume conversion
+        symbol = await client.symbols.get_by_id(creds.account_id, 270)
+
         # Place a test order
         order = NewOrderRequest(
             symbol_id=270,
             order_type=OrderType.MARKET,
             side=OrderSide.BUY,
-            volume=100,
+            volume=symbol.lots_to_volume(0.01),  # 0.01 lots
         )
         await client.trading.place_order(creds.account_id, order)
 
@@ -203,7 +206,7 @@ config = ClientConfig(
 
     # Timeouts
     heartbeat_interval=10.0,
-    heartbeat_timeout=30.0,  # Or 0 to disable server heartbeat checks
+    heartbeat_timeout=0,  # 0 to disable server heartbeat checks (default)
     request_timeout=30.0,
 
     # Reconnection

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/docs/index.md

@@ -41,6 +41,7 @@ client = CTraderClient(config)
 
 @client.on(SpotEvent, symbol_id=270)  # Filter by symbol
 async def on_price(event: SpotEvent):
+    # bid and ask are floats
     print(f"Price update: {event.bid}/{event.ask}")
 
 

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.1.2"
+version = "0.2.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [
@@ -33,7 +33,7 @@ dev = [
     "mkdocstrings[python]>=1.0.3",
     "pytest>=9.0.3",
     "ruff>=0.15.9",
-    "ty>=0.0.28",
+    "zuban>=0.7.0",
 ]
 
 [tool.ruff]
@@ -68,8 +68,7 @@ line-ending = "lf"
 skip-magic-trailing-comma = false
 docstring-code-format = true
 
-[[tool.ty.overrides]]
-include = ["tests/**"]
 
-[tool.ty.overrides.rules]
-invalid-assignment = "ignore"
+[[tool.mypy.overrides]]
+module = "tests.*"
+disable_error_code = ["method-assign"]

{ctrader_api_client-0.1.2 → ctrader_api_client-0.2.0}/src/ctrader_api_client/api/market_data.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from datetime import datetime
 from typing import TYPE_CHECKING
 
@@ -177,7 +178,10 @@ class MarketDataAPI:
     ) -> None:
         """Subscribe to live trendbar (candle) updates.
 
-        After subscribing, trendbar events will be delivered via the event system.
+        Requires subscribing to spots for the same symbol beforehand.
+
+        After subscribing, trendbar data will be delivered via the event system inside the SpotEvent object.
+        Use `@client.on(SpotEvent)` to handle them.
 
         Args:
             account_id: The cTID trader account ID.
@@ -378,7 +382,7 @@ class MarketDataAPI:
         to_timestamp: datetime,
         quote_type: str = "BID",
         timeout: float | None = None,
-    ) -> list[TickData]:
+    ) -> Sequence[TickData]:
         """Get historical tick data.
 
         Args:
@@ -390,7 +394,7 @@ class MarketDataAPI:
             timeout: Request timeout (uses default if None).
 
         Returns:
-            List of TickData objects, ordered by timestamp ascending.
+            List of TickData objects, ordered by newest first.
 
         Note:
             Tick data can be voluminous. Use small time windows to avoid
@@ -421,4 +425,4 @@ class MarketDataAPI:
                 description=f"Expected ProtoOAGetTickDataRes, got {type(response).__name__}",
             )
 
-        return [TickData.from_proto(t) for t in response.tick_data]
+        return TickData.from_proto_list(response.tick_data)