Merge branch 'main_merge_20260904' into 'main'

[API-1623]: support option leg-in/leg-out on single-leg orders (US only)

See merge request webull/webull-openapi-mcp!21

Author: 方佳

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "webull-openapi-mcp"
-version = "1.2.2"
+version = "1.2.3"
 description = "MCP Server for Webull OpenAPI - enables AI assistants to securely access Webull trading and market data"
 readme = "README.md"
 license = "Apache-2.0"

webull_openapi_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Webull OpenAPI MCP Server - AI assistant integration for Webull OpenAPI."""
 
-__version__ = "1.2.2"
+__version__ = "1.2.3"

webull_openapi_mcp/constants.py

@@ -35,6 +35,9 @@
     "SELL_TO_CLOSE",
 })
 
+# Option leg-in / leg-out values (US only)
+VALID_LEG_IN_OUT: frozenset[str] = frozenset({"LEG_IN", "LEG_OUT"})
+
 # Trading session types
 VALID_TRADING_SESSIONS: frozenset[str] = frozenset({"ALL", "CORE", "NIGHT"})
 

webull_openapi_mcp/formatters.py

@@ -215,34 +215,86 @@ def format_account_balance(data: dict | None) -> str:
 
 def format_positions(data: list[dict] | None) -> str:
     """Format account positions response.
-    
-    API returns: [{position_id, currency, quantity, symbol, option_strategy,
-    instrument_type, last_price, cost_price, unrealized_profit_loss, legs: [...]}]
+
+    Top-level core (all regions): position_id, currency, quantity, symbol,
+    option_strategy, instrument_type, last_price, cost_price,
+    unrealized_profit_loss, legs: [...].
+    Top-level region-specific:
+    - US:  event_outcome (event orders only)
+    - JP:  available_quantity, market_value, symbol_name, exchange_code,
+           instrument_id, account_tax_type, base_currency, fx_rate,
+           base_currency_market_value
+
+    Leg fields differ by region:
+    - US:  side, quantity, market, instrument_type, symbol, strike_price,
+           option_expire_date, option_type (no leg_id)
+    - HK:  symbol, quantity, option_type, option_expire_date,
+           option_exercise_price, option_contract_multiplier,
+           option_contract_deliverable, expiration_type (no leg_id)
+    - JP:  same as HK plus leg_id
+
+    The formatter reads whichever fields are present so it works across regions.
     """
     if not data:
         return _NO_DATA
     lines: list[str] = ["=== Positions ==="]
     for pos in data:
-        lines.append(
-            f"  {_get(pos, 'symbol'):>8s}  "
-            f"Qty: {_get(pos, 'quantity'):>8s}  "
-            f"Type: {_get(pos, 'instrument_type'):>6s}  "
-            f"Cost: {_get(pos, 'cost_price'):>10s}  "
-            f"Last: {_get(pos, 'last_price'):>10s}  "
-            f"Unrealized P&L: {_get(pos, 'unrealized_profit_loss'):>10s}  "
-            f"Currency: {_get(pos, 'currency')}"
-        )
-        # Option legs
+        # Top-level fields — show only present fields (varies by region).
+        head_fields: list[tuple[str, str]] = [
+            ("Symbol", "symbol"),
+            ("Position ID", "position_id"),
+            ("Qty", "quantity"),
+            ("Available Qty", "available_quantity"),
+            ("Type", "instrument_type"),
+            ("Strategy", "option_strategy"),
+            ("Name", "symbol_name"),
+            ("Exchange", "exchange_code"),
+            ("Instrument ID", "instrument_id"),
+            ("Cost", "cost_price"),
+            ("Last", "last_price"),
+            ("Market Value", "market_value"),
+            ("Unrealized P&L", "unrealized_profit_loss"),
+            ("Currency", "currency"),
+            ("Event Outcome", "event_outcome"),
+            ("Tax Type", "account_tax_type"),
+            ("Base Currency", "base_currency"),
+            ("FX Rate", "fx_rate"),
+            ("Base Market Value", "base_currency_market_value"),
+        ]
+        head_parts = [
+            f"{label}: {pos[key]}"
+            for label, key in head_fields
+            if pos.get(key) is not None
+        ]
+        lines.append("  " + "  ".join(head_parts))
+
+        # Option legs — field set varies by region; show only present fields.
         legs = pos.get("legs", [])
         for leg in legs:
-            lines.append(
-                f"{'':>10s}  "
-                f"Leg: {_get(leg, 'symbol')}  "
-                f"Qty: {_get(leg, 'quantity')}  "
-                f"Type: {_get(leg, 'option_type')}  "
-                f"Strike: {_get(leg, 'option_exercise_price')}  "
-                f"Exp: {_get(leg, 'option_expire_date')}"
-            )
+            parts: list[str] = [f"Leg: {_get(leg, 'symbol')}"]
+            if leg.get("leg_id") is not None:
+                parts.append(f"Leg ID: {leg['leg_id']}")
+            if leg.get("side") is not None:
+                parts.append(f"Side: {leg['side']}")
+            parts.append(f"Qty: {_get(leg, 'quantity')}")
+            if leg.get("instrument_type") is not None:
+                parts.append(f"Type: {leg['instrument_type']}")
+            if leg.get("option_type") is not None:
+                parts.append(f"Option: {leg['option_type']}")
+            # Strike: US uses strike_price, HK/JP use option_exercise_price
+            strike = leg.get("strike_price") or leg.get("option_exercise_price")
+            if strike is not None:
+                parts.append(f"Strike: {strike}")
+            if leg.get("option_expire_date") is not None:
+                parts.append(f"Exp: {leg['option_expire_date']}")
+            # HK/JP-only option contract fields
+            if leg.get("option_contract_multiplier") is not None:
+                parts.append(f"Multiplier: {leg['option_contract_multiplier']}")
+            if leg.get("option_contract_deliverable") is not None:
+                parts.append(f"Deliverable: {leg['option_contract_deliverable']}")
+            if leg.get("expiration_type") is not None:
+                parts.append(f"ExpType: {leg['expiration_type']}")
+            lines.append(f"{'':>10s}  " + "  ".join(parts))
     return "\n".join(lines)
 
 
@@ -262,45 +314,38 @@ def format_position_details(data: list[dict] | dict | None) -> str:
     if not isinstance(data, list) or not data:
         return _NO_DATA
 
+    # Field labels in display order; only present fields are shown.
+    fields: list[tuple[str, str]] = [
+        ("Position ID", "id"),
+        ("Symbol", "symbol"),
+        ("Name", "symbol_name"),
+        ("Exchange", "exchange_code"),
+        ("Instrument ID", "instrument_id"),
+        ("Contract ID", "contract_id"),
+        ("Qty", "quantity"),
+        ("Hold Type", "hold_type"),
+        ("Margin Type", "margin_type"),
+        ("Average Price", "average_price"),
+        ("Market Value", "market_value"),
+        ("Unrealized P&L", "unrealized_pl"),
+        ("Currency", "currency"),
+        ("Account Tax Type", "account_tax_type"),
+        ("Base Currency", "base_currency"),
+        ("FX Rate", "fx_rate"),
+        ("Base Currency Market Value", "base_currency_market_value"),
+    ]
+
     lines: list[str] = ["=== Position Details ==="]
     for i, detail in enumerate(data, 1):
         if not isinstance(detail, dict):
             continue
         lines.append(f"\n[Position Detail {i}]")
-        lines.append(
-            f"  {_get(detail, 'symbol'):>8s}  "
-            f"Qty: {_get(detail, 'quantity'):>8s}  "
-            f"Hold: {_get(detail, 'hold_type'):>6s}  "
-            f"Market Value: {_get(detail, 'market_value'):>10s}  "
-            f"Currency: {_get(detail, 'currency')}"
-        )
-        lines.append(
-            f"{'':>10s}  "
-            f"Name: {_get(detail, 'symbol_name')}  "
-            f"Exchange: {_get(detail, 'exchange_code')}"
-        )
-        lines.append(
-            f"{'':>10s}  "
-            f"Average Price: {_get(detail, 'average_price'):>10s}  "
-            f"Unrealized P&L: {_get(detail, 'unrealized_pl'):>10s}"
-        )
-        lines.append(
-            f"{'':>10s}  "
-            f"Account Tax Type: {_get(detail, 'account_tax_type')}  "
-            f"Margin Type: {_get(detail, 'margin_type')}"
-        )
-        lines.append(
-            f"{'':>10s}  "
-            f"Instrument ID: {_get(detail, 'instrument_id')}  "
-            f"Contract ID: {_get(detail, 'contract_id')}  "
-            f"Position ID: {_get(detail, 'id')}"
-        )
-        lines.append(
-            f"{'':>10s}  "
-            f"Base Currency: {_get(detail, 'base_currency')}  "
-            f"FX Rate: {_get(detail, 'fx_rate')}  "
-            f"Base Currency Market Value: {_get(detail, 'base_currency_market_value')}"
-        )
+        parts = [
+            f"{label}: {detail[key]}"
+            for label, key in fields
+            if detail.get(key) is not None
+        ]
+        lines.append("  " + "  ".join(parts))
 
     if len(lines) == 1:
         return _NO_DATA

webull_openapi_mcp/tools/trading/option_order.py

@@ -81,6 +81,9 @@ def _build_option_order(
     limit_price: float | None,
     stop_price: float | None,
     position_intent: str | None = None,
+    leg_in_or_out: str | None = None,
+    position_id: str | None = None,
+    leg_in_strategy: str | None = None,
 ) -> dict:
     """Build a single-leg option order dict for the SDK."""
     order: dict = {
@@ -109,6 +112,13 @@ def _build_option_order(
     _add_optional_str(order, "stop_price", stop_price)
     if position_intent is not None:
         order["position_intent"] = position_intent
+    # Option leg-in / leg-out fields (US only)
+    if leg_in_or_out is not None:
+        order["leg_in_or_out"] = leg_in_or_out
+    if position_id is not None:
+        order["position_id"] = position_id
+    if leg_in_strategy is not None:
+        order["leg_in_strategy"] = leg_in_strategy
     return order
 
 
@@ -237,6 +247,10 @@ def register_option_single_tools(
             "order_type: MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT.\n"
             "time_in_force: DAY, GTC. trading_session: CORE only.\n"
             "position_intent: BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, SELL_TO_CLOSE (optional, US only).\n"
+            "Leg-in / leg-out (US only, single-leg option): "
+            "leg_in_or_out=LEG_IN adds this leg to an existing position; LEG_OUT closes a leg from a multi-leg position. "
+            "position_id (from Account Positions API) is required when leg_in_or_out is set. "
+            "leg_in_strategy (COVERED_STOCK/VERTICAL/STRADDLE/STRANGLE/CALENDAR/DIAGONAL) is required for LEG_IN, not allowed for LEG_OUT.\n"
             "Returns: {client_order_id, order_id}"
         ),
     )
@@ -254,6 +268,9 @@ async def place_option_single_order(
         limit_price: Optional[float] = None,
         stop_price: Optional[float] = None,
         position_intent: Optional[str] = None,
+        leg_in_or_out: Optional[str] = None,
+        position_id: Optional[str] = None,
+        leg_in_strategy: Optional[str] = None,
     ) -> str:
         """Place a single-leg option order."""
         audit.log_tool_call("place_option_single_order", {"symbol": symbol, "side": side})
@@ -283,6 +300,27 @@ async def place_option_single_order(
                     f"must be one of {sorted(VALID_POSITION_INTENTS)}"
                 )
 
+        # Leg-in / leg-out validation (US only)
+        if leg_in_or_out is not None or position_id is not None or leg_in_strategy is not None:
+            from webull_openapi_mcp.constants import VALID_LEG_IN_OUT
+            if config.region_id != "us":
+                return "Validation error: leg-in / leg-out is only supported for US region"
+            if leg_in_or_out is None:
+                return "Validation error: leg_in_or_out is required when position_id or leg_in_strategy is provided"
+            if leg_in_or_out not in VALID_LEG_IN_OUT:
+                return (
+                    f"Validation error: Invalid leg_in_or_out '{leg_in_or_out}', "
+                    f"must be one of {sorted(VALID_LEG_IN_OUT)}"
+                )
+            if position_id is None:
+                return "Validation error: position_id is required when leg_in_or_out is specified"
+            if leg_in_or_out == "LEG_IN":
+                if leg_in_strategy is None:
+                    return "Validation error: leg_in_strategy is required when leg_in_or_out is LEG_IN"
+            else:  # LEG_OUT
+                if leg_in_strategy is not None:
+                    return "Validation error: leg_in_strategy is not allowed when leg_in_or_out is LEG_OUT"
+
         try:
             validate_client_order_id(client_order_id)
         except ValidationError as e:
@@ -297,6 +335,9 @@ async def place_option_single_order(
             time_in_force=time_in_force,
             limit_price=limit_price, stop_price=stop_price,
             position_intent=position_intent,
+            leg_in_or_out=leg_in_or_out,
+            position_id=position_id,
+            leg_in_strategy=leg_in_strategy,
         )
 
         audit.log_order_attempt(

webull_openapi_mcp/tools/trading/stock_order.py

@@ -128,6 +128,10 @@ def _build_stock_order(params: dict) -> dict:
     _add_optional_str(order, "position_intent", params.get("position_intent"))
     if params.get("close_contracts") is not None:
         order["close_contracts"] = params["close_contracts"]
+    # Option leg-in / leg-out fields (US only) — e.g. legging a stock leg out of a combo
+    _add_optional_str(order, "leg_in_or_out", params.get("leg_in_or_out"))
+    _add_optional_str(order, "position_id", params.get("position_id"))
+    _add_optional_str(order, "leg_in_strategy", params.get("leg_in_strategy"))
 
     return order
 
@@ -447,6 +451,10 @@ def register_stock_order_tools(
             "margin_type must be ONE_DAY or INDEFINITE and is margin-account-only; "
             "position_intent must be BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, or SELL_TO_CLOSE and is margin-account-only; "
             "close_contracts account eligibility is checked by the API backend.\n"
+            "Leg-in / leg-out (US only): use to leg a STOCK leg into/out of an option combo position. "
+            "leg_in_or_out=LEG_IN adds this stock leg to an existing position; LEG_OUT closes the stock leg from a multi-leg combo. "
+            "position_id (from Account Positions API) is required when leg_in_or_out is set. "
+            "leg_in_strategy (COVERED_STOCK/VERTICAL/STRADDLE/STRANGLE/CALENDAR/DIAGONAL) is required for LEG_IN, not allowed for LEG_OUT.\n"
             "Returns: {client_order_id, order_id}"
         ),
     )
@@ -472,6 +480,9 @@ async def place_stock_order(
         margin_type: Optional[MarginType] = None,
         position_intent: Optional[PositionIntent] = None,
         close_contracts: Optional[list[dict]] = None,
+        leg_in_or_out: Optional[str] = None,
+        position_id: Optional[str] = None,
+        leg_in_strategy: Optional[str] = None,
     ) -> str:
         """Place a single stock order (non-combo).
 
@@ -531,6 +542,27 @@ async def place_stock_order(
         except ValidationError as e:
             return f"Validation error: {e.message}"
 
+        # Leg-in / leg-out validation (US only) — e.g. legging a stock leg into/out of a combo
+        if leg_in_or_out is not None or position_id is not None or leg_in_strategy is not None:
+            from webull_openapi_mcp.constants import VALID_LEG_IN_OUT
+            if config.region_id != "us":
+                return "Validation error: leg-in / leg-out is only supported for US region"
+            if leg_in_or_out is None:
+                return "Validation error: leg_in_or_out is required when position_id or leg_in_strategy is provided"
+            if leg_in_or_out not in VALID_LEG_IN_OUT:
+                return (
+                    f"Validation error: Invalid leg_in_or_out '{leg_in_or_out}', "
+                    f"must be one of {sorted(VALID_LEG_IN_OUT)}"
+                )
+            if position_id is None:
+                return "Validation error: position_id is required when leg_in_or_out is specified"
+            if leg_in_or_out == "LEG_IN":
+                if leg_in_strategy is None:
+                    return "Validation error: leg_in_strategy is required when leg_in_or_out is LEG_IN"
+            else:  # LEG_OUT
+                if leg_in_strategy is not None:
+                    return "Validation error: leg_in_strategy is not allowed when leg_in_or_out is LEG_OUT"
+
         coid = client_order_id or _generate_client_order_id()
 
         order = _build_stock_order({
@@ -546,6 +578,9 @@ async def place_stock_order(
             "margin_type": margin_type,
             "position_intent": position_intent,
             "close_contracts": close_contracts,
+            "leg_in_or_out": leg_in_or_out,
+            "position_id": position_id,
+            "leg_in_strategy": leg_in_strategy,
         })
 
         audit.log_order_attempt(