fix: flatten raw exchange fill envelopes

Author: yunjinqi

backtrader/brokers/btapibroker.py

@@ -2399,17 +2399,47 @@ def _drain_store_updates(self):
             return
 
         while True:
-            update = self.store.poll_broker_update()
-            if update is None:
+            raw_update = self.store.poll_broker_update()
+            if raw_update is None:
                 break
 
-            kind = str(update.get("kind") or "").lower()
-            if kind == "order":
-                self._apply_order_update(update)
-            elif kind == "trade":
-                self._apply_trade_update(update)
-            elif kind == "error":
-                self._apply_error_update(update)
+            for update in self._iter_broker_update_rows(raw_update):
+                kind = str(update.get("kind") or "").lower()
+                if kind == "order":
+                    self._apply_order_update(update)
+                elif kind == "trade":
+                    self._apply_trade_update(update)
+                elif kind == "error":
+                    self._apply_error_update(update)
+
+    @classmethod
+    def _iter_broker_update_rows(cls, update):
+        """Yield flat broker updates from exchange envelopes such as WS data lists."""
+        if not isinstance(update, dict):
+            return
+
+        data = update.get("data")
+        if isinstance(data, dict):
+            rows = [data]
+        elif isinstance(data, (list, tuple)):
+            rows = [item for item in data if isinstance(item, dict)]
+        else:
+            yield update
+            return
+
+        if not rows:
+            yield update
+            return
+
+        envelope = {key: value for key, value in update.items() if key not in {"data", "id"}}
+        if update.get("id") not in (None, ""):
+            envelope["message_id"] = update.get("id")
+        for row in rows:
+            flat = dict(envelope)
+            flat.update(row)
+            if "kind" not in flat and update.get("kind") not in (None, ""):
+                flat["kind"] = update.get("kind")
+            yield flat
 
     def _trade_dedupe_key(self, update, order=None):
         """Build a stable trade dedupe key when the provider exposes a fill id."""

tests/unit/brokers/test_btapibroker.py

@@ -3566,6 +3566,63 @@ def test_remote_trade_update_accepts_raw_okx_trade_aliases_and_fee():
         broker.stop()
 
 
+def test_remote_trade_update_accepts_raw_okx_orders_envelope_rows():
+    """Raw OKX private-channel envelopes must be flattened before fill booking."""
+    symbol = "BTC-USDT-SWAP"
+    client = FakeBtApiClient(
+        history={symbol: [make_bar(0, 100.0, 101.0, 99.0, 100.5)]},
+    )
+    store = make_store(api=client, provider="okx")
+    data = store.getdata(dataname=symbol)
+    broker = store.getbroker(account_refresh_interval=60.0, positions_refresh_interval=60.0)
+
+    data._start()
+    assert data.load() is True
+    broker.start()
+    broker.setcommission(
+        commission=10.0,
+        commtype=bt.CommInfoBase.COMM_FIXED,
+    )
+    try:
+        order = broker.buy(
+            owner=None,
+            data=data,
+            size=1,
+            price=101.0,
+            exectype=bt.Order.Limit,
+        )
+
+        client.push_broker_update(
+            {
+                "kind": "trade",
+                "arg": {"channel": "orders"},
+                "id": "okx-message-1",
+                "data": [
+                    {
+                        "ordId": "btapi-1",
+                        "tradeId": "okx-trade-1",
+                        "instId": symbol,
+                        "side": "buy",
+                        "fillSz": "1",
+                        "fillPx": "101.5",
+                        "fee": "-0.25",
+                        "feeCcy": "USDT",
+                    }
+                ],
+            }
+        )
+
+        broker.next()
+
+        assert order.status == bt.Order.Completed
+        assert order.executed.size == pytest.approx(1.0)
+        assert order.executed.price == pytest.approx(101.5)
+        assert order.executed.comm == pytest.approx(0.25)
+        assert broker.positions[symbol].size == pytest.approx(1.0)
+    finally:
+        broker.stop()
+
+
 def test_remote_trade_update_accepts_raw_bybit_v5_execution_aliases_and_fee():
     """Raw Bybit V5 execution events must use exchange fill fields and exact fees."""
     symbol = "BTCUSDT"
@@ -3667,6 +3724,69 @@ def test_remote_trade_update_accepts_raw_bybit_v5_execution_aliases_and_fee():
         broker.stop()
 
 
+def test_remote_trade_update_accepts_raw_bybit_v5_execution_envelope_rows():
+    """Raw Bybit V5 execution envelopes must be flattened and booked as fills."""
+    symbol = "BTCUSDT"
+    client = FakeBtApiClient(
+        history={symbol: [make_bar(0, 100.0, 101.0, 99.0, 100.5)]},
+    )
+    store = make_store(api=client, provider="bybit")
+    data = store.getdata(dataname=symbol)
+    broker = store.getbroker(account_refresh_interval=60.0, positions_refresh_interval=60.0)
+
+    data._start()
+    assert data.load() is True
+    broker.start()
+    broker.setcommission(
+        commission=10.0,
+        commtype=bt.CommInfoBase.COMM_FIXED,
+    )
+    try:
+        order = broker.buy(
+            owner=None,
+            data=data,
+            size=1,
+            price=101.0,
+            exectype=bt.Order.Limit,
+        )
+
+        client.push_broker_update(
+            {
+                "kind": "trade",
+                "topic": "execution",
+                "id": "bybit-message-1",
+                "creationTime": 1746270400355,
+                "data": [
+                    {
+                        "category": "linear",
+                        "symbol": symbol,
+                        "orderId": "btapi-1",
+                        "orderLinkId": "btapi-1",
+                        "side": "Buy",
+                        "execQty": "1",
+                        "execPrice": "101.5",
+                        "execFee": "0.15",
+                        "execId": "bybit-exec-1",
+                        "execTime": "1746270400353",
+                        "feeCurrency": "USDT",
+                        "isMaker": False,
+                    }
+                ],
+            }
+        )
+
+        broker.next()
+
+        assert order.status == bt.Order.Completed
+        assert order.executed.size == pytest.approx(1.0)
+        assert order.executed.price == pytest.approx(101.5)
+        assert order.executed.comm == pytest.approx(0.15)
+        assert broker.positions[symbol].size == pytest.approx(1.0)
+        assert broker.positions[symbol].price == pytest.approx(101.5)
+    finally:
+        broker.stop()
+
+
 def test_remote_trade_update_without_price_is_ignored_not_zero_filled():
     """Malformed fills must not execute locally at price zero."""
     client = FakeBtApiClient(