ctrader-api-client 0.1.0__py3-none-any.whl

ctrader_api_client-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,43 @@
+ctrader_api_client/__init__.py,sha256=4YAr1TKuOryIhDumTS5iKwRAc-BwxgxFtr6HkOczCBY,1437
+ctrader_api_client/client.py,sha256=oS3J1YiueswXbdKJ9iAdDdtu7zQNqA1RQIX7I_NBX7A,14474
+ctrader_api_client/config.py,sha256=AvJLWBgTKqRcOGy6NLE28wtcAZzbA_PjMymHyhBBB9U,1845
+ctrader_api_client/enums.py,sha256=r57VZkvjKYXH-ff3V7xTAZAzGi7rbLzoF2Fh7TPVY7A,2774
+ctrader_api_client/exceptions.py,sha256=C4k79e9v3Xl-h1avlho6aY8xm3GAyasnvqnqGy8tzHw,7828
+ctrader_api_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctrader_api_client/_internal/__init__.py,sha256=3uiL23pBLEx2Xl_ejhHQBnWkfF53XQYgF49cWFGnsgM,511
+ctrader_api_client/_internal/messages.py,sha256=Z4p2LXSTS3s8eeLGlRU2EuMoFqmGLxKP3jH8-m_1FoM,15394
+ctrader_api_client/_internal/serialization.py,sha256=6YvdxOAAZmqtw13KcJuVVA3qeKvbKRm1fsLFOD-aPzM,2473
+ctrader_api_client/_internal/proto/OpenApiCommonMessages.py,sha256=cjga95e4C_OSy8bCm78tJZ6i9Wu9OSsFlFRpnNhjZpM,1388
+ctrader_api_client/_internal/proto/OpenApiCommonModelMessages.py,sha256=NywbMSf7KNJaJSv41ymB1_JgrB0STVh2yeFEekg6-GI,706
+ctrader_api_client/_internal/proto/OpenApiMessages.py,sha256=6aMnUmY6CYrtmMNvGTG8qPsijh2D5hDYo2R3Csja1R4,39293
+ctrader_api_client/_internal/proto/OpenApiModelMessages.py,sha256=KE-k7H9-UDsh7cA8bQF2EZrloUhDkxHRRtEtorWqjnA,27125
+ctrader_api_client/_internal/proto/__init__.py,sha256=-wZhbTn18bgtwOrBjI3EZfckAdX3WlAL5NTad88RKxI,9413
+ctrader_api_client/api/__init__.py,sha256=MrawYa778pN2YXPw92X6D7anIOLTfJmvT9xl0uxfTlM,562
+ctrader_api_client/api/accounts.py,sha256=GTNwAqYHHvxlWc0iIUZSvka9Iqh4WswrVI9IIyuAs0k,1986
+ctrader_api_client/api/market_data.py,sha256=fiyWjvkL1wqTBw5NllyrhBQ6tszoR_fqgfPrO5T-7-A,14325
+ctrader_api_client/api/symbols.py,sha256=2GAB21kxSkcF-qcRxJOL9--pk0o9Ma6DZ2kv5xmzSig,5170
+ctrader_api_client/api/trading.py,sha256=oiwymq2SUwtXxP4kbIu1E-SzLUkQjBmtKzfaOec9LAA,16282
+ctrader_api_client/auth/__init__.py,sha256=ykxE1xPqJl9T3kOpU8a0UT0Tn107GqLGEOS_gqkou_0,287
+ctrader_api_client/auth/credentials.py,sha256=diMXNy8hNci1eyhbkhGnUWNWB0pn18xtqQXc7_okdIU,2153
+ctrader_api_client/auth/manager.py,sha256=r5kjSCjrAS2rQGW3wZAAOInijDJA0YLnGmXrrBX-6hE,18130
+ctrader_api_client/connection/__init__.py,sha256=aHW0ahsLcW__P0KXCzfDL-pdM14IBeMiHKp2npjbo2Q,360
+ctrader_api_client/connection/heartbeat.py,sha256=ASVysDtA0nsd3q57kNdpa8-C0x8o5omb-_evmQrKDck,4118
+ctrader_api_client/connection/protocol.py,sha256=oufw1mDawyC_gO2Es3XYCwLZVAzFsRwG1-3UyYWCk1M,12802
+ctrader_api_client/connection/transport.py,sha256=9zOqaXtPgWtjeNgxqgVHmd06ZMrAgG8jgRMjGy-j6rQ,3808
+ctrader_api_client/events/__init__.py,sha256=kAfzhbFLjcJzCeuQOhc7dCXkj9W77KeoOzeDWj-hmVo,1403
+ctrader_api_client/events/emitter.py,sha256=PwcxT4SLFf5zUFOMiGLhAq9qgOjIleVenH3m_fDT6Y0,8563
+ctrader_api_client/events/router.py,sha256=h0GRF8ZX8PeJswoK1V90bq7iwxMO6-zjnYXgwO1-q8I,14940
+ctrader_api_client/events/types.py,sha256=bEBGPn1TF2h-KJS3-LHuybrdxZJiRYxL-2S17b9aaWM,9368
+ctrader_api_client/models/__init__.py,sha256=I4Xdz_8mCvv_nxSwFJQPOQoyBPlHYnVtsWNEPtupqOE,1178
+ctrader_api_client/models/_base.py,sha256=YQTsIhu7HwQd-fa2U-CaDgKZDBkasLY3BEcVGTMuLcE,410
+ctrader_api_client/models/account.py,sha256=HuWFCH1CAdXMmnUmUIrSDfWhlk5huKF7dc6obor_qHg,6534
+ctrader_api_client/models/deal.py,sha256=7Keh2bnPFm_HvHh-vLwGIG7b6TrTBc9ywrLa2epp2CU,8307
+ctrader_api_client/models/market_data.py,sha256=PkCns7eVweq9aKFoSKCXmcIeTU3SWTyxUeUsoSOPVIY,5349
+ctrader_api_client/models/order.py,sha256=bd9aDZexfVE_XRWFB5yYj2jGFuybzLXRt8tNE5xlz48,10044
+ctrader_api_client/models/position.py,sha256=bppivlIRhQPmTOnj2J_R_61wVTePTTjR92VMZBQ-i7k,7431
+ctrader_api_client/models/requests.py,sha256=OrxtF-cYi8rs3uT0lOzNLBBfrO5i-sqLjOayGInp0UI,10940
+ctrader_api_client/models/symbol.py,sha256=lVNc-gXMo6kwQbpexiCJn7FKbDIN17K1bfxEID9r18A,6309
+ctrader_api_client-0.1.0.dist-info/METADATA,sha256=x2wEm7W6DX0VBZoEwxcVADVqyCH29WfsjFLrKa8BoV4,6635
+ctrader_api_client-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ctrader_api_client-0.1.0.dist-info/licenses/LICENSE,sha256=_ZY-NhfjiEbAnrCG6drSXwAPkbibV3NgK68KC95gl6I,1076
+ctrader_api_client-0.1.0.dist-info/RECORD,,

ctrader_api_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ctrader_api_client-0.1.0.dist-info/licenses/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.