ctrader-api-client 0.1.0__tar.gz

ctrader_api_client-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+  name: Deploy Documentation
+
+  on:
+    push:
+      branches: [master]
+    workflow_dispatch:
+
+  permissions:
+    contents: write
+
+  jobs:
+    deploy:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+        - uses: astral-sh/setup-uv@v5
+        - run: uv sync --group dev
+        - run: uv run mkdocs gh-deploy --force

ctrader_api_client-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE-specific files
+.idea/
+.vscode/

ctrader_api_client-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  # Ruff for linting & formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        language_version: python3
+      - id: ruff-format
+        language_version: python3
+
+  # Basic pre-commit housekeeping hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-shebang-scripts-are-executable

ctrader_api_client-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

ctrader_api_client-0.1.0/Justfile

@@ -0,0 +1,51 @@
+#!/usr/bin/env just --justfile
+
+SEPARATOR := `printf '%0.s-' {1..60}`
+PROTO_PATH := "protos/vendor"
+PYTHON_OUT_PATH := "src/ctrader_api_client/_internal/proto"
+
+default: help
+
+# Print this help message
+help:
+    just --list
+
+# Run all CI steps: linting, formatting, type checking
+ci directory='':
+    @just lint {{directory}}
+    @just fmt {{directory}}
+    @just type-check {{directory}}
+
+# Lint the codebase using ruff, optionally specifying a directory to lint.
+lint directory='':
+    uv run ruff check --fix {{directory}}
+
+# Format the codebase using ruff, optionally specifying a directory to format.
+fmt directory='':
+    uv run ruff format {{directory}}
+
+# Run type checking using ty, optionally specifying a directory to check.
+type-check directory='':
+    uv run ty check {{directory}}
+
+# Run tests using pytest, optionally specifying a directory to test.
+test directory='':
+    uv run pytest {{directory}}
+
+# Update .proto files to a specific version. Defaults to 'main' if no version is provided.
+update-proto version='':
+    ./protos/update.sh {{version}}
+
+# Generate Python code from .proto files. This should be run after updating the .proto files.
+@compile-proto:
+     echo {{SEPARATOR}}
+     echo "Compiling .proto files from {{PROTO_PATH}}/ to Python code under {{PYTHON_OUT_PATH}}/"
+     uv run protoc -I={{PROTO_PATH}} \
+            --python_betterproto_out={{PYTHON_OUT_PATH}} \
+            {{PROTO_PATH}}/*.proto
+     echo {{SEPARATOR}}
+     echo "Fixing cross-module imports..."
+     uv run python scripts/fix_proto_imports.py
+     echo "Formatting generated code with ruff..."
+     @uv run ruff check {{PYTHON_OUT_PATH}} --fix
+     @uv run ruff format {{PYTHON_OUT_PATH}}

ctrader_api_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elio Anthony Chukri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ctrader_api_client-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: ctrader-api-client
+Version: 0.1.0
+Summary: API Client to interact with the cTrader Open API spec
+Author-email: Elio <elioachukri@pm.me>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.13.0
+Requires-Dist: betterproto[compiler]>=1.2.5
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: tenacity>=9.1.4
+Description-Content-Type: text/markdown
+
+# cTrader API Client
+
+A Python client for the cTrader Open API. Provides a high-level async interface for trading operations, market data subscriptions, and account management.
+
+Documentation:
+- [Library Docs](https://elioachukri.github.io/ctrader-api-client/)
+- [cTrader Open API Docs](https://help.ctrader.com/open-api/)
+
+> Note that this library is in early development. The API may change, and some features may be incomplete. Contributions and feedback are welcome!
+
+## Requirements
+
+- Python 3.12+
+- An activated cTrader Open API application with client ID and secret
+- OAuth tokens for account authentication (see below)
+
+## Installation
+
+**Using uv (recommended):**
+
+```bash
+uv add ctrader-api-client
+```
+
+**Using pip:**
+
+```bash
+pip install ctrader-api-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from ctrader_api_client import CTraderClient, ClientConfig
+from ctrader_api_client.events import ReadyEvent, SpotEvent
+
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+client = CTraderClient(config)
+
+
+@client.on(SpotEvent, symbol_id=270)  # US500.cash
+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(
+            trader_login=12345678,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+        # Keep running to receive events
+        await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## OAuth Token Generation
+
+This library requires OAuth tokens from cTrader. For simple use cases, you can use [ctrader-oauth-fetcher](https://github.com/ElioaChukri/ctrader-oauth-fetcher) to generate tokens:
+
+```bash
+uvx ctrader-oauth-fetcher --client-id [ID] --client-secret [SECRET]
+```
+
+This opens a browser for authorization and returns your access token, refresh token, and expiry time.
+
+For production applications, implement the OAuth flow according to the [cTrader Open API documentation](https://help.ctrader.com/open-api/).
+
+## Features
+
+### Authentication
+
+```python
+# Authenticate the application
+await client.auth.authenticate_app()
+
+# Authenticate a trading account
+creds = await client.auth.authenticate_by_trader_login(
+    trader_login=12345678,
+    access_token="...",
+    refresh_token="...",
+    expires_at=1778617423,
+)
+
+# Tokens are automatically refreshed before expiry
+```
+
+### Market Data
+
+```python
+# Subscribe to spot prices
+await client.market_data.subscribe_spots(account_id, [symbol_id])
+
+# Subscribe to candles
+await client.market_data.subscribe_trendbars(account_id, symbol_id, TrendbarPeriod.M1)
+
+# Get historical data
+bars = await client.market_data.get_trendbars(
+    account_id, symbol_id, TrendbarPeriod.H1, from_ts, to_ts
+)
+```
+
+### Trading
+
+```python
+from ctrader_api_client.models import NewOrderRequest, ClosePositionRequest
+from ctrader_api_client.enums import OrderType, OrderSide
+
+# Place a market order
+request = NewOrderRequest(
+    symbol_id=symbol_id,
+    order_type=OrderType.MARKET,
+    side=OrderSide.BUY,
+    volume=100000,  # 1 lot in cents
+)
+result = await client.trading.create_order(account_id, request)
+
+# Get open positions
+positions = await client.trading.get_positions(account_id)
+
+# Close a position
+close_position = ClosePositionRequest(
+    position_id=position_id,
+    volume=100000,  # Close full volume
+)
+await client.trading.close_position(account_id, close_position)
+```
+
+### Event Handling
+
+```python
+from ctrader_api_client.events import (
+    SpotEvent,
+    ExecutionEvent,
+    ReadyEvent,
+    ReconnectedEvent,
+)
+
+# Price updates
+@client.on(SpotEvent, symbol_id=270)
+async def on_spot(event: SpotEvent):
+    print(f"{event.bid}/{event.ask}")
+
+# Order executions
+@client.on(ExecutionEvent, account_id=account_id)
+async def on_execution(event: ExecutionEvent):
+    print(f"Order {event.order_id}: {event.execution_type}")
+
+# Account ready (fires on initial auth and after reconnection)
+@client.on(ReadyEvent)
+async def on_ready(event: ReadyEvent):
+    # Set up subscriptions here
+    await client.market_data.subscribe_spots(event.account_id, symbols)
+
+# Connection restored
+@client.on(ReconnectedEvent)
+async def on_reconnected(event: ReconnectedEvent):
+    print(f"Reconnected, restored accounts: {event.restored_accounts}")
+```
+
+### Symbols
+
+```python
+# List all symbols
+symbols = await client.symbols.list_all(account_id)
+
+# Search by name
+results = await client.symbols.search(account_id, "EUR")
+
+# Get specific symbol
+symbol = await client.symbols.get_by_id(account_id, symbol_id)
+```
+
+### Account Information
+
+```python
+# Get account details
+account = await client.accounts.get_trader(account_id)
+print(f"Balance: {account.balance}")
+```
+
+## Automatic Reconnection
+
+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
+
+Use `ReadyEvent` to set up subscriptions that persist across reconnections.
+
+## Configuration
+
+```python
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+
+    # Connection settings
+    host="live.ctraderapi.com",  # or "demo.ctraderapi.com"
+    port=5035,
+    use_ssl=True,
+
+    # Timeouts
+    heartbeat_interval=10.0,
+    heartbeat_timeout=30.0, # Or 0 to disable server heartbeat checks
+    request_timeout=30.0,
+
+    # Reconnection
+    reconnect_attempts=5,
+    reconnect_min_wait=1.0,
+    reconnect_max_wait=60.0,
+)
+```

ctrader_api_client-0.1.0/README.md

@@ -0,0 +1,233 @@
+# cTrader API Client
+
+A Python client for the cTrader Open API. Provides a high-level async interface for trading operations, market data subscriptions, and account management.
+
+Documentation:
+- [Library Docs](https://elioachukri.github.io/ctrader-api-client/)
+- [cTrader Open API Docs](https://help.ctrader.com/open-api/)
+
+> Note that this library is in early development. The API may change, and some features may be incomplete. Contributions and feedback are welcome!
+
+## Requirements
+
+- Python 3.12+
+- An activated cTrader Open API application with client ID and secret
+- OAuth tokens for account authentication (see below)
+
+## Installation
+
+**Using uv (recommended):**
+
+```bash
+uv add ctrader-api-client
+```
+
+**Using pip:**
+
+```bash
+pip install ctrader-api-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from ctrader_api_client import CTraderClient, ClientConfig
+from ctrader_api_client.events import ReadyEvent, SpotEvent
+
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+client = CTraderClient(config)
+
+
+@client.on(SpotEvent, symbol_id=270)  # US500.cash
+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(
+            trader_login=12345678,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+        # Keep running to receive events
+        await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## OAuth Token Generation
+
+This library requires OAuth tokens from cTrader. For simple use cases, you can use [ctrader-oauth-fetcher](https://github.com/ElioaChukri/ctrader-oauth-fetcher) to generate tokens:
+
+```bash
+uvx ctrader-oauth-fetcher --client-id [ID] --client-secret [SECRET]
+```
+
+This opens a browser for authorization and returns your access token, refresh token, and expiry time.
+
+For production applications, implement the OAuth flow according to the [cTrader Open API documentation](https://help.ctrader.com/open-api/).
+
+## Features
+
+### Authentication
+
+```python
+# Authenticate the application
+await client.auth.authenticate_app()
+
+# Authenticate a trading account
+creds = await client.auth.authenticate_by_trader_login(
+    trader_login=12345678,
+    access_token="...",
+    refresh_token="...",
+    expires_at=1778617423,
+)
+
+# Tokens are automatically refreshed before expiry
+```
+
+### Market Data
+
+```python
+# Subscribe to spot prices
+await client.market_data.subscribe_spots(account_id, [symbol_id])
+
+# Subscribe to candles
+await client.market_data.subscribe_trendbars(account_id, symbol_id, TrendbarPeriod.M1)
+
+# Get historical data
+bars = await client.market_data.get_trendbars(
+    account_id, symbol_id, TrendbarPeriod.H1, from_ts, to_ts
+)
+```
+
+### Trading
+
+```python
+from ctrader_api_client.models import NewOrderRequest, ClosePositionRequest
+from ctrader_api_client.enums import OrderType, OrderSide
+
+# Place a market order
+request = NewOrderRequest(
+    symbol_id=symbol_id,
+    order_type=OrderType.MARKET,
+    side=OrderSide.BUY,
+    volume=100000,  # 1 lot in cents
+)
+result = await client.trading.create_order(account_id, request)
+
+# Get open positions
+positions = await client.trading.get_positions(account_id)
+
+# Close a position
+close_position = ClosePositionRequest(
+    position_id=position_id,
+    volume=100000,  # Close full volume
+)
+await client.trading.close_position(account_id, close_position)
+```
+
+### Event Handling
+
+```python
+from ctrader_api_client.events import (
+    SpotEvent,
+    ExecutionEvent,
+    ReadyEvent,
+    ReconnectedEvent,
+)
+
+# Price updates
+@client.on(SpotEvent, symbol_id=270)
+async def on_spot(event: SpotEvent):
+    print(f"{event.bid}/{event.ask}")
+
+# Order executions
+@client.on(ExecutionEvent, account_id=account_id)
+async def on_execution(event: ExecutionEvent):
+    print(f"Order {event.order_id}: {event.execution_type}")
+
+# Account ready (fires on initial auth and after reconnection)
+@client.on(ReadyEvent)
+async def on_ready(event: ReadyEvent):
+    # Set up subscriptions here
+    await client.market_data.subscribe_spots(event.account_id, symbols)
+
+# Connection restored
+@client.on(ReconnectedEvent)
+async def on_reconnected(event: ReconnectedEvent):
+    print(f"Reconnected, restored accounts: {event.restored_accounts}")
+```
+
+### Symbols
+
+```python
+# List all symbols
+symbols = await client.symbols.list_all(account_id)
+
+# Search by name
+results = await client.symbols.search(account_id, "EUR")
+
+# Get specific symbol
+symbol = await client.symbols.get_by_id(account_id, symbol_id)
+```
+
+### Account Information
+
+```python
+# Get account details
+account = await client.accounts.get_trader(account_id)
+print(f"Balance: {account.balance}")
+```
+
+## Automatic Reconnection
+
+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
+
+Use `ReadyEvent` to set up subscriptions that persist across reconnections.
+
+## Configuration
+
+```python
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+
+    # Connection settings
+    host="live.ctraderapi.com",  # or "demo.ctraderapi.com"
+    port=5035,
+    use_ssl=True,
+
+    # Timeouts
+    heartbeat_interval=10.0,
+    heartbeat_timeout=30.0, # Or 0 to disable server heartbeat checks
+    request_timeout=30.0,
+
+    # Reconnection
+    reconnect_attempts=5,
+    reconnect_min_wait=1.0,
+    reconnect_max_wait=60.0,
+)
+```

ctrader_api_client-0.1.0/docs/api/accounts.md

@@ -0,0 +1,44 @@
+# Accounts API
+
+Account information retrieval operations.
+
+Access via `client.accounts`.
+
+## AccountsAPI
+
+::: ctrader_api_client.api.AccountsAPI
+    options:
+      show_source: false
+      members:
+        - get_trader
+
+## Usage Examples
+
+### Get Account Details
+
+```python
+account = await client.accounts.get_trader(account_id)
+
+print(f"Balance: {account.get_balance()}")
+print(f"Leverage: {account.get_leverage()}")
+print(f"Account type: {account.account_type}")
+print(f"Broker name: {account.broker_name}")
+```
+
+## Account Discovery
+
+To discover available accounts for an access token, use the auth manager:
+
+```python
+# Get all accounts associated with a token
+accounts = await client.auth.get_accounts(access_token)
+
+for acc in accounts:
+    print(f"Login: {acc.trader_login}, Account ID: {acc.account_id}")
+    print(f"  Live: {acc.is_live}, Broker: {acc.broker_name}")
+```
+
+## Related
+
+- [Authentication](client.md#authentication) - Authenticating accounts
+- [Models - Account](models.md#account) - Account model reference

ctrader_api_client-0.1.0/docs/api/client.md

@@ -0,0 +1,52 @@
+# Client
+
+The main entry point for interacting with the cTrader API.
+
+## CTraderClient
+
+::: ctrader_api_client.CTraderClient
+    options:
+      show_source: false
+      members:
+        - __init__
+        - connect
+        - close
+        - "on"
+        - "off"
+        - auth
+        - accounts
+        - symbols
+        - trading
+        - market_data
+        - is_connected
+        - protocol
+
+## ClientConfig
+
+::: ctrader_api_client.ClientConfig
+    options:
+      show_source: false
+
+## Authentication
+
+The `client.auth` property provides access to authentication operations.
+
+::: ctrader_api_client.auth.AuthManager
+    options:
+      show_source: false
+      members:
+        - authenticate_app
+        - authenticate_account
+        - authenticate_by_trader_login
+        - get_accounts
+        - resolve_account_id
+        - get_credentials
+        - remove_account
+        - is_app_authenticated
+        - authenticated_accounts
+
+## AccountCredentials
+
+::: ctrader_api_client.auth.AccountCredentials
+    options:
+      show_source: false