Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(futu): carry average-cost basis and P&L split with positions

alex6d76d99cf423
diff --git a/agent/src/trading/connectors/futu/sdk.py b/agent/src/trading/connectors/futu/sdk.py
index 4a0b5f053..01cdc8d62 100644
--- a/agent/src/trading/connectors/futu/sdk.py
+++ b/agent/src/trading/connectors/futu/sdk.py
@@ -1241,15 +1241,53 @@ def _account_to_dict(
}
+def _reported(row: Mapping[str, Any], name: str) -> Any:
+ """Return a position field, or ``None`` where Futu did not report it.
+
+ Futu fills an unreported field with the string ``"N/A"``. Downstream that
+ string reads as present, and a numeric reader turns it into zero, so an
+ unreported P&L would show as a flat position.
+
+ Args:
+ row: One row from ``position_list_query``.
+ name: The field to read.
+
+ Returns:
+ The reported value, or ``None``.
+ """
+ value = _first(row, (name,))
+ return None if value == _NO_DATA else value
+
+
def _position_to_dict(row: Mapping[str, Any]) -> dict[str, Any]:
+ """Normalize one ``position_list_query`` row.
+
+ Futu reports a position on two cost bases. ``cost_price`` is the diluted
+ cost, with realized gains subtracted, so after round-trip trading it can
+ turn negative and ``pl_ratio`` on that basis stops describing the
+ position. ``average_cost`` and ``pl_ratio_avg_cost`` are the same position
+ on its average purchase cost. ``pl_val`` adds realized and unrealized
+ P&L, so ``unrealized_pl`` and ``realized_pl`` ship alongside it to keep a
+ realized gain from hiding an unrealized loss.
+
+ Args:
+ row: One row from ``position_list_query``.
+
+ Returns:
+ The normalized position mapping.
+ """
return {
"code": _first(row, ("code",)),
"qty": _first(row, ("qty",)),
"can_sell_qty": _first(row, ("can_sell_qty",)),
"cost_price": _first(row, ("cost_price",)),
+ "average_cost": _reported(row, "average_cost"),
"market_val": _first(row, ("market_val",)),
"pl_ratio": _first(row, ("pl_ratio",)),
+ "pl_ratio_avg_cost": _reported(row, "pl_ratio_avg_cost"),
"pl_val": _first(row, ("pl_val",)),
+ "unrealized_pl": _reported(row, "unrealized_pl"),
+ "realized_pl": _reported(row, "realized_pl"),
"position_side": str(_first(row, ("position_side",), "")),
"market": str(_first(row, ("position_market",), "") or "").upper(),
"currency": str(_first(row, ("currency",), "") or "").upper(),
diff --git a/agent/tests/test_futu_position_cost_bases.py b/agent/tests/test_futu_position_cost_bases.py
new file mode 100644
index 000000000..6aef21f8f
--- /dev/null
+++ b/agent/tests/test_futu_position_cost_bases.py
@@ -0,0 +1,139 @@
+"""Futu position rows carry both cost bases and the split of their P&L.
+
+The fields come from ``PositionListQuery.unpack_rsp`` in the SDK module
+``futu/trade/trade_query.py``: ``average_cost`` (``averageCostPrice``),
+``pl_ratio_avg_cost`` (``averagePlRatio``), ``unrealized_pl``
+(``unrealizedPL``) and ``realized_pl`` (``realizedPL``). That module fills a
+field the response does not carry with ``NoneDataValue``, the string
+``"N/A"``, rather than omitting the key.
+
+All rows are synthetic: invented symbols and values in the shape the SDK
+returns.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+from src.portfolio.fx import build_rates
+from src.portfolio.normalization import normalize_position, value_position
+from src.trading.connectors.futu import sdk as futu_sdk
+
+pytestmark = pytest.mark.unit
+
+#: Synthetic rates: 8 HKD and 7 CNY per USD.
+RATES = build_rates(usd_cny=Decimal("7"), usd_hkd=Decimal("8"))
+
+NEW_KEYS = ("average_cost", "pl_ratio_avg_cost", "unrealized_pl", "realized_pl")
+
+_BASE = {"position_side": "LONG", "position_market": "HK", "currency": "HKD"}
+
+# Realized gains have pushed the diluted cost below zero, so the ratio on that
+# basis is filled with 0.0 while the average-cost pair still reads normally.
+DILUTED_COST_WENT_NEGATIVE = {
+ **_BASE,
+ "code": "HK.SYNTHA",
+ "qty": 300.0,
+ "can_sell_qty": 300.0,
+ "cost_price": -1.50,
+ "average_cost": 20.00,
+ "market_val": 6600.0,
+ "pl_ratio": 0.0,
+ "pl_ratio_avg_cost": 10.00,
+ "pl_val": 7050.0,
+ "unrealized_pl": 600.0,
+ "realized_pl": 6450.0,
+}
+
+# A large unrealized loss offset by an earlier realized gain.
+PL_VAL_MIXES_REALIZED = {
+ **_BASE,
+ "code": "HK.SYNTHB",
+ "qty": 2000.0,
+ "can_sell_qty": 2000.0,
+ "cost_price": 9.30,
+ "average_cost": 12.00,
+ "market_val": 18000.0,
+ "pl_ratio": -3.23,
+ "pl_ratio_avg_cost": -25.00,
+ "pl_val": -600.0,
+ "unrealized_pl": -6000.0,
+ "realized_pl": 5400.0,
+}
+
+# The SDK reports none of the four fields for this row.
+NEW_FIELDS_UNREPORTED = {
+ **_BASE,
+ "code": "HK.SYNTHC",
+ "qty": 100.0,
+ "can_sell_qty": 100.0,
+ "cost_price": 10.00,
+ "market_val": 800.0,
+ "pl_ratio": -20.00,
+ "pl_val": -200.0,
+ **{key: "N/A" for key in NEW_KEYS},
+}
+
+
+def test_both_cost_bases_are_carried() -> None:
+ """Without ``average_cost`` a negative ``cost_price`` reads as a bad value."""
+ row = futu_sdk._position_to_dict(DILUTED_COST_WENT_NEGATIVE)
+
+ assert row["cost_price"] == -1.50
+ assert row["average_cost"] == 20.00
+
+
+def test_both_pl_ratios_are_carried() -> None:
+ """``pl_ratio`` 0.0 here means "cannot be computed", not "flat"."""
+ row = futu_sdk._position_to_dict(DILUTED_COST_WENT_NEGATIVE)
+
+ assert row["pl_ratio"] == 0.0
+ assert row["pl_ratio_avg_cost"] == 10.00
+
+
+def test_pl_val_is_carried_with_its_realized_and_unrealized_parts() -> None:
+ row = futu_sdk._position_to_dict(PL_VAL_MIXES_REALIZED)
+
+ assert row["pl_val"] == -600.0
+ assert row["unrealized_pl"] == -6000.0
+ assert row["realized_pl"] == 5400.0
+
+
+def test_original_keys_are_kept() -> None:
+ row = futu_sdk._position_to_dict(DILUTED_COST_WENT_NEGATIVE)
+
+ assert row["code"] == "HK.SYNTHA"
+ assert row["qty"] == 300.0
+ assert row["can_sell_qty"] == 300.0
+ assert row["market_val"] == 6600.0
+ assert row["pl_val"] == 7050.0
+ assert row["position_side"] == "LONG"
+ assert row["market"] == "HK"
+ assert row["currency"] == "HKD"
+
+
+def test_unreported_new_fields_become_none() -> None:
+ row = futu_sdk._position_to_dict(NEW_FIELDS_UNREPORTED)
+
+ for key in NEW_KEYS:
+ assert row[key] is None
+
+
+def test_reported_unrealized_pl_is_the_valued_pnl() -> None:
+ """Portfolio valuation reads the broker's unrealized P&L when it is present."""
+ row = normalize_position("futu", futu_sdk._position_to_dict(PL_VAL_MIXES_REALIZED))
+
+ valued = value_position(row, rates=RATES)
+
+ assert valued["unrealized_pnl_usd"] == pytest.approx(-750.0)
+
+
+def test_unreported_unrealized_pl_is_not_valued_as_zero() -> None:
+ """An unreported P&L falls back to price against cost instead of a flat 0."""
+ row = normalize_position("futu", futu_sdk._position_to_dict(NEW_FIELDS_UNREPORTED))
+
+ valued = value_position(row, rates=RATES)
+
+ assert valued["unrealized_pnl_usd"] == pytest.approx(-25.0)