fix: IBKR portfolio data (#324)

Loading the portfolio data from IBKR sometimes produced incomplete information.

This fix guarantees the data is properly loaded, which mainly fixes data about ETFs and countries.

Author: ctasada

CHANGELOG.md

@@ -22,7 +22,9 @@ _This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) a
   - Fixed error aggregating numeric types
   - Fixed error sorting dates
 - DEGIRO: Prevent authenticated users from being redirected to 2FA login screen
-- IBKR: Handle incomplete IBKR API contract data with defensive fallbacks
+- IBKR:
+  - Handle incomplete IBKR API contract data with defensive fallbacks
+  - Fixed portfolio API import. Improves identification of ETFs
 
 ### Security
 

docs/IBKR.md

@@ -439,18 +439,16 @@ The database model is defined in:
 - **Fee Information**: Limited fee data available
 - **Historical Data**: Depends on your account data subscription
 
-#### Incomplete Position Contract Data
+#### Position Contract Data — Gateway Cache
 
-The IBKR Web API `/portfolio` endpoints frequently return incomplete contract details. Fields like `ticker`, `name`, `sector`, `listingExchange`, and `countryCode` are often `None`.
+The IBKR Client Portal Gateway caches position data server-side. On a cold session (fresh gateway start), contract detail fields like `ticker`, `name`, `sector`, `type`, `listingExchange`, and `countryCode` may be missing from the first response of the `GET /portfolio/{accountId}/positions/{pageId}` endpoint.
 
-**Workaround**: Stonks Overwatch uses `contractDesc` (which contains the ticker) as a fallback when these fields are missing.
+**Workaround**: Stonks Overwatch calls the positions endpoint twice — the first call primes the gateway cache with full contract details, and the second call returns the fully populated data. Defensive fallbacks are also in place for any fields that remain `None` (e.g., ETFs with no sector classification).
 
 **Impact**:
-- ✅ Portfolio displays correctly with ticker symbols
+- ✅ Portfolio displays correctly with ticker symbols, sector, and asset type
 - ✅ Position values and P&L calculations work properly
-- ⚠️ Sector/geographic diversification may show generic values ("Unknown", "US")
-
-These are IBKR API limitations, not application limitations. The application handles them gracefully with defensive fallback logic.
+- ⚠️ ETFs may still show `null` for `sector`/`group` as IBKR does not classify them
 
 ---
 

src/stonks_overwatch/services/brokers/ibkr/client/ibkr_service.py

@@ -119,6 +119,8 @@ def get_account_summary(self) -> dict:
 
     def get_open_positions(self) -> list[dict]:
         self.logger.debug("Open Positions")
+        # First call primes the gateway cache with full contract details (sector, type, etc.)
+        self.client.positions(self.account.account_id)
         return self.client.positions(self.account.account_id).data
 
     def transaction_history(self, conid: str, currency: str) -> dict:

src/stonks_overwatch/services/brokers/ibkr/services/portfolio.py

@@ -100,8 +100,9 @@ def __create_portfolio_entry(self, position: dict, base_currency: str) -> Portfo
         """
         Create a portfolio entry from IBKR position data.
 
-        Note: IBKR API often returns None for ticker, name, sector, etc.
-        Uses contractDesc as fallback. See docs/IBKR.md for details.
+        Note: Some fields (sector, group) are genuinely None for ETFs.
+        Others (ticker, name, type, etc.) are populated after the gateway cache warms up.
+        Defensive fallbacks handle both cases. See docs/IBKR.md for details.
 
         Args:
             position: Position data from IBKR (may contain None values)
@@ -129,7 +130,7 @@ def __create_portfolio_entry(self, position: dict, base_currency: str) -> Portfo
 
         is_open = position["position"] > 0
 
-        # Defensive handling: IBKR API limitation - use contractDesc as fallback
+        # Defensive handling: ETFs have null sector/group; use contractDesc as ticker fallback
         ticker = position.get("ticker") or position.get("contractDesc") or "UNKNOWN"
         name = position.get("name") or position.get("contractDesc") or ticker
         sector_str = position.get("sector") or "Unknown"

src/stonks_overwatch/services/brokers/ibkr/services/update_service.py

@@ -126,9 +126,9 @@ def __import_open_positions(self, open_positions: list[dict]) -> None:
         """
         Store open positions into the DB.
 
-        Note: IBKR API often returns None for ticker, name, sector, etc.
+        Note: ETFs have null sector/group from the IBKR API.
         Portfolio service handles this with defensive fallbacks.
-        See docs/IBKR.md (Known API Limitations) for details.
+        See docs/IBKR.md for details.
         """
         for row in open_positions:
             try: