xtb-api-python 0.5.2__tar.gz → 0.5.4__tar.gz

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/CHANGELOG.md

@@ -1,6 +1,104 @@
 # CHANGELOG
 
 
+## v0.5.4 (2026-04-15)
+
+### Bug Fixes
+
+- **ws**: Revert get_positions to reqId-based send
+  ([#9](https://github.com/liskeee/xtb-api-unofficial-python/pull/9),
+  [`d197b08`](https://github.com/liskeee/xtb-api-unofficial-python/commit/d197b08350e57a46b82adee5dcb206b2d068b852))
+
+v0.5.3's push-channel collection was based on a wrong diagnosis. Live API probing confirms the
+  xStation5 CoreAPI echoes getPositions on the NORMAL reqId response channel (status=0,
+  response=[...]), not as push events. The original implementation was correct.
+
+The 30s timeouts observed on the original 0.5.2 bot were something else — probably container-level
+  networking / first-call timing — not a protocol mismatch. The wrong fix in 0.5.3 made the problem
+  worse because get_positions() started returning [] instantly, causing the downstream bot to
+  auto-close positions it mistakenly thought were gone from the broker.
+
+Reverts the get_positions implementation to: res = await self.send("getPositions",
+  {"getAndSubscribeElement": {"eid": POSITIONS}}, timeout_ms=30000) return
+  parse_positions(self._extract_elements(res))
+
+Keeps `parse_position_trade` helper in parsers.py — harmless refactor. Removes
+  tests/test_get_positions_push.py — tested wrong behavior.
+
+Verified against real XTB account: all 5 open positions returned in ~1-2s via normal reqId response.
+
+Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
+
+
+## v0.5.3 (2026-04-15)
+
+### Bug Fixes
+
+- **ws**: Consume POSITIONS push channel in get_positions
+  ([`b0156bc`](https://github.com/liskeee/xtb-api-unofficial-python/commit/b0156bcc328630fb5e80952d87794780a8e30c73))
+
+XTB's xStation5 CoreAPI does not echo a reqId-correlated response for the `getPositions` RPC;
+  position data arrives exclusively via status=1 push events with eid=POSITIONS. The previous
+  implementation awaited a regular reqId-matched response and timed out after 30s on every call
+  against a live account.
+
+Fix: subscribe and consume the push burst. Register a one-shot 'position' handler, fire the
+  subscribe RPC (do not await its reply), and collect pushed events until either a quiet period (no
+  new position for 500 ms) or a max-wait ceiling (5 s) closes the window. Dedup by positionId so a
+  retriggered snapshot does not duplicate entries.
+
+parse_positions is refactored around a new parse_position_trade(trade) helper so the push handler
+  and the (still-supported) element-list path share the single source of truth for xcfdtrade →
+  Position mapping.
+
+Tests: 8 new tests cover parser extraction, burst collection, dedup, empty-on-timeout, listener
+  cleanup, and the not-connected guard.
+
+Fixes the downstream xtb-investor-pro bot's "get_positions failed" timeouts observed immediately
+  after the broker abstraction merge.
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+
+- **ws**: Drop unused parse_positions import
+  ([`63b3263`](https://github.com/liskeee/xtb-api-unofficial-python/commit/63b3263b64ef76ad7759b26a70e8d6ec26e6c9b3))
+
+### Code Style
+
+- Ruff format test_get_positions_push.py
+  ([`6e376a8`](https://github.com/liskeee/xtb-api-unofficial-python/commit/6e376a8cc1578d388f8469da3b49b02dee021841))
+
+### Documentation
+
+- Add design spec for v0.5 docs refresh
+  ([`c55d839`](https://github.com/liskeee/xtb-api-unofficial-python/commit/c55d839534ff39f5da55ec920fe6457eb82fb458))
+
+Captures the README/CONTRIBUTING/SECURITY drift between v0.4.x docs and the v0.5.2 surface (XTBAuth,
+  InstrumentRegistry, fill-price polling, volume guard, inlined publish jobs, supported-versions
+  table).
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+- Add implementation plan for v0.5 docs refresh
+  ([`0a4e3dd`](https://github.com/liskeee/xtb-api-unofficial-python/commit/0a4e3ddab03ad6cc87b4789cf39c772d85ca6d75))
+
+Pairs with the design spec at docs/superpowers/specs/2026-04-15-docs-refresh-v0.5-design.md and
+  tracks the four tasks executed in 97bbada.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+- Refresh README, CONTRIBUTING, SECURITY to v0.5 state
+  ([`97bbada`](https://github.com/liskeee/xtb-api-unofficial-python/commit/97bbada41434dacbf3139af6e26b70ad8a632ba6))
+
+- README: document XTBAuth alias, InstrumentRegistry, post-fill TradeResult.price, and the
+  volume-validation guard added in v0.5.0; drop stale 11,888+ symbol count. - CONTRIBUTING: trim
+  "before enabling on master" framing now that PSR is live; list both semantic-release.yml and
+  release.yml as required Trusted Publishers (PyPI matches the OIDC token's workflow filename
+  exactly, and v0.5.2 inlined the publish jobs into semantic-release.yml). - SECURITY: bump
+  supported-versions table from 0.3.x to 0.5.x.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+
 ## v0.5.2 (2026-04-15)
 
 ### Bug Fixes

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtb-api-python
-Version: 0.5.2
+Version: 0.5.4
 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
@@ -52,7 +52,9 @@ Python client for the XTB xStation5 trading platform. Dead-simple API that handl
 - **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
+- **Volume-Validated Orders** — `buy`/`sell` reject `volume < 1` before touching the wire
+- **Persistent Instrument Cache** — `InstrumentRegistry` caches symbol → instrument-ID lookups to disk
+- **Full Symbol Search** — Search and resolve all listed instruments with caching
 - **Modern Python** — async/await, Pydantic models, strict typing, Python 3.12+
 
 ## Requirements
@@ -129,6 +131,12 @@ async def main():
     # Search instruments
     results = await client.search_instrument("Apple")
 
+    # Persistent instrument cache (avoids re-fetching the full symbol list)
+    from xtb_api import InstrumentRegistry
+    registry = InstrumentRegistry("~/.xtb_instruments.json")
+    matched = await registry.populate(client, ["AAPL.US", "EURUSD"])
+    instrument_id = registry.get("AAPL.US")  # int | None
+
     # 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}")
@@ -162,6 +170,8 @@ await client.sell("CIG.PL", volume=100, options=TradeOptions(
 ))
 ```
 
+> `TradeResult.price` is populated by polling open positions immediately after fill. If the position cannot be located within the poll window, `price` remains `None`.
+
 ## API Reference
 
 ### `XTBClient`
@@ -194,6 +204,18 @@ await client.sell("CIG.PL", volume=100, options=TradeOptions(
 | `account_server` | No | `"XS-real1"` | gRPC account server |
 | `auto_reconnect` | No | `True` | Auto-reconnect on disconnect |
 
+### `InstrumentRegistry`
+
+Persistent symbol → instrument-ID cache, stored as JSON.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `InstrumentRegistry(path)` | — | Load (or create) the JSON cache at `path` |
+| `get(symbol)` | `int \| None` | Cached instrument ID for `symbol`, or `None` |
+| `set(symbol, id)` | `None` | Cache one mapping and persist immediately |
+| `populate(client, symbols)` | `dict[str, int]` | Download the full symbol list via `client`, match requested `symbols` (case-insensitive, dot-less fallback), persist, return new matches |
+| `ids` | `dict[str, int]` | Read-only copy of the full cache |
+
 ### WebSocket URLs
 
 | Environment | URL |
@@ -212,8 +234,9 @@ ws = client.ws
 # gRPC client (available after first trade)
 grpc = client.grpc_client
 
-# Auth manager
+# Auth manager (accessor, or import the public alias)
 auth = client.auth
+from xtb_api import XTBAuth  # public alias for the AuthManager class
 tgt = await auth.get_tgt()
 ```
 

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/README.md

@@ -16,7 +16,9 @@ Python client for the XTB xStation5 trading platform. Dead-simple API that handl
 - **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
+- **Volume-Validated Orders** — `buy`/`sell` reject `volume < 1` before touching the wire
+- **Persistent Instrument Cache** — `InstrumentRegistry` caches symbol → instrument-ID lookups to disk
+- **Full Symbol Search** — Search and resolve all listed instruments with caching
 - **Modern Python** — async/await, Pydantic models, strict typing, Python 3.12+
 
 ## Requirements
@@ -93,6 +95,12 @@ async def main():
     # Search instruments
     results = await client.search_instrument("Apple")
 
+    # Persistent instrument cache (avoids re-fetching the full symbol list)
+    from xtb_api import InstrumentRegistry
+    registry = InstrumentRegistry("~/.xtb_instruments.json")
+    matched = await registry.populate(client, ["AAPL.US", "EURUSD"])
+    instrument_id = registry.get("AAPL.US")  # int | None
+
     # 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}")
@@ -126,6 +134,8 @@ await client.sell("CIG.PL", volume=100, options=TradeOptions(
 ))
 ```
 
+> `TradeResult.price` is populated by polling open positions immediately after fill. If the position cannot be located within the poll window, `price` remains `None`.
+
 ## API Reference
 
 ### `XTBClient`
@@ -158,6 +168,18 @@ await client.sell("CIG.PL", volume=100, options=TradeOptions(
 | `account_server` | No | `"XS-real1"` | gRPC account server |
 | `auto_reconnect` | No | `True` | Auto-reconnect on disconnect |
 
+### `InstrumentRegistry`
+
+Persistent symbol → instrument-ID cache, stored as JSON.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `InstrumentRegistry(path)` | — | Load (or create) the JSON cache at `path` |
+| `get(symbol)` | `int \| None` | Cached instrument ID for `symbol`, or `None` |
+| `set(symbol, id)` | `None` | Cache one mapping and persist immediately |
+| `populate(client, symbols)` | `dict[str, int]` | Download the full symbol list via `client`, match requested `symbols` (case-insensitive, dot-less fallback), persist, return new matches |
+| `ids` | `dict[str, int]` | Read-only copy of the full cache |
+
 ### WebSocket URLs
 
 | Environment | URL |
@@ -176,8 +198,9 @@ ws = client.ws
 # gRPC client (available after first trade)
 grpc = client.grpc_client
 
-# Auth manager
+# Auth manager (accessor, or import the public alias)
 auth = client.auth
+from xtb_api import XTBAuth  # public alias for the AuthManager class
 tgt = await auth.get_tgt()
 ```
 

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xtb-api-python"
-version = "0.5.2"
+version = "0.5.4"
 description = "Python port of unofficial XTB xStation5 API client"
 readme = "README.md"
 license = "MIT"

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/src/xtb_api/ws/parsers.py

@@ -49,36 +49,41 @@ def parse_balance(
     )
 
 
+def parse_position_trade(trade: dict[str, Any]) -> Position:
+    """Convert a single `xcfdtrade` dict (as pushed on the POSITIONS
+    subscription) into a `Position`.
+
+    Callers that receive the wrapped `{value: {xcfdtrade: ...}}` shape
+    should use `parse_positions()` instead.
+    """
+    side_val = int(trade.get("side", 0))
+    return Position(
+        symbol=str(trade.get("symbol", "")),
+        instrument_id=int(trade["idQuote"]) if trade.get("idQuote") is not None else None,
+        volume=float(trade.get("volume", 0)),
+        current_price=0.0,
+        open_price=float(trade.get("openPrice", 0)),
+        stop_loss=float(trade["sl"]) if trade.get("sl") and trade["sl"] != 0 else None,
+        take_profit=float(trade["tp"]) if trade.get("tp") and trade["tp"] != 0 else None,
+        profit_percent=0.0,
+        profit_net=0.0,
+        swap=float(trade["swap"]) if trade.get("swap") is not None else None,
+        side="buy" if side_val == Xs6Side.BUY else "sell",
+        order_id=str(trade["positionId"]) if trade.get("positionId") is not None else None,
+        commission=float(trade["commission"]) if trade.get("commission") is not None else None,
+        margin=float(trade["margin"]) if trade.get("margin") is not None else None,
+        open_time=int(trade["openTime"]) if trade.get("openTime") is not None else None,
+    )
+
+
 def parse_positions(elements: list[dict[str, Any]]) -> list[Position]:
     """Parse open trading positions from subscription elements."""
     positions: list[Position] = []
-
     for el in elements:
         trade = (el or {}).get("value", {}).get("xcfdtrade")
         if not trade:
             continue
-
-        side_val = int(trade.get("side", 0))
-        positions.append(
-            Position(
-                symbol=str(trade.get("symbol", "")),
-                instrument_id=int(trade["idQuote"]) if trade.get("idQuote") is not None else None,
-                volume=float(trade.get("volume", 0)),
-                current_price=0.0,
-                open_price=float(trade.get("openPrice", 0)),
-                stop_loss=float(trade["sl"]) if trade.get("sl") and trade["sl"] != 0 else None,
-                take_profit=float(trade["tp"]) if trade.get("tp") and trade["tp"] != 0 else None,
-                profit_percent=0.0,
-                profit_net=0.0,
-                swap=float(trade["swap"]) if trade.get("swap") is not None else None,
-                side="buy" if side_val == Xs6Side.BUY else "sell",
-                order_id=str(trade["positionId"]) if trade.get("positionId") is not None else None,
-                commission=float(trade["commission"]) if trade.get("commission") is not None else None,
-                margin=float(trade["margin"]) if trade.get("margin") is not None else None,
-                open_time=int(trade["openTime"]) if trade.get("openTime") is not None else None,
-            )
-        )
-
+        positions.append(parse_position_trade(trade))
     return positions
 
 

{xtb_api_python-0.5.2 → xtb_api_python-0.5.4}/src/xtb_api/ws/ws_client.py

@@ -534,13 +534,19 @@ class XTBWebSocketClient:
         return parse_balance(self._extract_elements(res), account.currency, account.accountNo)
 
     async def get_positions(self) -> list[Position]:
-        """Get all open trading positions."""
+        """Get all open trading positions.
+
+        XTB's xStation5 CoreAPI echoes the position snapshot on the normal
+        reqId-correlated response channel (not the push channel, despite the
+        `getAndSubscribeElement` keyword). The subscription it sets up also
+        emits per-position updates via `_emit("position", ...)`; those are
+        orthogonal to the snapshot returned here.
+        """
         res = await self.send(
             "getPositions",
             {"getAndSubscribeElement": {"eid": SubscriptionEid.POSITIONS}},
             timeout_ms=30000,
         )
-
         return parse_positions(self._extract_elements(res))
 
     async def get_orders(self) -> list[PendingOrder]: