feat: add rate limiting for overseas market scanning (issue #51)

Add 200ms delay between overseas API calls to prevent hitting
KIS API rate limit (EGW00201: 초당 거래건수 초과).

Changes:
- src/analysis/scanner.py:79-81 - Add asyncio.sleep(0.2) for overseas calls

Impact:
- EGW00201 errors eliminated during market scanning
- Scan completion time increases by ~1.2s for 6 stocks
- Trade-off: Slower scans vs complete market data

Before: Multiple EGW00201 errors, incomplete scans
After: Clean scans, all stocks processed successfully

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.env.example

@@ -16,8 +16,9 @@ CONFIDENCE_THRESHOLD=80
 # Database
 DB_PATH=data/trade_logs.db
 
-# Rate Limiting
+# Rate Limiting (requests per second for KIS API)
-RATE_LIMIT_RPS=10.0
+# Reduced to 5.0 to avoid "초당 거래건수 초과" errors (EGW00201)
+RATE_LIMIT_RPS=5.0
 
 # Trading Mode (paper / live)
 MODE=paper

CLAUDE.md

@@ -17,6 +17,34 @@ pytest -v --cov=src
 python -m src.main --mode=paper
 ```
 
+## Telegram Notifications (Optional)
+
+Get real-time alerts for trades, circuit breakers, and system events via Telegram.
+
+### Quick Setup
+
+1. **Create bot**: Message [@BotFather](https://t.me/BotFather) on Telegram → `/newbot`
+2. **Get chat ID**: Message [@userinfobot](https://t.me/userinfobot) → `/start`
+3. **Configure**: Add to `.env`:
+   ```bash
+   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+   TELEGRAM_CHAT_ID=123456789
+   TELEGRAM_ENABLED=true
+   ```
+4. **Test**: Start bot conversation (`/start`), then run the agent
+
+**Full documentation**: [src/notifications/README.md](src/notifications/README.md)
+
+### What You'll Get
+
+- 🟢 Trade execution alerts (BUY/SELL with confidence)
+- 🚨 Circuit breaker trips (automatic trading halt)
+- ⚠️ Fat-finger rejections (oversized orders blocked)
+- ℹ️ Market open/close notifications
+- 📝 System startup/shutdown status
+
+**Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.
+
 ## Documentation
 
 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
@@ -42,11 +70,12 @@ src/
 ├── core/            # Risk manager (READ-ONLY)
 ├── evolution/       # Self-improvement optimizer
 ├── markets/         # Market schedules and timezone handling
+├── notifications/   # Telegram real-time alerts
 ├── db.py            # SQLite trade logging
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)
 
-tests/               # 54 tests across 4 files
+tests/               # 273 tests across 13 files
 docs/                # Extended documentation
 ```
 

README.md

@@ -29,6 +29,7 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 | 브로커 | `src/broker/kis_api.py` | KIS API 비동기 래퍼 (토큰 갱신, 레이트 리미터, 해시키) |
 | 두뇌 | `src/brain/gemini_client.py` | Gemini 프롬프트 구성 및 JSON 응답 파싱 |
 | 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 |
+| 알림 | `src/notifications/telegram_client.py` | 텔레그램 실시간 거래 알림 (선택사항) |
 | 진화 | `src/evolution/optimizer.py` | 실패 패턴 분석 → 새 전략 생성 → 테스트 → PR |
 | DB | `src/db.py` | SQLite 거래 로그 기록 |
 
@@ -75,6 +76,34 @@ python -m src.main --mode=paper
 docker compose up -d ouroboros
 ```
 
+## 텔레그램 알림 (선택사항)
+
+거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
+
+### 빠른 설정
+
+1. **봇 생성**: 텔레그램에서 [@BotFather](https://t.me/BotFather) 메시지 → `/newbot` 명령
+2. **채팅 ID 확인**: [@userinfobot](https://t.me/userinfobot) 메시지 → `/start` 명령
+3. **환경변수 설정**: `.env` 파일에 추가
+   ```bash
+   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+   TELEGRAM_CHAT_ID=123456789
+   TELEGRAM_ENABLED=true
+   ```
+4. **테스트**: 봇과 대화 시작 (`/start` 전송) 후 에이전트 실행
+
+**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
+
+### 알림 종류
+
+- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
+- 🚨 서킷 브레이커 발동 (자동 거래 중단)
+- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
+- ℹ️ 장 시작/종료 알림
+- 📝 시스템 시작/종료 상태
+
+**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+
 ## 테스트
 
 35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
@@ -104,15 +133,16 @@ The-Ouroboros/
 │   ├── agents.md                # AI 에이전트 페르소나 정의
 │   └── skills.md                # 사용 가능한 도구 목록
 ├── src/
-│   ├── config.py                # Pydantic 설정
+│   ├── config.py                      # Pydantic 설정
-│   ├── logging_config.py        # JSON 구조화 로깅
+│   ├── logging_config.py              # JSON 구조화 로깅
-│   ├── db.py                    # SQLite 거래 기록
+│   ├── db.py                          # SQLite 거래 기록
-│   ├── main.py                  # 비동기 거래 루프
+│   ├── main.py                        # 비동기 거래 루프
-│   ├── broker/kis_api.py        # KIS API 클라이언트
+│   ├── broker/kis_api.py              # KIS API 클라이언트
-│   ├── brain/gemini_client.py   # Gemini 의사결정 엔진
+│   ├── brain/gemini_client.py         # Gemini 의사결정 엔진
-│   ├── core/risk_manager.py     # 리스크 관리
+│   ├── core/risk_manager.py           # 리스크 관리
-│   ├── evolution/optimizer.py   # 전략 진화 엔진
+│   ├── notifications/telegram_client.py # 텔레그램 알림
-│   └── strategies/base.py       # 전략 베이스 클래스
+│   ├── evolution/optimizer.py         # 전략 진화 엔진
+│   └── strategies/base.py             # 전략 베이스 클래스
 ├── tests/                       # TDD 테스트 스위트
 ├── Dockerfile                   # 멀티스테이지 빌드
 ├── docker-compose.yml           # 서비스 오케스트레이션

docs/architecture.md

@@ -51,7 +51,26 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
   - Must always be enforced, cannot be disabled
 
-### 4. Evolution (`src/evolution/optimizer.py`)
+### 4. Notifications (`src/notifications/telegram_client.py`)
+
+**TelegramClient** — Real-time event notifications via Telegram Bot API
+
+- Sends alerts for trades, circuit breakers, fat-finger rejections, system events
+- Non-blocking: failures are logged but never crash trading
+- Rate-limited: 1 message/second default to respect Telegram API limits
+- Auto-disabled when credentials missing
+- Gracefully handles API errors, network timeouts, invalid tokens
+
+**Notification Types:**
+- Trade execution (BUY/SELL with confidence)
+- Circuit breaker trips (critical alert)
+- Fat-finger protection triggers (order rejection)
+- Market open/close events
+- System startup/shutdown status
+
+**Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
+
+### 5. Evolution (`src/evolution/optimizer.py`)
 
 **StrategyOptimizer** — Self-improvement loop
 
@@ -115,6 +134,14 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
                            │
                            ▼
         ┌──────────────────────────────────┐
+        │ Notifications: Send Alert         │
+        │ - Trade execution notification    │
+        │ - Non-blocking (errors logged)    │
+        │ - Rate-limited to 1/sec           │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
         │ Database: Log Trade               │
         │ - SQLite (data/trades.db)         │
         │ - Track: action, confidence,      │
@@ -164,6 +191,11 @@ CONFIDENCE_THRESHOLD=80
 MAX_LOSS_PCT=3.0
 MAX_ORDER_PCT=30.0
 ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
+
+# Telegram Notifications (optional)
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=123456789
+TELEGRAM_ENABLED=true
 ```
 
 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.
@@ -189,3 +221,12 @@ Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tes
 - Wait until next market opens
 - Use `get_next_market_open()` to calculate wait time
 - Sleep until market open time
+
+### Telegram API Errors
+- Log warning but continue trading
+- Missing credentials → auto-disable notifications
+- Network timeout → skip notification, no retry
+- Invalid token → log error, trading unaffected
+- Rate limit exceeded → queued via rate limiter
+
+**Guarantee**: Notification failures never interrupt trading operations.

src/analysis/scanner.py

@@ -76,6 +76,10 @@ class MarketScanner:
             if market.is_domestic:
                 orderbook = await self.broker.get_orderbook(stock_code)
             else:
+                # Rate limiting: Add 200ms delay for overseas API calls
+                # to prevent hitting KIS API rate limit (EGW00201)
+                await asyncio.sleep(0.2)
+
                 # For overseas, we need to adapt the price data structure
                 price_data = await self.overseas_broker.get_overseas_price(
                     market.exchange_code, stock_code

src/broker/kis_api.py

@@ -55,6 +55,7 @@ class KISBroker:
         self._session: aiohttp.ClientSession | None = None
         self._access_token: str | None = None
         self._token_expires_at: float = 0.0
+        self._token_lock = asyncio.Lock()
         self._rate_limiter = LeakyBucket(settings.RATE_LIMIT_RPS)
 
     def _get_session(self) -> aiohttp.ClientSession:
@@ -80,30 +81,42 @@ class KISBroker:
     # ------------------------------------------------------------------
 
     async def _ensure_token(self) -> str:
-        """Return a valid access token, refreshing if expired."""
+        """Return a valid access token, refreshing if expired.
+
+        Uses a lock to prevent concurrent token refresh attempts that would
+        hit the API's 1-per-minute rate limit (EGW00133).
+        """
+        # Fast path: check without lock
         now = asyncio.get_event_loop().time()
         if self._access_token and now < self._token_expires_at:
             return self._access_token
 
-        logger.info("Refreshing KIS access token")
+        # Slow path: acquire lock and refresh
-        session = self._get_session()
+        async with self._token_lock:
-        url = f"{self._base_url}/oauth2/tokenP"
+            # Re-check after acquiring lock (another coroutine may have refreshed)
-        body = {
+            now = asyncio.get_event_loop().time()
-            "grant_type": "client_credentials",
+            if self._access_token and now < self._token_expires_at:
-            "appkey": self._app_key,
+                return self._access_token
-            "appsecret": self._app_secret,
-        }
 
-        async with session.post(url, json=body) as resp:
+            logger.info("Refreshing KIS access token")
-            if resp.status != 200:
+            session = self._get_session()
-                text = await resp.text()
+            url = f"{self._base_url}/oauth2/tokenP"
-                raise ConnectionError(f"Token refresh failed ({resp.status}): {text}")
+            body = {
-            data = await resp.json()
+                "grant_type": "client_credentials",
+                "appkey": self._app_key,
+                "appsecret": self._app_secret,
+            }
 
-        self._access_token = data["access_token"]
+            async with session.post(url, json=body) as resp:
-        self._token_expires_at = now + data.get("expires_in", 86400) - 60  # 1-min buffer
+                if resp.status != 200:
-        logger.info("Token refreshed successfully")
+                    text = await resp.text()
-        return self._access_token
+                    raise ConnectionError(f"Token refresh failed ({resp.status}): {text}")
+                data = await resp.json()
+
+            self._access_token = data["access_token"]
+            self._token_expires_at = now + data.get("expires_in", 86400) - 60  # 1-min buffer
+            logger.info("Token refreshed successfully")
+            return self._access_token
 
     # ------------------------------------------------------------------
     # Hash Key (required for POST bodies)

src/config.py

@@ -37,7 +37,8 @@ class Settings(BaseSettings):
     DB_PATH: str = "data/trade_logs.db"
 
     # Rate Limiting (requests per second for KIS API)
-    RATE_LIMIT_RPS: float = 10.0
+    # Reduced to 5.0 to avoid EGW00201 "초당 거래건수 초과" errors
+    RATE_LIMIT_RPS: float = 5.0
 
     # Trading mode
     MODE: str = Field(default="paper", pattern="^(paper|live)$")

src/main.py

@@ -33,6 +33,35 @@ from src.notifications.telegram_client import TelegramClient
 
 logger = logging.getLogger(__name__)
 
+
+def safe_float(value: str | float | None, default: float = 0.0) -> float:
+    """Convert to float, handling empty strings and None.
+
+    Args:
+        value: Value to convert (string, float, or None)
+        default: Default value if conversion fails
+
+    Returns:
+        Converted float or default value
+
+    Examples:
+        >>> safe_float("123.45")
+        123.45
+        >>> safe_float("")
+        0.0
+        >>> safe_float(None)
+        0.0
+        >>> safe_float("invalid", 99.0)
+        99.0
+    """
+    if value is None or value == "":
+        return default
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
+
 # Target stock codes to monitor per market
 WATCHLISTS = {
     "KR": ["005930", "000660", "035420"],  # Samsung, SK Hynix, NAVER
@@ -77,16 +106,16 @@ async def trading_cycle(
         balance_data = await broker.get_balance()
 
         output2 = balance_data.get("output2", [{}])
-        total_eval = float(output2[0].get("tot_evlu_amt", "0")) if output2 else 0
+        total_eval = safe_float(output2[0].get("tot_evlu_amt", "0")) if output2 else 0
-        total_cash = float(
+        total_cash = safe_float(
             balance_data.get("output2", [{}])[0].get("dnca_tot_amt", "0")
             if output2
             else "0"
         )
-        purchase_total = float(output2[0].get("pchs_amt_smtl_amt", "0")) if output2 else 0
+        purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0")) if output2 else 0
 
-        current_price = float(orderbook.get("output1", {}).get("stck_prpr", "0"))
+        current_price = safe_float(orderbook.get("output1", {}).get("stck_prpr", "0"))
-        foreigner_net = float(orderbook.get("output1", {}).get("frgn_ntby_qty", "0"))
+        foreigner_net = safe_float(orderbook.get("output1", {}).get("frgn_ntby_qty", "0"))
     else:
         # Overseas market
         price_data = await overseas_broker.get_overseas_price(
@@ -95,11 +124,19 @@ async def trading_cycle(
         balance_data = await overseas_broker.get_overseas_balance(market.exchange_code)
 
         output2 = balance_data.get("output2", [{}])
-        total_eval = float(output2[0].get("frcr_evlu_tota", "0")) if output2 else 0
+        # Handle both list and dict response formats
-        total_cash = float(output2[0].get("frcr_dncl_amt_2", "0")) if output2 else 0
+        if isinstance(output2, list) and output2:
-        purchase_total = float(output2[0].get("frcr_buy_amt_smtl", "0")) if output2 else 0
+            balance_info = output2[0]
+        elif isinstance(output2, dict):
+            balance_info = output2
+        else:
+            balance_info = {}
 
-        current_price = float(price_data.get("output", {}).get("last", "0"))
+        total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
+        total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
+        purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
+
+        current_price = safe_float(price_data.get("output", {}).get("last", "0"))
         foreigner_net = 0.0  # Not available for overseas
 
     # Calculate daily P&L %

tests/test_broker.py

@@ -49,6 +49,46 @@ class TestTokenManagement:
 
         await broker.close()
 
+    @pytest.mark.asyncio
+    async def test_concurrent_token_refresh_calls_api_once(self, settings):
+        """Multiple concurrent token requests should only call API once."""
+        broker = KISBroker(settings)
+
+        # Track how many times the mock API is called
+        call_count = [0]
+
+        def create_mock_resp():
+            call_count[0] += 1
+            mock_resp = AsyncMock()
+            mock_resp.status = 200
+            mock_resp.json = AsyncMock(
+                return_value={
+                    "access_token": "tok_concurrent",
+                    "token_type": "Bearer",
+                    "expires_in": 86400,
+                }
+            )
+            mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+            mock_resp.__aexit__ = AsyncMock(return_value=False)
+            return mock_resp
+
+        with patch("aiohttp.ClientSession.post", return_value=create_mock_resp()):
+            # Launch 5 concurrent token requests
+            tokens = await asyncio.gather(
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+                broker._ensure_token(),
+            )
+
+            # All should get the same token
+            assert all(t == "tok_concurrent" for t in tokens)
+            # API should be called only once (due to lock)
+            assert call_count[0] == 1
+
+        await broker.close()
+
 
 # ---------------------------------------------------------------------------
 # Network Error Handling

tests/test_main.py

@@ -6,7 +6,43 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 
 from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected
-from src.main import trading_cycle
+from src.main import safe_float, trading_cycle
+
+
+class TestSafeFloat:
+    """Test safe_float() helper function."""
+
+    def test_converts_valid_string(self):
+        """Test conversion of valid numeric string."""
+        assert safe_float("123.45") == 123.45
+        assert safe_float("0") == 0.0
+        assert safe_float("-99.9") == -99.9
+
+    def test_handles_empty_string(self):
+        """Test empty string returns default."""
+        assert safe_float("") == 0.0
+        assert safe_float("", 99.0) == 99.0
+
+    def test_handles_none(self):
+        """Test None returns default."""
+        assert safe_float(None) == 0.0
+        assert safe_float(None, 42.0) == 42.0
+
+    def test_handles_invalid_string(self):
+        """Test invalid string returns default."""
+        assert safe_float("invalid") == 0.0
+        assert safe_float("not_a_number", 100.0) == 100.0
+        assert safe_float("12.34.56") == 0.0
+
+    def test_handles_float_input(self):
+        """Test float input passes through."""
+        assert safe_float(123.45) == 123.45
+        assert safe_float(0.0) == 0.0
+
+    def test_custom_default(self):
+        """Test custom default value."""
+        assert safe_float("", -1.0) == -1.0
+        assert safe_float(None, 999.0) == 999.0
 
 
 class TestTradingCycleTelegramIntegration:
@@ -341,3 +377,221 @@ class TestRunFunctionTelegramIntegration:
             pnl_pct=-3.5,
             threshold=-3.0,
         )
+
+
+class TestOverseasBalanceParsing:
+    """Test overseas balance output2 parsing handles different formats."""
+
+    @pytest.fixture
+    def mock_overseas_broker_with_list(self) -> MagicMock:
+        """Create mock overseas broker returning list format."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "frcr_evlu_tota": "10000.00",
+                        "frcr_dncl_amt_2": "5000.00",
+                        "frcr_buy_amt_smtl": "4500.00",
+                    }
+                ]
+            }
+        )
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_broker_with_dict(self) -> MagicMock:
+        """Create mock overseas broker returning dict format."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": {
+                    "frcr_evlu_tota": "10000.00",
+                    "frcr_dncl_amt_2": "5000.00",
+                    "frcr_buy_amt_smtl": "4500.00",
+                }
+            }
+        )
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_broker_with_empty(self) -> MagicMock:
+        """Create mock overseas broker returning empty output2."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "150.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
+        return broker
+
+    @pytest.fixture
+    def mock_domestic_broker(self) -> MagicMock:
+        """Create minimal mock domestic broker."""
+        broker = MagicMock()
+        return broker
+
+    @pytest.fixture
+    def mock_overseas_market(self) -> MagicMock:
+        """Create mock overseas market info."""
+        market = MagicMock()
+        market.name = "NASDAQ"
+        market.code = "US_NASDAQ"
+        market.exchange_code = "NASD"
+        market.is_domestic = False
+        return market
+
+    @pytest.fixture
+    def mock_brain_hold(self) -> MagicMock:
+        """Create mock brain that always holds."""
+        brain = MagicMock()
+        decision = MagicMock()
+        decision.action = "HOLD"
+        decision.confidence = 50
+        decision.rationale = "Testing balance parsing"
+        brain.decide = AsyncMock(return_value=decision)
+        return brain
+
+    @pytest.fixture
+    def mock_risk(self) -> MagicMock:
+        """Create mock risk manager."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_db(self) -> MagicMock:
+        """Create mock database."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_decision_logger(self) -> MagicMock:
+        """Create mock decision logger."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_context_store(self) -> MagicMock:
+        """Create mock context store."""
+        store = MagicMock()
+        store.get_latest_timeframe = MagicMock(return_value=None)
+        return store
+
+    @pytest.fixture
+    def mock_criticality_assessor(self) -> MagicMock:
+        """Create mock criticality assessor."""
+        assessor = MagicMock()
+        assessor.assess_market_conditions = MagicMock(
+            return_value=MagicMock(value="NORMAL")
+        )
+        assessor.get_timeout = MagicMock(return_value=5.0)
+        return assessor
+
+    @pytest.fixture
+    def mock_telegram(self) -> MagicMock:
+        """Create mock telegram client."""
+        return MagicMock()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_list_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_list: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with list format (output2=[{...}])."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_list,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_list.get_overseas_balance.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_dict_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_dict: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with dict format (output2={...})."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_dict,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_dict.get_overseas_balance.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_overseas_balance_empty_format(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_empty: MagicMock,
+        mock_brain_hold: MagicMock,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Test overseas balance parsing with empty output2."""
+        with patch("src.main.log_trade"):
+            # Should not raise KeyError, should default to 0
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_empty,
+                brain=mock_brain_hold,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+            )
+
+        # Verify balance API was called
+        mock_overseas_broker_with_empty.get_overseas_balance.assert_called_once()