fxsocket 0.4.0__tar.gz → 0.5.0__tar.gz

{fxsocket-0.4.0 → fxsocket-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fxsocket
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python SDK for the FxSocket API — MT4/MT5 account management, trading, and real-time streaming.
 Project-URL: Homepage, https://fxsocket.com
 Project-URL: Documentation, https://api.fxsocket.com/v1/docs
@@ -229,6 +229,35 @@ with Client(api_key="fxs_live_…") as fx:
                 print(event.data.bid, event.data.ask)
 ```
 
+### Trade events
+
+A `TradeUpdate` carries the full deal: `commission`, `swap`, `magic` and a
+real `comment` alongside `profit` (bridges MT5 0.12+ / MT4 0.11+; zero on
+older pods). Event-only P&L accounting is `data.net_profit`
+(`profit + commission + swap`).
+
+Correlate the `In` and `Out` events of one round-trip through
+`data.position` — on MT5, `Out` deals carry `magic=0` / `comment=""` unless
+the closing request set them (platform behavior, not a bridge gap), so
+position id is the reliable join key. On MT4, `deal` is always 0 and
+`position` equals the order ticket. The same id appears as `position` in
+`order_history()` rows (bridges MT5 0.14+ / MT4 0.13+) and as
+`position_id` in `position_history()`.
+
+If the bridge can't fully enrich an event in time it sets
+`data.degraded=True`: identifiers, `symbol`, `type`, `volume` and `price`
+are still trustworthy, but `entry` is `"Unknown"` and the cost fields are
+zeroed — reconcile that deal via `order_history()`.
+
+```python
+async for event in s:
+    match event:
+        case TradeUpdate() as t if t.data.degraded:
+            reconcile_later(t.data.position)     # costs/entry unreliable
+        case TradeUpdate() as t if t.data.entry == DealEntry.OUT:
+            print(t.data.position, "closed, net", t.data.net_profit)
+```
+
 ## Errors
 
 Every failure raises a subclass of `fxsocket.FxSocketError`:

{fxsocket-0.4.0 → fxsocket-0.5.0}/README.md

@@ -202,6 +202,35 @@ with Client(api_key="fxs_live_…") as fx:
                 print(event.data.bid, event.data.ask)
 ```
 
+### Trade events
+
+A `TradeUpdate` carries the full deal: `commission`, `swap`, `magic` and a
+real `comment` alongside `profit` (bridges MT5 0.12+ / MT4 0.11+; zero on
+older pods). Event-only P&L accounting is `data.net_profit`
+(`profit + commission + swap`).
+
+Correlate the `In` and `Out` events of one round-trip through
+`data.position` — on MT5, `Out` deals carry `magic=0` / `comment=""` unless
+the closing request set them (platform behavior, not a bridge gap), so
+position id is the reliable join key. On MT4, `deal` is always 0 and
+`position` equals the order ticket. The same id appears as `position` in
+`order_history()` rows (bridges MT5 0.14+ / MT4 0.13+) and as
+`position_id` in `position_history()`.
+
+If the bridge can't fully enrich an event in time it sets
+`data.degraded=True`: identifiers, `symbol`, `type`, `volume` and `price`
+are still trustworthy, but `entry` is `"Unknown"` and the cost fields are
+zeroed — reconcile that deal via `order_history()`.
+
+```python
+async for event in s:
+    match event:
+        case TradeUpdate() as t if t.data.degraded:
+            reconcile_later(t.data.position)     # costs/entry unreliable
+        case TradeUpdate() as t if t.data.entry == DealEntry.OUT:
+            print(t.data.position, "closed, net", t.data.net_profit)
+```
+
 ## Errors
 
 Every failure raises a subclass of `fxsocket.FxSocketError`:

fxsocket-0.5.0/src/fxsocket/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

{fxsocket-0.4.0 → fxsocket-0.5.0}/src/fxsocket/enums.py

@@ -103,11 +103,17 @@ class OrderKind(str, Enum):
 
 
 class DealEntry(str, Enum):
-    """Direction of a deal in trade history / the ``trades`` stream."""
+    """Direction of a deal in trade history / the ``trades`` stream.
+
+    ``UNKNOWN`` appears only on degraded ``trades``-stream frames, where the
+    bridge could not resolve the deal direction in time — see
+    ``TradeEventData.degraded``.
+    """
 
     IN = "In"
     OUT = "Out"
     IN_OUT = "InOut"
+    UNKNOWN = "Unknown"
 
 
 class HealthStatus(str, Enum):

{fxsocket-0.4.0 → fxsocket-0.5.0}/src/fxsocket/models.py

@@ -205,10 +205,20 @@ class HistoryTrade(_Camel):
 
     On MT4 this is one row per closed *order* (no per-deal granularity);
     ``order`` aliases the ticket and ``entry`` is constant.
+
+    ``position`` groups the rows of one round-trip: on MT5 it is the deal's
+    ``DEAL_POSITION_ID`` — the ``In`` and ``Out`` rows share it, and it
+    equals the ``trades``-stream events' ``position`` and
+    :attr:`PositionTrade.position_id` — so an exit row alone identifies the
+    position it closed even though MT5 exits usually carry ``magic=0`` /
+    ``comment=""``. On MT4 it equals the order ticket. 0 on pods older than
+    bridge MT5 0.14 / MT4 0.13. (Netting-account caveat: a reversal
+    ``InOut`` row reports the position it belongs to *after* processing.)
     """
 
     ticket: int
     order: int
+    position: int = 0
     symbol: str
     type: str
     entry: str
@@ -553,8 +563,29 @@ class HealthChecks(_Camel):
 class TradeEventData(_Camel):
     """A trade transaction pushed on the ``trades`` stream.
 
-    ``deal`` / ``position`` are 0 on MT4 (no per-deal model); ``entry`` is the
-    deal direction (compare against :class:`fxsocket.DealEntry`).
+    ``entry`` is the deal direction (compare against
+    :class:`fxsocket.DealEntry`; ``"Unknown"`` appears only on degraded
+    frames). ``commission`` / ``swap`` / ``magic`` (and a real ``comment`` on
+    MT5) arrive on bridges MT5 0.12+ / MT4 0.11+ and default to 0 before
+    that; a deal's net P&L is ``profit + commission + swap``
+    (:attr:`net_profit`).
+
+    Platform semantics:
+
+    * **MT5** — ``Out`` deals carry ``magic=0`` / ``comment=""`` unless the
+      closing request set them (a platform property, not a bridge gap).
+      Correlate ``In``/``Out`` through ``position``, which is present on
+      every event.
+    * **MT4** — orders keep their magic/comment for the whole lifecycle, so
+      both ``In`` and ``Out`` events carry them; ``deal`` is always 0 and
+      ``position`` equals the order ticket.
+
+    ``degraded=True`` (bridges MT5 0.13+ / MT4 0.12+; structurally always
+    ``False`` on MT4) means the bridge could not fully enrich the event in
+    time: the identifiers, ``symbol``, ``type``, ``volume`` and ``price`` are
+    trustworthy, but ``entry`` is ``"Unknown"`` and ``profit`` /
+    ``commission`` / ``swap`` / ``magic`` / ``comment`` are zeroed —
+    reconcile the deal via ``GET /OrderHistory``.
     """
 
     deal: int
@@ -566,8 +597,17 @@ class TradeEventData(_Camel):
     volume: float
     price: float
     profit: float
+    commission: float = 0.0
+    swap: float = 0.0
+    magic: int = 0
     comment: str
     time: str
+    degraded: bool = False
+
+    @property
+    def net_profit(self) -> float:
+        """Deal P&L including costs: ``profit + commission + swap``."""
+        return self.profit + self.commission + self.swap
 
 
 class TerminalStatusData(_Camel):

{fxsocket-0.4.0 → fxsocket-0.5.0}/tests/test_stream.py

@@ -13,6 +13,7 @@ from fxsocket import (
     AccountUpdate,
     AsyncStream,
     Bar,
+    DealEntry,
     PositionsUpdate,
     Stream,
     StreamWarning,
@@ -157,12 +158,19 @@ def test_parse_event_all_types() -> None:
                 "volume": 0.1,
                 "price": 1.0,
                 "profit": 0.0,
-                "comment": "",
+                "commission": -0.04,
+                "swap": 0.0,
+                "magic": 1000999,
+                "comment": "CN_9999_8888",
                 "time": "t",
+                "degraded": False,
             },
         }
     )
     assert isinstance(trade, TradeUpdate) and trade.data.entry == "In"
+    assert trade.data.commission == -0.04 and trade.data.magic == 1000999
+    assert trade.data.degraded is False
+    assert trade.data.net_profit == pytest.approx(-0.04)
 
     term = parse_event(
         {
@@ -192,6 +200,61 @@ def test_parse_event_all_types() -> None:
     assert isinstance(parse_event({"type": "subscriptions", "data": []}), Subscriptions)
 
 
+def test_parse_trade_pre_012_bridge_defaults() -> None:
+    """Bridges older than MT5 0.12 / MT4 0.11 omit the enrichment fields."""
+    trade = parse_event(
+        {
+            "type": "trade",
+            "data": {
+                "deal": 9,
+                "order": 10,
+                "position": 10,
+                "symbol": "EURUSD",
+                "type": "Buy",
+                "entry": "In",
+                "volume": 0.1,
+                "price": 1.0,
+                "profit": 0.0,
+                "comment": "",
+                "time": "t",
+            },
+        }
+    )
+    assert isinstance(trade, TradeUpdate)
+    assert trade.data.commission == 0.0 and trade.data.swap == 0.0
+    assert trade.data.magic == 0 and trade.data.degraded is False
+
+
+def test_parse_trade_degraded_frame() -> None:
+    """A degraded frame: identifiers/direction real, costs zeroed, entry Unknown."""
+    trade = parse_event(
+        {
+            "type": "trade",
+            "data": {
+                "deal": 9,
+                "order": 10,
+                "position": 10,
+                "symbol": "EURUSD",
+                "type": "Buy",
+                "entry": "Unknown",
+                "volume": 0.1,
+                "price": 1.0,
+                "profit": 0.0,
+                "commission": 0.0,
+                "swap": 0.0,
+                "magic": 0,
+                "comment": "",
+                "time": "2026-08-19T18:53:41.000Z",
+                "degraded": True,
+            },
+        }
+    )
+    assert isinstance(trade, TradeUpdate)
+    assert trade.data.degraded is True
+    assert trade.data.entry == DealEntry.UNKNOWN
+    assert trade.data.symbol == "EURUSD" and trade.data.position == 10
+
+
 # --------------------------------------------------------------------------- #
 # Validation (no connection needed — raised before send)
 # --------------------------------------------------------------------------- #

{fxsocket-0.4.0 → fxsocket-0.5.0}/tests/test_terminal.py

@@ -693,6 +693,54 @@ def test_server_timezone_parses() -> None:
     assert isinstance(tz.server_time, str)
 
 
+@respx.mock
+def test_order_history_parses_position() -> None:
+    # Second row mimics a pod older than bridge MT5 0.14 / MT4 0.13 (no
+    # ``position`` yet) — must default to 0, not fail validation.
+    respx.get(f"{TERM}/OrderHistory").mock(
+        return_value=httpx.Response(
+            200,
+            json=[
+                {
+                    "ticket": 14541780,
+                    "order": 13173527,
+                    "position": 13173524,
+                    "symbol": "EURUSD",
+                    "type": "Sell",
+                    "entry": "Out",
+                    "volume": 0.01,
+                    "price": 1.16635,
+                    "profit": -0.02,
+                    "commission": -0.04,
+                    "swap": 0.0,
+                    "magic": 0,
+                    "comment": "",
+                    "time": "2026-08-19T18:53:47.000Z",
+                },
+                {
+                    "ticket": 14541777,
+                    "order": 13173524,
+                    "symbol": "EURUSD",
+                    "type": "Buy",
+                    "entry": "In",
+                    "volume": 0.01,
+                    "price": 1.16637,
+                    "profit": 0.0,
+                    "commission": -0.04,
+                    "swap": 0.0,
+                    "magic": 1000999,
+                    "comment": "CN_9999_8888",
+                    "time": "2026-08-19T18:53:41.000Z",
+                },
+            ],
+        )
+    )
+    with _term() as t:
+        rows = t.order_history()
+    assert rows[0].position == 13173524
+    assert rows[1].position == 0
+
+
 @respx.mock
 def test_position_history_sends_dates_and_parses() -> None:
     route = respx.get(f"{TERM}/PositionHistory").mock(

fxsocket-0.4.0/src/fxsocket/_version.py

@@ -1 +0,0 @@
-__version__ = "0.4.0"