feat: Initialize Portfolio with Existing Positions and Enhance Data Fetching Reliability

This pull request introduces two major enhancements to the portfolio initialization process:
1. Initial Position Loading: The system now correctly loads and integrates any existing open positions into the PortfolioView at startup.
2. Robust Data Fetching: A retry mechanism has been implemented for fetching portfolio data to improve reliability against transient network or API errors.

Author: lukecold

frontend/src/app/agent/components/strategy-items/forms/trading-strategy-form.tsx

@@ -25,7 +25,7 @@ export const TradingStrategyForm = withForm({
   defaultValues: {
     strategy_type: "" as Strategy["strategy_type"],
     strategy_name: "",
-    initial_capital: 1000,
+    initial_capital_input: 1000,
     max_leverage: 2,
     decide_interval: 60,
     symbols: TRADING_SYMBOLS,
@@ -73,7 +73,7 @@ export const TradingStrategyForm = withForm({
 
         <FieldGroup className="flex flex-row gap-4">
           {tradingMode === "virtual" && (
-            <form.AppField name="initial_capital">
+            <form.AppField name="initial_capital_input">
               {(field) => (
                 <field.NumberField
                   className="flex-1"

frontend/src/app/agent/components/strategy-items/modals/create-strategy-modal.tsx

@@ -93,7 +93,9 @@ const step2Schema = z.union([
 const step3Schema = z.object({
   strategy_type: z.enum(["PromptBasedStrategy", "GridStrategy"]),
   strategy_name: z.string().min(1, "Strategy name is required"),
-  initial_capital: z.number().min(1, "Initial capital must be at least 1"),
+  initial_capital_input: z
+    .number()
+    .min(1, "Initial capital must be at least 1"),
   max_leverage: z
     .number()
     .min(1, "Leverage must be at least 1")
@@ -265,7 +267,7 @@ const CreateStrategyModal: FC<CreateStrategyModalProps> = ({ children }) => {
     defaultValues: {
       strategy_type: "PromptBasedStrategy" as Strategy["strategy_type"],
       strategy_name: "",
-      initial_capital: 1000,
+      initial_capital_input: 1000,
       max_leverage: 2,
       decide_interval: 60,
       symbols: TRADING_SYMBOLS,
@@ -275,10 +277,16 @@ const CreateStrategyModal: FC<CreateStrategyModalProps> = ({ children }) => {
       onSubmit: step3Schema,
     },
     onSubmit: async ({ value }) => {
+      const { initial_capital_input, ...restOfTradingConfig } = value;
+      const trading_config = {
+        ...restOfTradingConfig,
+        initial_free_cash: initial_capital_input,
+        initial_total_cash: initial_capital_input,
+      };
       const payload = {
         llm_model_config: form1.state.values,
         exchange_config: form2.state.values,
-        trading_config: value,
+        trading_config: trading_config,
       };
 
       await createStrategy(payload);

frontend/src/app/rank/board.tsx

@@ -208,7 +208,7 @@ export default function RankBoard() {
                   <span>{strategyDetail.llm_model_id}</span>
 
                   <p>Initial Capital</p>
-                  <span>{strategyDetail.initial_capital}</span>
+                  <span>{strategyDetail.initial_total_cash}</span>
 
                   <p>Max Leverage</p>
                   <span>{strategyDetail.max_leverage}x</span>

frontend/src/types/strategy.ts

@@ -17,7 +17,7 @@ export interface Strategy {
 // Strategy Performance types
 export type StrategyPerformance = {
   strategy_id: string;
-  initial_capital: number;
+  initial_total_cash: number;
   return_rate_pct: number;
   llm_provider: string;
   llm_model_id: string;
@@ -96,7 +96,8 @@ export interface CreateStrategyRequest {
   // Trading Strategy Configuration
   trading_config: {
     strategy_name: string;
-    initial_capital: number;
+    initial_free_cash: number;
+    initial_total_cash: number;
     max_leverage: number;
     symbols: string[]; // e.g. ['BTC', 'ETH', ...]
     template_id: string;

frontend/src/types/system.ts

@@ -34,7 +34,7 @@ export interface StrategyDetail {
   llm_provider: string;
   llm_model_id: string;
   max_leverage: number;
-  initial_capital: number;
+  initial_total_cash: number;
   prompt: string;
 }
 
@@ -48,6 +48,6 @@ export interface StrategyReport {
   llm_provider: string;
   llm_model_id: string;
   max_leverage: number;
-  initial_capital: number;
+  initial_total_cash: number;
   prompt: string;
 }

python/valuecell/agents/common/trading/README.md

@@ -120,7 +120,8 @@ UserRequest
 TradingConfig
 
 - `strategy_name?: str` — Display name
-- `initial_capital: float` — Starting capital (USD)
+- `initial_free_cash: float` — Starting free cash in USD
+- `initial_total_cash: float` — Starting total cash in USD (same as initial_free_cash without initial positions)
 - `max_leverage: float` — Maximum leverage allowed
 - `max_positions: int` — Concurrent position limit
 - `symbols: List[str]` — Instruments to trade (e.g., `["BTC-USDT", "ETH-USDT"]`)
@@ -459,7 +460,8 @@ For live trading with real exchanges:
 **The runtime automatically:**
 
 - Fetches real account balance
-- Sets `initial_capital` to available cash
+- Sets `initial_free_cash` to available cash
+- Sets `initial_total_cash` to account total cash
 - Uses `CCXTExecutionGateway` for order submission
 
 **Always test on testnet first** before using real funds

python/valuecell/agents/common/trading/_internal/coordinator.py

@@ -466,16 +466,17 @@ def build_summary(
             # Fallback to internal tracking if portfolio service is unavailable
             unrealized = float(self._unrealized_pnl or 0.0)
             # Fallback equity uses initial capital when view is unavailable
-            equity = float(self._request.trading_config.initial_capital or 0.0)
+            equity = float(
+                (self._request.trading_config.initial_total_cash + unrealized)
+                if self._request.trading_config.initial_total_cash is not None
+                else 0.0
+            )
 
         # Keep internal state in sync (allow negative unrealized PnL)
         self._unrealized_pnl = float(unrealized)
 
-        initial_capital = self._request.trading_config.initial_capital or 0.0
         pnl_pct = (
-            (self._realized_pnl + self._unrealized_pnl) / initial_capital
-            if initial_capital
-            else None
+            (self._realized_pnl + self._unrealized_pnl) / equity if equity else None
         )
 
         # Strategy-level unrealized percent: percent of equity (if equity is available)

python/valuecell/agents/common/trading/_internal/runtime.py

@@ -17,7 +17,7 @@
 )
 from ..models import Constraints, DecisionCycleResult, TradingMode, UserRequest
 from ..portfolio.in_memory import InMemoryPortfolioService
-from ..utils import fetch_free_cash_from_gateway
+from ..utils import fetch_free_cash_from_gateway, fetch_positions_from_gateway
 from .coordinator import DefaultDecisionCoordinator
 
 
@@ -28,22 +28,26 @@ async def _create_execution_gateway(request: UserRequest) -> BaseExecutionGatewa
     # In LIVE mode, fetch exchange balance and set initial capital from free cash
     try:
         if request.exchange_config.trading_mode == TradingMode.LIVE:
-            free_cash, _ = await fetch_free_cash_from_gateway(
+            free_cash, total_cash = await fetch_free_cash_from_gateway(
                 execution_gateway, request.trading_config.symbols
             )
-            request.trading_config.initial_capital = float(free_cash)
+            request.trading_config.initial_free_cash = float(free_cash)
+            request.trading_config.initial_total_cash = float(total_cash)
+            request.trading_config.initial_positions = (
+                await fetch_positions_from_gateway(execution_gateway)
+            )
     except Exception:
-        # Log the error but continue - user might have set initial_capital manually
+        # Log the error but continue - user might have set initial portfolio manually
         logger.exception(
-            "Failed to fetch exchange balance for LIVE mode. Will use configured initial_capital instead."
+            "Failed to fetch exchange balance for LIVE mode. Will use configured initial portfolio instead."
         )
 
     # Validate initial capital for LIVE mode
     if request.exchange_config.trading_mode == TradingMode.LIVE:
-        initial_cap = request.trading_config.initial_capital or 0.0
-        if initial_cap <= 0:
+        initial_total_cash = request.trading_config.initial_total_cash or 0.0
+        if initial_total_cash <= 0:
             logger.error(
-                f"LIVE trading mode has initial_capital={initial_cap}. "
+                f"LIVE trading mode has initial_total_cash={initial_total_cash}. "
                 "This usually means balance fetch failed or account has no funds. "
                 "Strategy will not be able to trade without capital."
             )
@@ -99,7 +103,8 @@ async def create_strategy_runtime(
         ...     ),
         ...     trading_config=TradingConfig(
         ...         symbols=['BTC-USDT', 'ETH-USDT'],
-        ...         initial_capital=10000.0,
+        ...         initial_free_cash=10000.0,
+        ...         initial_total_cash=10000.0,
         ...         max_leverage=10.0,
         ...         max_positions=5,
         ...     )
@@ -112,36 +117,45 @@ async def create_strategy_runtime(
     # Create strategy runtime components
     strategy_id = strategy_id_override or generate_uuid("strategy")
 
-    # If an initial capital override wasn't provided, and this is a resume
-    # of an existing strategy, attempt to initialize from the persisted
-    # portfolio snapshot so the in-memory portfolio starts with the
-    # previously recorded equity.
-    initial_capital_override = None
+    # If this is a resume of an existing strategy,
+    # attempt to initialize from the persisted portfolio snapshot
+    # so the in-memory portfolio starts with the previously recorded equity.
+    free_cash_override = None
+    total_cash_override = None
     if strategy_id_override:
         try:
             repo = get_strategy_repository()
             snap = repo.get_latest_portfolio_snapshot(strategy_id_override)
             if snap is not None:
-                initial_capital_override = float(snap.total_value or snap.cash or 0.0)
+                free_cash_override = float(snap.cash or 0.0)
+                total_cash_override = float(
+                    snap.total_value - snap.total_unrealized_pnl
+                    if (
+                        snap.total_value is not None
+                        and snap.total_unrealized_pnl is not None
+                    )
+                    else 0.0
+                )
                 logger.info(
-                    "Initialized runtime initial_capital from persisted snapshot for strategy_id=%s",
+                    "Initialized runtime initial capital from persisted snapshot for strategy_id=%s",
                     strategy_id_override,
                 )
         except Exception:
             logger.exception(
-                "Failed to initialize initial_capital from persisted snapshot for strategy_id=%s",
+                "Failed to initialize initial capital from persisted snapshot for strategy_id=%s",
                 strategy_id_override,
             )
 
-    initial_capital = (
-        initial_capital_override or request.trading_config.initial_capital or 0.0
-    )
+    free_cash = free_cash_override or request.trading_config.initial_free_cash or 0.0
+    total_cash = total_cash_override or request.trading_config.initial_total_cash or 0.0
     constraints = Constraints(
         max_positions=request.trading_config.max_positions,
         max_leverage=request.trading_config.max_leverage,
     )
     portfolio_service = InMemoryPortfolioService(
-        initial_capital=initial_capital,
+        free_cash=free_cash,
+        total_cash=total_cash,
+        initial_positions=request.trading_config.initial_positions,
         trading_mode=request.exchange_config.trading_mode,
         market_type=request.exchange_config.market_type,
         constraints=constraints,

python/valuecell/agents/common/trading/_internal/stream_controller.py

@@ -123,7 +123,7 @@ def persist_initial_state(self, runtime: StrategyRuntime) -> None:
                     self.strategy_id,
                 )
 
-            # When running in LIVE mode, update DB config.initial_capital to exchange available balance
+            # When running in LIVE mode, update DB config.initial_free_cash to exchange available balance
             # and record initial capital into strategy metadata for fast access by APIs.
             # Only perform this on the first snapshot to avoid overwriting user edits or restarts.
             try:
@@ -132,51 +132,54 @@ def persist_initial_state(self, runtime: StrategyRuntime) -> None:
                 )
                 is_live = trading_mode == agent_models.TradingMode.LIVE
                 if is_live and is_first_snapshot:
-                    initial_cash = getattr(initial_portfolio, "free_cash", None)
-                    if initial_cash is None:
-                        initial_cash = getattr(
-                            initial_portfolio, "account_balance", None
-                        )
-                    if initial_cash is None:
-                        initial_cash = getattr(
-                            runtime.request.trading_config, "initial_capital", None
+                    initial_free_cash = (
+                        initial_portfolio.free_cash
+                        or initial_portfolio.account_balance
+                        or runtime.request.trading_config.initial_free_cash
+                    )
+                    initial_total_cash = (
+                        initial_portfolio.total_value
+                        - initial_portfolio.total_unrealized_pnl
+                        if (
+                            initial_portfolio.total_value is not None
+                            and initial_portfolio.total_unrealized_pnl is not None
                         )
-
-                    if initial_cash is not None:
+                        else runtime.request.trading_config.initial_free_cash
+                    )
+                    if initial_free_cash is not None:
                         if strategy_persistence.update_initial_capital(
-                            self.strategy_id, float(initial_cash)
+                            self.strategy_id,
+                            float(initial_free_cash),
+                            float(initial_total_cash),
                         ):
-                            logger.info(
-                                "Updated DB initial_capital to {} for strategy={} (LIVE mode)",
-                                initial_cash,
-                                self.strategy_id,
-                            )
                             try:
                                 # Also persist metadata for initial capital to avoid repeated first-snapshot queries
                                 strategy_persistence.set_initial_capital_metadata(
                                     strategy_id=self.strategy_id,
-                                    initial_capital=float(initial_cash),
+                                    initial_free_cash=float(initial_free_cash),
+                                    initial_total_cash=float(initial_total_cash),
                                     source="live_snapshot_cash",
                                     ts_ms=timestamp_ms,
                                 )
                                 logger.info(
-                                    "Recorded initial_capital_live={} (source=live_snapshot_cash) in metadata for strategy={}",
-                                    initial_cash,
+                                    "Recorded initial_free_cash={} initial_total_cash={} (source=live_snapshot_cash) in metadata for strategy={}",
+                                    initial_free_cash,
+                                    initial_total_cash,
                                     self.strategy_id,
                                 )
                             except Exception:
                                 logger.exception(
-                                    "Failed to set initial_capital metadata for {}",
+                                    "Failed to set initial capital metadata for {}",
                                     self.strategy_id,
                                 )
                         else:
                             logger.warning(
-                                "Failed to update DB initial_capital for strategy={} (LIVE mode)",
+                                "Failed to update DB initial capital for strategy={} (LIVE mode)",
                                 self.strategy_id,
                             )
             except Exception:
                 logger.exception(
-                    "Error while updating DB initial_capital from live balance for {}",
+                    "Error while updating DB initial capital from live balance for {}",
                     self.strategy_id,
                 )
         except Exception:

python/valuecell/agents/common/trading/models.py

@@ -208,11 +208,20 @@ class TradingConfig(BaseModel):
         default=None,
         description="Reuse existing strategy id to continue execution (resume semantics without extra flags)",
     )
-    initial_capital: Optional[float] = Field(
+    initial_free_cash: Optional[float] = Field(
         default=DEFAULT_INITIAL_CAPITAL,
-        description="Initial capital for trading in USD",
+        description="Initial free cash for trading in USD",
         gt=0,
     )
+    initial_total_cash: Optional[float] = Field(
+        default=DEFAULT_INITIAL_CAPITAL,
+        description="Initial total cash for trading in USD",
+        gt=0,
+    )
+    initial_positions: Dict[str, "PositionSnapshot"] = Field(
+        default={},
+        description="Initial positions in portfolio",
+    )
     max_leverage: float = Field(
         default=DEFAULT_MAX_LEVERAGE,
         description="Maximum leverage",