xtb-api-python 0.5.2__py3-none-any.whl

xtb_api_python-0.5.2.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: xtb-api-python
+Version: 0.5.2
+Summary: Python port of unofficial XTB xStation5 API client
+Project-URL: Homepage, https://github.com/liskeee/xtb-api-python
+Project-URL: Repository, https://github.com/liskeee/xtb-api-python
+Project-URL: Issues, https://github.com/liskeee/xtb-api-python/issues
+Project-URL: Changelog, https://github.com/liskeee/xtb-api-python/blob/master/CHANGELOG.md
+Author-email: Łukasz Lis <ll.lukasz.lis@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,trading,websocket,xstation5,xtb
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.40
+Requires-Dist: pydantic>=2.5
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: totp
+Requires-Dist: pyotp>=2.9.0; extra == 'totp'
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://img.shields.io/pypi/v/xtb-api-python.svg)](https://pypi.org/project/xtb-api-python/)
+[![Python versions](https://img.shields.io/pypi/pyversions/xtb-api-python.svg)](https://pypi.org/project/xtb-api-python/)
+[![CI](https://github.com/liskeee/xtb-api-python/actions/workflows/ci.yml/badge.svg)](https://github.com/liskeee/xtb-api-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# xtb-api-python
+
+> **Unofficial** — Reverse-engineered from xStation5. Not affiliated with XTB. Use at your own risk.
+
+Python client for the XTB xStation5 trading platform. Dead-simple API that handles all authentication, token refresh, and transport selection transparently.
+
+## Features
+
+- **Single Client** — One `XTBClient` handles everything, no mode selection needed
+- **Auto Auth** — Full CAS login flow with automatic TGT/JWT refresh
+- **2FA Support** — Automatic TOTP handling when `totp_secret` is provided
+- **Real-time Data** — Live quotes, positions, balance via WebSocket push events
+- **Trading** — Buy/sell market orders with SL/TP via gRPC-web
+- **11,888+ Instruments** — Full symbol search with caching
+- **Modern Python** — async/await, Pydantic models, strict typing, Python 3.12+
+
+## Requirements
+
+- Python **3.12 or 3.13**
+- Chromium browser (installed via playwright — see post-install step below)
+- An XTB trading account
+
+## Install
+
+```bash
+pip install xtb-api-python
+
+# With automatic 2FA handling:
+pip install "xtb-api-python[totp]"
+```
+
+### Post-install setup (REQUIRED)
+
+This library uses [Playwright](https://playwright.dev/python/) to authenticate with
+XTB's servers (the REST login path is blocked by a WAF). **After** `pip install`,
+you must download the Chromium binary:
+
+```bash
+playwright install chromium
+```
+
+Without this step, the first call to `client.connect()` will fail with a
+`CASError("BROWSER_CHROMIUM_MISSING", ...)` and a pointer back here.
+
+To verify your install is complete, run:
+
+```bash
+python -m xtb_api doctor
+```
+
+### Development install
+
+```bash
+pip install -e ".[dev,totp]"
+playwright install chromium
+pre-commit install
+```
+
+## Quick Start
+
+```python
+import asyncio
+from xtb_api import XTBClient
+
+async def main():
+    client = XTBClient(
+        email="your@email.com",
+        password="your-password",
+        account_number=12345678,
+        totp_secret="BASE32SECRET",      # optional, auto-handles 2FA
+        session_file="~/.xtb_session",   # optional, persists auth across restarts
+    )
+
+    await client.connect()
+
+    # Account data
+    balance = await client.get_balance()
+    print(f"Balance: {balance.balance} {balance.currency}")
+
+    positions = await client.get_positions()
+    orders = await client.get_orders()
+
+    # Live quote
+    quote = await client.get_quote("EURUSD")
+    if quote:
+        print(f"Bid: {quote.bid}, Ask: {quote.ask}")
+
+    # Search instruments
+    results = await client.search_instrument("Apple")
+
+    # Trading (USE WITH CAUTION!)
+    result = await client.buy("AAPL.US", volume=1, stop_loss=150.0, take_profit=200.0)
+    print(f"Order: {result.order_id}")
+
+    await client.disconnect()
+
+asyncio.run(main())
+```
+
+### Real-time Events
+
+```python
+client.on("tick", lambda tick: print(f"{tick['symbol']}: {tick['bid']}/{tick['ask']}"))
+client.on("position", lambda pos: print(f"Position update: {pos['symbol']}"))
+
+await client.subscribe_ticks("EURUSD")
+```
+
+### Advanced Trade Options
+
+```python
+from xtb_api import TradeOptions
+
+# Simple: flat kwargs
+await client.buy("EURUSD", volume=1, stop_loss=1.0850, take_profit=1.0950)
+
+# Advanced: TradeOptions object
+await client.sell("CIG.PL", volume=100, options=TradeOptions(
+    trailing_stop=50,
+    amount=1000.0,  # amount-based sizing
+))
+```
+
+## API Reference
+
+### `XTBClient`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `None` | Connect and authenticate |
+| `disconnect()` | `None` | Disconnect and clean up |
+| `get_balance()` | `AccountBalance` | Account balance, equity, free margin |
+| `get_positions()` | `list[Position]` | Open trading positions |
+| `get_orders()` | `list[PendingOrder]` | Pending limit/stop orders |
+| `get_quote(symbol)` | `Quote \| None` | Current bid/ask for a symbol |
+| `search_instrument(query)` | `list[InstrumentSearchResult]` | Search instruments |
+| `buy(symbol, volume, ...)` | `TradeResult` | Execute BUY order |
+| `sell(symbol, volume, ...)` | `TradeResult` | Execute SELL order |
+| `on(event, callback)` | `None` | Register event handler |
+| `subscribe_ticks(symbol)` | `None` | Subscribe to real-time ticks |
+
+### Constructor Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `email` | Yes | — | XTB account email |
+| `password` | Yes | — | XTB account password |
+| `account_number` | Yes | — | XTB account number |
+| `totp_secret` | No | `""` | Base32 TOTP secret for auto 2FA |
+| `session_file` | No | `None` | Path to persist auth session |
+| `ws_url` | No | Real server | WebSocket endpoint URL |
+| `endpoint` | No | `"meta1"` | Server endpoint name |
+| `account_server` | No | `"XS-real1"` | gRPC account server |
+| `auto_reconnect` | No | `True` | Auto-reconnect on disconnect |
+
+### WebSocket URLs
+
+| Environment | URL |
+|-------------|-----|
+| Real | `wss://api5reala.x-station.eu/v1/xstation` (default) |
+| Demo | `wss://api5demoa.x-station.eu/v1/xstation` |
+
+### Advanced: Direct Access
+
+For advanced use cases, access the underlying clients:
+
+```python
+# WebSocket client (always available)
+ws = client.ws
+
+# gRPC client (available after first trade)
+grpc = client.grpc_client
+
+# Auth manager
+auth = client.auth
+tgt = await auth.get_tgt()
+```
+
+## Architecture
+
+```
+XTBClient (public facade)
+|
++-- AuthManager (shared auth session)
+|   +-- CASClient (REST + Playwright browser auth)
+|   +-- TGT cache (memory + disk)
+|
++-- XTBWebSocketClient (quotes, positions, balance)
+|   +-- Auto-reconnect with fresh service tickets
+|
++-- GrpcClient (trading, lazy-initialized)
+    +-- JWT auto-refresh from shared TGT
+```
+
+## How Authentication Works
+
+1. **Login** — REST CAS attempt, falls back to Playwright browser if WAF blocks
+2. **TGT** — 8-hour token, cached in memory + optional session file
+3. **Service Ticket** — Derived from TGT, used for WebSocket login
+4. **JWT** — 5-minute token for gRPC trading, auto-refreshed from TGT
+5. **2FA** — Automatic TOTP if `totp_secret` provided
+
+All token refresh is transparent. If a TGT expires mid-session, the full auth chain re-runs automatically.
+
+## Disclaimer
+
+This is an **unofficial**, community-driven project. NOT affiliated with, endorsed by, or connected to XTB S.A.
+
+- **Use at your own risk** — trading involves financial risk
+- **No warranty** — provided "as is"
+- **API stability** — XTB may change their internal APIs at any time
+- **Always test on demo accounts first**
+
+## License
+
+MIT

xtb_api_python-0.5.2.dist-info/RECORD

@@ -0,0 +1,28 @@
+xtb_api/__init__.py,sha256=4uuWQIVA508vYbb6_KOsyUXkWRIC3Jxv9vhCVcky8Q0,1581
+xtb_api/__main__.py,sha256=r0Du6KYGst8U0l9dkLV55EwxqBFsQqwwPZ1wq5UdgZE,4688
+xtb_api/client.py,sha256=DDDdQFrSLcwT3OlImam4s9lFiTbZ5M1a6pxA-iu30C4,17168
+xtb_api/exceptions.py,sha256=Im69z0LPxhR6mV3XTrh99V8ai-hteczZJkhayjQC55Q,1522
+xtb_api/instruments.py,sha256=GAfVtIX9siIkbyxRCi_cFWI9TWLoLnBm4zw-3_AzWQE,4857
+xtb_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xtb_api/utils.py,sha256=xpJ3QTfeCkMnhOu_YCdRq2KPL0hTMC7Y_wqvvCWLM4s,1781
+xtb_api/auth/__init__.py,sha256=p9Devj_dJBgH6awKdUU4uJwBkZaYSz5v932SqEEWHY4,229
+xtb_api/auth/auth_manager.py,sha256=JCViygItScN3Dpwzjxy-ZuywFB6r5fAYycg-HW9l_ss,12174
+xtb_api/auth/browser_auth.py,sha256=Z9CkbcyZ_AyeFWVaRS3QlqTpC2st7_tSb3UMU5UMh6o,12383
+xtb_api/auth/cas_client.py,sha256=f4Rs9LI8A1Y4wTJ1itOGS8cjwnfjAUT5o_Q8TFKplE0,20292
+xtb_api/grpc/__init__.py,sha256=puaZSuPIJ8XWt29c02G95wfWFem5YPDa73Z3PgQI7sM,569
+xtb_api/grpc/client.py,sha256=fdmkCVbZqLQgxrr7olWuPFvAmJdDVX2k-fzsCcO5IGE,11173
+xtb_api/grpc/proto.py,sha256=jglStrhkWrKzEGO2PWXL2iTEm-wulFK99OijD2rQFKU,8753
+xtb_api/grpc/types.py,sha256=178wH9tm1vge7D3O0trOIZCk9qmSzH0PAfiHfjUml8Y,298
+xtb_api/types/__init__.py,sha256=XY4_GL07XDS_wo7iqHB-tsu3SCOm0s9dwg-kr62t6rA,236
+xtb_api/types/enums.py,sha256=p-jzwyAevBFhzwO25Xh3EAIDmd6WMVuI5_I8yd3GvOQ,1837
+xtb_api/types/instrument.py,sha256=uxGB3LrE1IgP3UeEMu9c50Mvqmplr3DmgUbLwjg4i14,927
+xtb_api/types/trading.py,sha256=fGLGga-kMX7vDvE848H7lUnw-kHpTcqq6a8P25RDu2k,3033
+xtb_api/types/websocket.py,sha256=66vZSC6hdlglO5EEqPSciBbtBVunGV0L-0pLiZwVrQo,3705
+xtb_api/ws/__init__.py,sha256=6QNzj6rXiGWa9vU-o_IvVTqU7nDqPaYDJnTQhX-1pXY,106
+xtb_api/ws/parsers.py,sha256=ApEjm3uX-QhiyaM8U1RpZByVbU0ijL5jnm4FFIApyNk,6222
+xtb_api/ws/ws_client.py,sha256=X_bBaAw80aHEECRol33aDJqMfVu5onqrQ8a7ANrrZ8s,34077
+xtb_api_python-0.5.2.dist-info/METADATA,sha256=QNHFjD2C2vtf_aqSVn6pT9ikkPhBcfEK9K0pN6Coxpc,8464
+xtb_api_python-0.5.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+xtb_api_python-0.5.2.dist-info/entry_points.txt,sha256=HhB6G6gQU-c43Y0YowXSqXXOTCd1CK8fvy5guFdzy0s,50
+xtb_api_python-0.5.2.dist-info/licenses/LICENSE,sha256=fEnrQRlNl8P7GRU9YAaLjbNRfQ0qe0At5LRkCmM4j0I,1073
+xtb_api_python-0.5.2.dist-info/RECORD,,

xtb_api_python-0.5.2.dist-info/WHEEL

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

xtb_api_python-0.5.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xtb-api = xtb_api.__main__:main

xtb_api_python-0.5.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Łukasz Lis
+
+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.