ivolatility-backtesting 2.146__tar.gz → 2.147__tar.gz

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 2.146
+Version: 2.147
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/ivolatility_backtesting/__init__.py

@@ -27,7 +27,7 @@ from .ivolatility_backtesting import (
     check_portfolio_stop_loss,
     FUTURES_HEDGE_MAP, _load_futures_for_hedge,
     set_project_root, get_project_root,
-    get_position_multiplier,
+    get_position_multiplier, get_hedge_multiplier,
 )
 
 __all__ = [
@@ -59,5 +59,5 @@ __all__ = [
     'check_portfolio_stop_loss',
     'FUTURES_HEDGE_MAP', '_load_futures_for_hedge',
     'set_project_root', 'get_project_root',
-    'get_position_multiplier',
+    'get_position_multiplier', 'get_hedge_multiplier',
 ]

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/ivolatility_backtesting/ivolatility_backtesting.py

@@ -6029,15 +6029,16 @@ class StrategyRegistry:
         credit = abs(total_cost)
         debit = abs(total_cost)
         premium = abs(total_cost)
-        
+        um = _pos_unit_multiplier(position)
+
         # Category-specific calculations (driven by STRATEGIES['category'])
         category = strategy['category']
-        
+
         if category == 'CREDIT':
-            # Credit spreads: max loss = (width * 100 * contracts) - credit
+            # Credit spreads: max loss = (width * unit_multiplier * contracts) - credit
             if position_type == 'IRON_CONDOR':
                 wing_width = position.get('wing_width', 5)
-                max_loss_per_contract = (wing_width * 100) - (credit / contracts if contracts > 0 else 0)
+                max_loss_per_contract = (wing_width * um) - (credit / contracts if contracts > 0 else 0)
                 max_loss = max_loss_per_contract * contracts
                 capital_at_risk = max(max_loss * 1.5, credit * 2)
                 locked_capital = credit
@@ -6047,39 +6048,39 @@ class StrategyRegistry:
                 long_strike = position.get('long_strike', 0)
                 if short_strike and long_strike:
                     spread_width = abs(long_strike - short_strike)
-                    max_loss = (spread_width * 100 * contracts) - credit
+                    max_loss = (spread_width * um * contracts) - credit
                     capital_at_risk = max(abs(max_loss) * 1.5, credit * 2)
                     locked_capital = credit
                 else:
                     capital_at_risk = credit * 2
                     locked_capital = credit
-            
+
             elif position_type == 'IRON_BUTTERFLY':
                 wing_width = position.get('wing_width', 10)
-                max_loss = (wing_width * 100 * contracts) - credit
+                max_loss = (wing_width * um * contracts) - credit
                 capital_at_risk = max(abs(max_loss) * 1.5, credit * 2)
                 locked_capital = credit
-            
+
             else:
                 # Generic credit strategy
                 capital_at_risk = credit * 2
                 locked_capital = credit
-        
+
         elif category == 'DEBIT':
             # Debit strategies: max loss = debit paid
             capital_at_risk = debit * 1.5
             locked_capital = debit
-        
+
         elif category == 'NEUTRAL':
+            underlying_price = position.get('underlying_entry_price', 0)
             if position_type == 'COVERED_CALL':
-                underlying_price = position.get('underlying_entry_price', 0)
-                stock_value = underlying_price * contracts * 100
+                stock_value = underlying_price * contracts * um
                 # Use call_premium if available, fallback to credit for backward compatibility
                 call_premium = position.get('call_premium', abs(credit))
                 capital_at_risk = max(stock_value - call_premium, stock_value * 0.8)
                 locked_capital = stock_value
             elif position_type in ('LONG_STOCK', 'SHORT_STOCK'):
-                stock_value = underlying_price * contracts * 100
+                stock_value = underlying_price * contracts * um
                 capital_at_risk = stock_value
                 locked_capital = stock_value
             else:
@@ -6322,7 +6323,7 @@ class StrategyRegistry:
             return 0.0
 
         if unit_multiplier is None:
-            unit_multiplier = position.get('unit_multiplier', 100)
+            unit_multiplier = _pos_unit_multiplier(position)
 
         category = strategy.get('category', 'DEBIT')
         contracts = position.get('contracts', 1)
@@ -6526,7 +6527,8 @@ class StrategyRegistry:
         category = strategy.get('category', 'DEBIT')
         total_cost = entry_cost_info.get('total', 0)
         contracts = position_params.get('contracts', 1)
-        
+        um = _pos_unit_multiplier(position_params)
+
         # NEUTRAL strategies (STRADDLE/STRANGLE) can be DEBIT or CREDIT
         # Check if it's a DEBIT position by looking at total_cost sign
         is_debit = total_cost > 0
@@ -6539,34 +6541,34 @@ class StrategyRegistry:
         # NOTE: total_cost is ALREADY multiplied by contracts in calculate_entry_cost()!
         if strategy_type == 'IRON_CONDOR':
             wing_width = position_params.get('wing_width', 0)
-            # Max risk = (wing_width * 100 * contracts) - credit (only ONE side can lose)
+            # Max risk = (wing_width * unit_multiplier * contracts) - credit (only ONE side can lose)
             # total_cost is negative for credit, so we add it
-            return (wing_width * 100 * contracts) + total_cost  # total_cost already includes contracts
-        
+            return (wing_width * um * contracts) + total_cost  # total_cost already includes contracts
+
         elif strategy_type in ['BULL_PUT_SPREAD', 'BEAR_CALL_SPREAD', 'CREDIT_SPREAD']:
             spread_width = position_params.get('spread_width', 0)
-            # Max risk = (spread_width * 100 * contracts) - credit
-            return (spread_width * 100 * contracts) + total_cost  # total_cost already includes contracts
-        
+            # Max risk = (spread_width * unit_multiplier * contracts) - credit
+            return (spread_width * um * contracts) + total_cost  # total_cost already includes contracts
+
         elif strategy_type == 'IRON_BUTTERFLY':
             wing_width = position_params.get('wing_width', 0)
-            # Max risk = (wing_width * 100 * contracts) - credit (similar to Iron Condor)
-            return (wing_width * 100 * contracts) + total_cost  # total_cost already includes contracts
-        
+            # Max risk = (wing_width * unit_multiplier * contracts) - credit (similar to Iron Condor)
+            return (wing_width * um * contracts) + total_cost  # total_cost already includes contracts
+
         elif strategy_type == 'COVERED_CALL':
             # Max risk = stock cost - call premium (stock can go to $0, but we keep premium)
             stock_price = position_params.get('stock_price', 0)
             # total_cost is negative (credit from selling call), so adding it reduces risk
-            return (stock_price * 100 * contracts) + total_cost  # subtract call premium
-        
+            return (stock_price * um * contracts) + total_cost  # subtract call premium
+
         elif strategy_type in ('LONG_STOCK', 'SHORT_STOCK'):
             stock_price = position_params.get('stock_price', position_params.get('underlying_entry_price', 0))
-            return stock_price * 100 * contracts
-        
+            return stock_price * um * contracts
+
         elif strategy_type == 'CASH_SECURED_PUT':
             strike = position_params.get('strike', 0)
             # Max risk = (strike * contracts) - premium (if stock goes to $0)
-            return (strike * 100 * contracts) + total_cost  # total_cost already includes contracts
+            return (strike * um * contracts) + total_cost  # total_cost already includes contracts
         
         elif strategy_type in ['STRADDLE', 'STRANGLE'] or category == 'NEUTRAL':
             # For short NEUTRAL strategies (short straddle/strangle)
@@ -6744,6 +6746,7 @@ class StrategyRegistry:
             # 2. Calculate P&L
             entry_cost = position.get('total_cost', 0)
             contracts = position.get('contracts', 1)
+            um = _pos_unit_multiplier(position)
 
             # ── COVERED_CALL special case ──────────────────────────────────────
             # COVERED_CALL = long stock + short call.
@@ -6758,7 +6761,7 @@ class StrategyRegistry:
             # Fix: compute P&L directly using underlying_price (available here) + call leg.
             # ── LONG_STOCK / SHORT_STOCK — pure stock position, no option legs ──
             if strategy_type in ('LONG_STOCK', 'SHORT_STOCK'):
-                stock_exit_value = underlying_price * contracts * 100
+                stock_exit_value = underlying_price * contracts * um
                 if strategy_type == 'SHORT_STOCK':
                     pnl = entry_cost - stock_exit_value  # short: profit when price drops
                 else:
@@ -6776,8 +6779,8 @@ class StrategyRegistry:
                     put_data = leg_data.get('put')
                     if put_data is not None:
                         put_close_ask = put_data.get('ask', put_data.get('bid', 0))
-                        stock_exit_value = underlying_price * contracts * 100
-                        put_close_cost = put_close_ask * contracts * 100
+                        stock_exit_value = underlying_price * contracts * um
+                        put_close_cost = put_close_ask * contracts * um
                         # Short stock gains when price drops: entry_cost - stock_exit - put_buyback
                         pnl = entry_cost - stock_exit_value - put_close_cost
                         is_credit = False
@@ -6791,8 +6794,8 @@ class StrategyRegistry:
                     call_data = leg_data.get('call')
                     if call_data is not None:
                         call_close_ask = call_data.get('ask', call_data.get('bid', 0))
-                        stock_exit_value = underlying_price * contracts * 100
-                        call_close_cost  = call_close_ask * contracts * 100
+                        stock_exit_value = underlying_price * contracts * um
+                        call_close_cost  = call_close_ask * contracts * um
                         pnl = stock_exit_value - call_close_cost - entry_cost
                         is_credit = False  # Treat as DEBIT for % formula (entry_cost is positive)
                         close_cost = stock_exit_value - call_close_cost  # for fall-through fields
@@ -9773,9 +9776,9 @@ class StopLossManager:
 
             if entry_price and entry_price > 0:
                 if leg['direction'] == 'long':
-                    entry_value += entry_price * 100 * contracts   # Pay for long
+                    entry_value += entry_price * _pos_unit_multiplier(pos) * contracts   # Pay for long
                 else:
-                    entry_value -= entry_price * 100 * contracts   # Receive for short
+                    entry_value -= entry_price * _pos_unit_multiplier(pos) * contracts   # Receive for short
 
         return abs(entry_value) if entry_value != 0 else abs(pos.get('entry_price', 0))
 
@@ -9872,11 +9875,11 @@ class StopLossManager:
             if leg['direction'] == 'long':
                 # To close long position, we SELL at bid
                 current_price = matching_bar.get('bid', 0)
-                current_value += current_price * 100 * contracts
+                current_value += current_price * _pos_unit_multiplier(pos) * contracts
             else:
                 # To close short position, we BUY at ask
                 current_price = matching_bar.get('ask', 0)
-                current_value -= current_price * 100 * contracts
+                current_value -= current_price * _pos_unit_multiplier(pos) * contracts
 
         # ── COVERED_CALL stock leg adjustment ────────────────────────────────
         # The stock leg is NOT in the options bars, but intraday option bars include
@@ -9894,10 +9897,10 @@ class StopLossManager:
             if underlying_price_bar and underlying_price_bar > 0:
                 if 'COVERED_PUT' in strategy_type.upper():
                     # Short stock: closing means buying back → subtract
-                    current_value -= underlying_price_bar * contracts * 100
+                    current_value -= underlying_price_bar * contracts * _pos_unit_multiplier(pos)
                 else:
                     # Long stock (COVERED_CALL): closing means selling → add
-                    current_value += underlying_price_bar * contracts * 100
+                    current_value += underlying_price_bar * contracts * _pos_unit_multiplier(pos)
 
         return current_value
 
@@ -10250,7 +10253,7 @@ class StopLossManager:
                         else:
                             print(f"  [P&L Stop Intraday] Stock: {len(bars)} bars, entry=${entry_price:.2f}, threshold={loss_threshold_pct:.2f}%")
 
-                    qty = pos.get('quantity') or pos.get('contracts', 1) * 100
+                    qty = pos.get('quantity') or pos.get('contracts', 1) * _pos_unit_multiplier(pos)
                     stock_entry_value = entry_price * qty
 
                     for bar_idx, bar in enumerate(bars):
@@ -10263,7 +10266,7 @@ class StopLossManager:
 
                         if _use_cc_pnl:
                             # COVERED_CALL/PUT: option leg near-zero (deep OTM), stock dominates
-                            bar_stock_value = bar_price * _cc_contracts * 100
+                            bar_stock_value = bar_price * _cc_contracts * _pos_unit_multiplier(pos)
                             if 'COVERED_PUT' in pos.get('strategy_type', '').upper():
                                 # Short stock: gains when price drops
                                 bar_pnl_pct = (_cc_total_cost - bar_stock_value) / _cc_total_cost * 100
@@ -10279,7 +10282,7 @@ class StopLossManager:
                             if _use_cc_pnl:
                                 # COVERED_CALL: return full position values for correct $ P&L
                                 _stop_entry_value = _cc_total_cost
-                                _stop_current_value = bar_price * _cc_contracts * 100  # call ≈ 0
+                                _stop_current_value = bar_price * _cc_contracts * _pos_unit_multiplier(pos)  # call ≈ 0
                             else:
                                 _stop_entry_value = stock_entry_value
                                 _stop_current_value = bar_price * qty
@@ -10587,7 +10590,7 @@ class StopLossManager:
                                         sp = sb.get('lastPrice', 0)
                                         st = sb.get('lastDateTime', '')
                                         if sp and sp > 0 and '00:00:00' not in str(st):
-                                            stock_value_931 = sp * _cc_contracts * 100
+                                            stock_value_931 = sp * _cc_contracts * _pos_unit_multiplier(pos)
                                             baseline_value = stock_value_931 + _cc_call_value  # stock + call
                                             if self.debuginfo >= 2:
                                                 print(f"[SL BASELINE RESET] {position_id}: CC stock@9:31=${sp:.2f} call=${_cc_call_value:.2f} → baseline=${baseline_value:.0f}")
@@ -12390,8 +12393,8 @@ class PositionManager:
         intrinsic_value = 0
 
         # Per-point multiplier stamped on position at open (100 for equity,
-        # 50 for ES, 1000 for CL, …). Replaces previous hardcoded *100.
-        unit_multiplier = position.get('unit_multiplier', 100)
+        # 50 for ES, 1000 for CL, 50 for ZS, …).
+        unit_multiplier = _pos_unit_multiplier(position)
 
         # Get strategy info from registry
         strategy_info = STRATEGIES.get(strategy_type, {})
@@ -12849,6 +12852,7 @@ class PositionManager:
                 put_entry_bid=kwargs.get('put_entry_bid'),
                 total_cost=kwargs.get('total_cost'),
                 min_days_before_check=kwargs.get('min_days_before_check', 0),
+                unit_multiplier=position['unit_multiplier'],
             )
             # [FIX 4] Forward spread/diagonal/calendar fields needed by _get_position_legs()
             # These are stored via **kwargs in add_position() and read by CUSTOM fallback
@@ -13058,7 +13062,7 @@ class PositionManager:
                             current_pnl = entry_premium - intrinsic_value
                         else:
                             current_pnl = intrinsic_value - entry_premium
-                        _um = position.get('unit_multiplier', 100)
+                        _um = _pos_unit_multiplier(position)
                         current_price = (intrinsic_value / (_um * contracts)) if contracts > 0 else 0
 
                         # P&L %
@@ -13103,7 +13107,7 @@ class PositionManager:
                                     wing_width = abs(long_put - short_put)
                                 if wing_width > 0:
                                     total_cost_per_contract = abs(position.get('total_cost', 0)) / position.get('contracts', 1)
-                                    max_risk_per_contract = (wing_width * 100) - total_cost_per_contract
+                                    max_risk_per_contract = (wing_width * _pos_unit_multiplier(position)) - total_cost_per_contract
                                     max_risk_total = max_risk_per_contract * position.get('contracts', 1)
                             current_pnl_pct = (current_pnl / max_risk_total * 100) if max_risk_total > 0 else 0
                         elif current_pnl_pct is None:
@@ -13216,7 +13220,7 @@ class PositionManager:
                         if wing_width > 0:
                             # Use abs() because total_cost is negative for credits
                             total_cost_per_contract = abs(position.get('total_cost', 0)) / position.get('contracts', 1)
-                            max_risk_per_contract = (wing_width * 100) - total_cost_per_contract
+                            max_risk_per_contract = (wing_width * _pos_unit_multiplier(position)) - total_cost_per_contract
                             contracts = position.get('contracts', 1)
                             max_risk_total = max_risk_per_contract * contracts
                     
@@ -13759,7 +13763,7 @@ class PositionManager:
             if leg_data is None and strategy_type in ('LONG_STOCK', 'SHORT_STOCK'):
                 entry_cost = abs(position.get('total_cost', 0))
                 contracts = position.get('contracts', 1)
-                stock_exit_value = stock_price * contracts * 100
+                stock_exit_value = stock_price * contracts * _pos_unit_multiplier(position)
                 if strategy_type == 'SHORT_STOCK':
                     pnl = entry_cost - stock_exit_value
                 else:
@@ -14691,13 +14695,13 @@ class PositionManager:
             # ========================================
             if position_type == 'IRON_CONDOR':
                 # Iron Condor: short call spread + short put spread
-                # Max loss = wing_width * 100 * contracts - credit
+                # Max loss = wing_width * unit_multiplier * contracts - credit
                 wing_width = position.get('wing_width', 5)
                 contracts = position.get('contracts', 1)
                 credit = position.get('total_cost', 0)
                 
-                # Max loss per spread = (wing_width * 100) - credit_per_contract
-                max_loss_per_contract = (wing_width * 100) - (credit / contracts if contracts > 0 else 0)
+                # Max loss per spread = (wing_width * unit_multiplier) - credit_per_contract
+                max_loss_per_contract = (wing_width * _pos_unit_multiplier(position)) - (credit / contracts if contracts > 0 else 0)
                 max_loss = max_loss_per_contract * contracts
                 
                 # Capital at risk = max loss + safety buffer
@@ -14720,11 +14724,11 @@ class PositionManager:
                 if short_strike and long_strike:
                     spread_width = abs(long_strike - short_strike)
                     
-                    # Credit spreads: max loss = (spread_width * 100 * contracts) - credit
+                    # Credit spreads: max loss = (spread_width * unit_multiplier * contracts) - credit
                     # Debit spreads: max loss = debit paid (already in total_cost)
                     if position_type in ['BULL_PUT_SPREAD', 'BEAR_CALL_SPREAD', 'CREDIT_SPREAD']:
                         # Credit spread: we received premium, max loss is spread width minus credit
-                        max_loss = (spread_width * 100 * contracts) - total_cost
+                        max_loss = (spread_width * _pos_unit_multiplier(position) * contracts) - total_cost
                     else:
                         # Debit spread: we paid premium, max loss is what we paid
                         max_loss = total_cost
@@ -14749,8 +14753,8 @@ class PositionManager:
                 
                 if position_type == 'IRON_BUTTERFLY':
                     # Iron butterfly: short straddle + protective wings
-                    # Max loss = (wing_width * 100 * contracts) - credit
-                    max_loss = (wing_width * 100 * contracts) - total_cost
+                    # Max loss = (wing_width * unit_multiplier * contracts) - credit
+                    max_loss = (wing_width * _pos_unit_multiplier(position) * contracts) - total_cost
                     capital_at_risk += max(abs(max_loss) * 1.5, abs(total_cost) * 2)
                 else:
                     # Regular butterfly: max loss = net debit
@@ -14796,7 +14800,7 @@ class PositionManager:
                 
                 # Capital at risk = stock value (we own stock)
                 # Call premium reduces risk slightly
-                stock_value = underlying_price * contracts * 100
+                stock_value = underlying_price * contracts * _pos_unit_multiplier(position)
                 capital_at_risk += max(stock_value - call_premium, stock_value * 0.8)
                 locked_capital += stock_value
             
@@ -14806,7 +14810,7 @@ class PositionManager:
             elif position_type in ('LONG_STOCK', 'SHORT_STOCK'):
                 contracts = position.get('contracts', 1)
                 underlying_price = position.get('underlying_entry_price', 0)
-                stock_value = underlying_price * contracts * 100
+                stock_value = underlying_price * contracts * _pos_unit_multiplier(position)
                 capital_at_risk += stock_value
                 locked_capital += stock_value
             
@@ -14818,9 +14822,9 @@ class PositionManager:
                 strike = position.get('strike', 0)
                 credit = position.get('total_cost', 0)  # Premium received
                 
-                # Capital at risk = strike * 100 * contracts (cash secured)
+                # Capital at risk = strike * unit_multiplier * contracts (cash secured)
                 # We collected premium, so max loss is strike - premium
-                cash_secured = strike * 100 * contracts
+                cash_secured = strike * _pos_unit_multiplier(position) * contracts
                 max_loss = cash_secured - credit
                 capital_at_risk += max_loss
                 locked_capital += cash_secured
@@ -14862,7 +14866,7 @@ class PositionManager:
                 
                 if call_current is not None and put_current is not None:
                     # Current cost to close (what we'd pay to buy back)
-                    current_cost = (call_current['ask'] + put_current['ask']) * position['contracts'] * 100
+                    current_cost = (call_current['ask'] + put_current['ask']) * position['contracts'] * _pos_unit_multiplier(position)
                     
                     # Premium collected (baseline)
                     locked_capital += position['total_cost']
@@ -14958,7 +14962,8 @@ class PositionManager:
         
         Example usage:
             # In your strategy, when you find an entry signal:
-            cost_per_straddle = (call_bid + put_bid) * 100
+            mult = get_position_multiplier(config, preloaded)   # 100 equity, 50 ES, 50 soybeans, ...
+            cost_per_straddle = (call_bid + put_bid) * mult
             
             # Simple usage (no debug)
             sizing_info = position_mgr.calculate_position_size(
@@ -21052,17 +21057,17 @@ FUTURES_HEDGE_MAP = {
 
 
 # ─── Per-point P&L multipliers — special asset classes ──────────────────────
-# For most futures (ES, NQ, CL, GC, NG, RTY, YM, SI...), API contract_size
-# IS the per-point P&L multiplier. Two asset classes need a correction:
+# For most futures (ES, NQ, CL, GC, NG, RTY, YM, SI, CME FX...), API contract_size
+# IS the per-point P&L multiplier. Corrections:
 #
 #   bond futures: API contract_size = face value (e.g. ZB = 100_000),
 #                 per-point P&L multiplier = face_value / 100 = $1000/pt
 #                 (because price is quoted in percent of par)
+#   cents-quoted US commodities: contract_size / 100 (lumber / 1000), see _PRICE_UNIT_DIVISORS
+#   power and gas (MEGA_WATT_HOURS, THERMS): size depends on hours/days in the delivery
+#                 month, not derivable → ValueError, caller must set multiplier_override
 #
-#   FX futures:   API contract_size = base currency size (e.g. 6E = 125_000),
-#                 per-point P&L multiplier depends on tick size + quote
-#                 convention (varies per pair). We refuse to guess and emit
-#                 a warning — caller must set config['multiplier_override'].
+# CME FX: contract_size = $ per 1.0 move; crosses/USD-base (RY, AJY, CNH, KU) — P&L in quote currency
 # Bond futures: list includes both Globex codes (ZB/ZN/...) and the internal
 # CME `IVOL_symbol` codes the API actually returns (US/TY/FV/TU/UL/TN).
 # get_position_multiplier checks BOTH config['symbol'] and meta['root'] against
@@ -21071,11 +21076,46 @@ _BOND_FUTURES_ROOTS = frozenset({
     'ZB','ZN','ZF','ZT','UB','TN',   # Globex aliases used by traders
     'US','TY','FV','TU','UL',        # internal CME codes returned by API
 })
-# Same dual-alias treatment for FX futures.
-_FX_FUTURES_ROOTS = frozenset({
-    '6E','6J','6B','6A','6C','6N','6S','6M',  # Globex aliases
-    'EC','JY','BP','AD','CD','NE','SF','MP',  # internal CME codes
-})
+
+def _pos_unit_multiplier(position):
+    """$ per 1.0 of option/underlying price for one contract of this position (100 for equity and legacy positions)."""
+    try:
+        return float((position or {}).get('unit_multiplier') or 100.0)
+    except (TypeError, ValueError, AttributeError):
+        return 100.0
+
+
+# US commodities priced in cents (or $/cwt, $/1000 board feet) while API contract_size
+# is in physical units: per-point multiplier = contract_size / divisor.
+# MIC-gated because roots collide across exchanges (C = CBOT corn and ICE London cocoa).
+_ICE_US = {'IEPA', 'IFUS'}
+_PRICE_UNIT_DIVISORS = {
+    # CBOT grains, soybean oil, wheat spreads, soy crush — cents per bushel / per lb
+    'S': (100.0, {'XCBT'}), 'ZS': (100.0, {'XCBT'}),
+    'C': (100.0, {'XCBT'}), 'ZC': (100.0, {'XCBT'}),
+    'W': (100.0, {'XCBT'}), 'ZW': (100.0, {'XCBT'}),
+    'O': (100.0, {'XCBT'}), 'ZO': (100.0, {'XCBT'}),
+    'KW': (100.0, {'XCBT'}), 'HRS': (100.0, {'XCBT'}),
+    'BO': (100.0, {'XCBT'}), 'ZL': (100.0, {'XCBT'}),
+    'CKW': (100.0, {'XCBT'}), 'MCX': (100.0, {'XCBT'}), 'WMK': (100.0, {'XCBT'}),
+    'BCX': (100.0, {'XCBT'}),
+    # CME livestock and meat, cents per lb
+    'LC': (100.0, {'XCME'}), 'LE': (100.0, {'XCME'}),
+    'LH': (100.0, {'XCME'}), 'HE': (100.0, {'XCME'}),
+    'FC': (100.0, {'XCME'}), 'GF': (100.0, {'XCME'}),
+    'PRK': (100.0, {'XCME'}), 'PB': (100.0, {'XCME'}),
+    'BTF': (100.0, {'XCME'}), 'BTN': (100.0, {'XCME'}),
+    # CME dairy: milk in $ per cwt with contract_size in lb; butter, whey, NFDM in cents per lb
+    'DA': (100.0, {'XCME'}), 'DK': (100.0, {'XCME'}),
+    'CB': (100.0, {'XCME'}), 'DB': (100.0, {'XCME'}),
+    'DY': (100.0, {'XCME'}), 'NF': (100.0, {'XCME'}),
+    # CME lumber, $ per 1000 board feet with contract_size in board feet
+    'LBR': (1000.0, {'XCME'}), 'LB': (1000.0, {'XCME'}), 'SYP': (1000.0, {'XCME'}),
+    # ICE US softs and cash-settled grains, cents per lb / per bushel
+    'KC': (100.0, _ICE_US), 'SB': (100.0, _ICE_US), 'CT': (100.0, _ICE_US), 'OJ': (100.0, _ICE_US),
+    'SB1': (100.0, _ICE_US), 'SB2': (100.0, _ICE_US), 'CT1': (100.0, _ICE_US), 'CT2': (100.0, _ICE_US),
+    'IS': (100.0, _ICE_US), 'ICN': (100.0, _ICE_US), 'IW3': (100.0, _ICE_US), 'IBO': (100.0, _ICE_US),
+}
 
 # Non-US futures per-point P&L multiplier — used WHEN the API returns
 # contract_size=0 (which it does for every non-US root). Until iVol's backend
@@ -21087,12 +21127,19 @@ _FX_FUTURES_ROOTS = frozenset({
 # portfolio aggregation is a separate concern this table does not address.
 _NONUS_FUTURES_MULTIPLIERS = {
     'BRN':  1000.0,   # ICE Brent Crude   (NDEX/IFEU, USD)
+    'WAB-D': 1000.0,  # ICE Brent Crude Weekly options on BRN futures (NDEX, USD)
     'BE':   1000.0,   # EUREX Euro-Bund   (XDTB, EUR)
     'BL':   1000.0,   # EUREX Euro-Bobl   (XDTB, EUR)
     'BZ':   1000.0,   # EUREX Euro-Schatz (XDTB, EUR)
     'FBTP': 1000.0,   # EUREX Euro-BTP    (XDTB, EUR)
+    'MBT':  0.1,      # CME Micro Bitcoin (0.1 BTC)
+    'MET':  0.1,      # CME Micro Ether   (0.1 ETH)
+    'BFF':  0.02,     # CME Bitcoin Friday (1/50 BTC)
 }
 
+# Units where API contract_size is per hour / per day of delivery, not per contract.
+_PER_PERIOD_MEASURES = frozenset({'MEGA_WATT_HOURS', 'THERMS'})
+
 
 # ─── Universal options-root classifier ──────────────────────────────────────
 # Driven by the standardized description text inside `root_list` from
@@ -21267,6 +21314,26 @@ def resolve_opt_category_policy(config):
     return OPT_CATEGORY_POLICIES.get(policy, OPT_CATEGORY_POLICIES['tradable'])
 
 
+_OVERRIDE_WARNED = set()
+
+
+def _warn_override_mismatch(config, preloaded, override):
+    """Print once when a futures override is >10x off the resolved multiplier (e.g. a tick value used as multiplier)."""
+    if config.get('asset_type', 'equity') != 'futures' or not override:
+        return
+    try:
+        auto = get_position_multiplier({k: v for k, v in config.items() if k != 'multiplier_override'}, preloaded)
+    except ValueError:
+        return
+    if not auto or 0.1 <= override / auto <= 10:
+        return
+    key = (config.get('symbol'), override, auto)
+    if key not in _OVERRIDE_WARNED:
+        _OVERRIDE_WARNED.add(key)
+        print(f"   ⚠️  multiplier_override={override:g} for {config.get('symbol')} is >10x off the "
+              f"resolved multiplier {auto:g} ($ per 1.0 of price) — check the override.")
+
+
 def get_position_multiplier(config, preloaded=None):
     """Return the per-point P&L multiplier for a position.
 
@@ -21275,9 +21342,11 @@ def get_position_multiplier(config, preloaded=None):
       2. asset_type != 'futures'         → 100  (standard equity options)
       3. preloaded['_futures_meta']      → API-derived multiplier
            - bonds (ZB/ZN/ZF/ZT/UB/TN): contract_size / 100
-           - FX (6E/6J/...):  WARN + return 1.0 (force user to override)
-           - everything else: contract_size as-is
-      4. Fallback                         → 100
+           - US commodities priced in cents / $ per cwt / $ per 1000 bf
+             (see _PRICE_UNIT_DIVISORS): contract_size / divisor
+           - power / gas sized per hour or day (MEGA_WATT_HOURS, THERMS): ValueError
+           - everything else incl. CME FX: contract_size as-is
+      4. contract_size=0 (non-US, micro crypto) → _NONUS_FUTURES_MULTIPLIERS, else ValueError
 
     Args:
         config:    Strategy config dict (or None)
@@ -21292,7 +21361,10 @@ def get_position_multiplier(config, preloaded=None):
         ES (S&P futures, mult=50):         50.0
         CL (Crude Oil, mult=1000):       1000.0
         ZB (T-Bond, face=100_000):       1000.0   ← / 100 applied
-        6E (EUR/USD, no rule):              1.0   ← + warning, override needed
+        ZS (Soybeans, 5000 bu, cents):     50.0   ← / 100 applied
+        6E (EUR/USD, 125_000 EUR):     125000.0   ← price is USD per 1 EUR
+        MBT (Micro Bitcoin, size 0):        0.1   ← from _NONUS_FUTURES_MULTIPLIERS
+        TTF (1 MWh per hour):        ValueError   ← override needed
         config['multiplier_override']=42:  42     ← short-circuits everything
     """
     if config is None:
@@ -21302,9 +21374,12 @@ def get_position_multiplier(config, preloaded=None):
     override = config.get('multiplier_override')
     if override is not None:
         try:
-            return float(override)
+            override = float(override)
         except (TypeError, ValueError):
-            pass
+            override = None
+        if override is not None:
+            _warn_override_mismatch(config, preloaded, override)
+            return override
 
     # 2. Equity path
     if config.get('asset_type', 'equity') != 'futures':
@@ -21349,22 +21424,27 @@ def get_position_multiplier(config, preloaded=None):
     }
     candidate_roots.discard('')
     raw = float(meta['multiplier'])
+    mic = (meta.get('mic') or '').upper()
 
-    # Bond futures: contract_size is face value; per-point P&L = face / 100
-    if candidate_roots & _BOND_FUTURES_ROOTS:
+    # Bond futures (CBOT only — UB also names a NYMEX Brent swap): contract_size is face value
+    if candidate_roots & _BOND_FUTURES_ROOTS and (not mic or mic == 'XCBT'):
         return raw / 100.0
 
-    # FX futures: per-point multiplier depends on quote convention; we cannot
-    # derive it from contract_size alone. Warn loudly and return 1.0 so any
-    # P&L computed without an override is obviously wrong.
-    if candidate_roots & _FX_FUTURES_ROOTS:
-        which = sorted(candidate_roots & _FX_FUTURES_ROOTS)[0]
-        print(f"   ⚠️  get_position_multiplier: FX futures root {which!r} requires "
-              f"config['multiplier_override'] (contract_size={raw} is base-currency size, "
-              f"not per-point P&L multiplier). Returning 1.0 — fix your config.")
-        return 1.0
-
-    # Everything else (indices, commodities, metals, energies): contract_size IS multiplier
+    for root in sorted(candidate_roots):
+        spec = _PRICE_UNIT_DIVISORS.get(root)
+        if spec and (not mic or mic in spec[1]):
+            return raw / spec[0]
+
+    measure = (meta.get('measure') or '').upper()
+    if measure in _PER_PERIOD_MEASURES:
+        raise ValueError(
+            f"Futures per-point multiplier for {sorted(candidate_roots)} is not derivable: "
+            f"contract_size={raw} {measure} is per hour/day, the contract covers every "
+            "hour/day of the delivery month. Set config['multiplier_override'] "
+            "(e.g. TTF: MWh in the month = hours in the month)."
+        )
+
+    # Everything else (indices, dollar-priced commodities, metals, energies, CME FX): contract_size IS multiplier
     return raw
 
 
@@ -21650,7 +21730,11 @@ def _load_futures_for_hedge(config, preloaded):
 
     if meta and meta.get('multiplier'):
         exchange = meta.get('exchange') or (map_entry[1] if map_entry else '')
-        mult = meta['multiplier']
+        try:
+            mult = get_position_multiplier({'asset_type': 'futures', 'symbol': fut_root},
+                                           {'_futures_meta': meta})
+        except ValueError:
+            mult = meta['multiplier']
     elif map_entry:
         # API resolver failed — fall back to hardcoded map
         _, exchange, mult, _, _, _ = map_entry
@@ -23190,8 +23274,9 @@ def _preload_futures_to_duckdb(config, cache_config):
 
     # ── 5. ChunkManager on the futures_options_eod_close table ──────────────
     print(f"\n[3/3] 📊 Building OptionsChunkManager (futures_options_eod_close)")
-    dte_target = config.get('dte_target', 35)
-    dte_tolerance = config.get('dte_tolerance', 10)
+    # same defaults as the cache fast-path, so the first run serves the same chain as re-runs
+    dte_target = config.get('dte_target', 7)
+    dte_tolerance = config.get('dte_tolerance', 3)
     conn = _get_duckdb_storage_conn(cache_config)
     chunk_mgr = OptionsChunkManager(
         db_path=db_path,
@@ -31981,6 +32066,43 @@ class MarketDataManager:
 # PORTFOLIO-LEVEL FUNCTIONS (delta hedge + portfolio stop-loss)
 # ════════════════════════════════════════════════════════════════════════════════
 
+def _hedge_instrument_multiplier(config):
+    """(instrument, $ per 1.0 price move per hedge unit): stock → 1; futures → config / micro contract from FUTURES_HEDGE_MAP."""
+    config = config or {}
+    hedge_config = config.get('delta_hedge', {}) or {}
+    symbol = config.get('symbol', '')
+    instrument = hedge_config.get('instrument', 'auto')
+    if instrument == 'auto':
+        instrument = 'futures' if symbol in FUTURES_HEDGE_MAP else 'stock'
+    if instrument != 'futures':
+        return instrument, 1.0
+    if 'futures_multiplier' in hedge_config:
+        return instrument, float(hedge_config['futures_multiplier'])
+    if symbol in FUTURES_HEDGE_MAP:
+        return instrument, float(FUTURES_HEDGE_MAP[symbol][4])
+    return instrument, 1.0
+
+
+def get_hedge_multiplier(config):
+    """$ per 1.0 price move per hedge unit returned by check_portfolio_delta_hedge (1 for stock, 5 for SPX→MES)."""
+    return _hedge_instrument_multiplier(config)[1]
+
+
+_HEDGE_MULT_WARNED = set()
+
+
+def _warn_hedge_multiplier_default(config):
+    """Print once when a futures hedge is valued with the default hedge_multiplier=1.0."""
+    instrument, mult = _hedge_instrument_multiplier(config)
+    symbol = (config or {}).get('symbol')
+    if instrument != 'futures' or mult == 1.0 or symbol in _HEDGE_MULT_WARNED:
+        return
+    _HEDGE_MULT_WARNED.add(symbol)
+    print(f"   ⚠️  check_portfolio_stop_loss: {symbol} is hedged with futures (${mult:g} per point per contract) "
+          f"but hedge_multiplier=1.0 — pass hedge_multiplier=get_hedge_multiplier(config) "
+          f"when cycle_hedge_pnl is the sum of action['cash_flow'].")
+
+
 def check_portfolio_delta_hedge(position_managers, options_today, get_option_func,
                                  current_hedge_shares, config, stock_row=None):
     """
@@ -32008,8 +32130,13 @@ def check_portfolio_delta_hedge(position_managers, options_today, get_option_fun
     Returns:
         dict or None. If rebalance needed:
             {'action': 'BUY'/'SELL', 'shares_diff': int, 'price': float,
+             'cash_flow': float,  # -shares_diff * price * hedge_multiplier, in $
              'target_shares': int, 'net_position_delta': float,
-             'position_deltas': list, 'stock_bid': float, 'stock_ask': float}
+             'position_deltas': list, 'stock_bid': float, 'stock_ask': float,
+             'instrument': 'stock'/'futures', 'hedge_multiplier': float}
+        shares_diff is in hedge units of hedge_multiplier $ per point: shares for stock,
+        micro futures contracts for SPX/NDX/RUT/DJX ($5/$2/$5/$0.5), futures contracts with
+        delta_hedge['futures_multiplier'], otherwise $1-per-point units.
     """
     hedge_config = config.get('delta_hedge', {})
     if not hedge_config.get('enabled', False):
@@ -32019,24 +32146,8 @@ def check_portfolio_delta_hedge(position_managers, options_today, get_option_fun
     threshold_min = int(hedge_config.get('rebalance_threshold_min', 5))
     use_bid_ask = hedge_config.get('use_bid_ask', True)
 
-    # Determine hedge instrument: stock (multiplier=1) or futures (multiplier from map/config).
     # For futures: notebook is responsible for passing futures price data as stock_row.
-    symbol = config.get('symbol', '')
-    instrument = hedge_config.get('instrument', 'auto')
-    if instrument == 'auto':
-        instrument = 'futures' if symbol in FUTURES_HEDGE_MAP else 'stock'
-
-    if instrument == 'futures':
-        if 'futures_multiplier' in hedge_config:
-            hedge_multiplier = float(hedge_config['futures_multiplier'])
-        elif symbol in FUTURES_HEDGE_MAP:
-            # Default to MICRO futures (smaller granularity for finer hedging)
-            _, _, _, _, micro_mult, _ = FUTURES_HEDGE_MAP[symbol]
-            hedge_multiplier = float(micro_mult)
-        else:
-            hedge_multiplier = 1.0
-    else:
-        hedge_multiplier = 1.0  # stock: 1 share = 1 delta
+    instrument, hedge_multiplier = _hedge_instrument_multiplier(config)
 
     if not isinstance(position_managers, (list, tuple)):
         position_managers = [position_managers]
@@ -32085,7 +32196,8 @@ def check_portfolio_delta_hedge(position_managers, options_today, get_option_fun
             else:
                 current_delta = float(option_data['delta'])
 
-            pos_delta = -current_delta * 100 * contracts if is_short else current_delta * 100 * contracts
+            _um = _pos_unit_multiplier(pos)
+            pos_delta = -current_delta * _um * contracts if is_short else current_delta * _um * contracts
             position_deltas.append({
                 'position_id': pos_id, 'strategy_type': strategy_type,
                 'opt_type': opt_type, 'strike': strike, 'current_delta': current_delta,
@@ -32110,6 +32222,7 @@ def check_portfolio_delta_hedge(position_managers, options_today, get_option_fun
         'action': 'BUY' if diff > 0 else 'SELL',
         'shares_diff': diff,                    # shares (stock) or contracts (futures)
         'price': price,
+        'cash_flow': -diff * price * hedge_multiplier,
         'target_shares': target_units,          # kept name for stock backward-compat
         'current_hedge_shares': current_hedge_shares,
         'net_position_delta': round(net_position_delta, 2),
@@ -32122,10 +32235,14 @@ def check_portfolio_delta_hedge(position_managers, options_today, get_option_fun
 
 def check_portfolio_stop_loss(position_managers, options_today, get_option_func,
                               config, stock_row=None, extra_pnl=0.0,
-                              hedge_shares=0, cycle_hedge_pnl=0.0):
+                              hedge_shares=0, cycle_hedge_pnl=0.0,
+                              hedge_multiplier=1.0):
     """
     Portfolio-level stop loss. Sums unrealized P&L across ALL open positions
-    in ALL PositionManagers + extra_pnl (e.g., hedge rebalance cash flow).
+    in ALL PositionManagers + open hedge + extra_pnl (other off-book P&L, not the hedge).
+
+    Hedge: cycle_hedge_pnl = sum of action['cash_flow'] ($), hedge_shares in hedge units,
+    hedge_multiplier = get_hedge_multiplier(config) (5 for SPX→MES; default 1.0 = shares).
 
     Config:
         'portfolio_stop_loss': {
@@ -32233,15 +32350,17 @@ def check_portfolio_stop_loss(position_managers, options_today, get_option_func,
                 ask = float(option_data.get('ask', 0) or 0)
                 close_price = ask if is_short else bid
                 if is_short:
-                    options_unrealized += abs(total_cost) - (close_price * 100 * contracts)
+                    options_unrealized += abs(total_cost) - (close_price * _pos_unit_multiplier(pos) * contracts)
                 else:
-                    options_unrealized += (close_price * 100 * contracts) - abs(total_cost)
+                    options_unrealized += (close_price * _pos_unit_multiplier(pos) * contracts) - abs(total_cost)
 
     if total_allocated == 0:
         return None
 
-    # Hedge P&L: realized (cycle_hedge_pnl) + unrealized (hedge_shares * stock_mid)
-    hedge_unrealized = cycle_hedge_pnl + hedge_shares * stock_mid if hedge_shares else 0.0
+    # cycle_hedge_pnl must be in the same units as hedge_multiplier: pass get_hedge_multiplier(config) with $ cash flows
+    if hedge_shares and hedge_multiplier == 1.0:
+        _warn_hedge_multiplier_default(config)
+    hedge_unrealized = cycle_hedge_pnl + (hedge_shares * stock_mid * hedge_multiplier if hedge_shares else 0.0)
     combined_pnl = options_unrealized + stock_unrealized + extra_pnl + hedge_unrealized
     combined_pnl_pct = combined_pnl / total_allocated
 

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/ivolatility_backtesting.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 2.146
+Version: 2.147
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/ivolatility_backtesting.egg-info/SOURCES.txt

@@ -10,4 +10,5 @@ ivolatility_backtesting.egg-info/requires.txt
 ivolatility_backtesting.egg-info/top_level.txt
 tests/test_2142_fixes.py
 tests/test_2144_duckdb_dedup.py
-tests/test_2146_vix_vro.py
+tests/test_2146_vix_vro.py
+tests/test_2147_cents_multiplier.py

{ivolatility_backtesting-2.146 → ivolatility_backtesting-2.147}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ivolatility_backtesting"
-version = "2.146"
+version = "2.147"
 description = "A universal backtesting framework for financial strategies using the IVolatility API."
 readme = "README.md"
 authors = [

ivolatility_backtesting-2.147/tests/test_2147_cents_multiplier.py

@@ -0,0 +1,305 @@
+# Per-point multiplier for US commodities priced in cents; contract_size is in physical units.
+# Run: python3 tests/test_2147_cents_multiplier.py  (or pytest)
+import os
+import sys
+import traceback
+
+import matplotlib
+matplotlib.use('Agg')
+
+_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(_REPO, 'ivolatility_backtesting'))
+import ivolatility_backtesting as lib  # noqa: E402
+
+
+import pandas as pd  # noqa: E402
+
+
+def _mult(symbol, contract_size, root=None, mic='', measure=''):
+    config = {'asset_type': 'futures', 'symbol': symbol}
+    meta = {'multiplier': contract_size, 'root': root or symbol, 'mic': mic, 'measure': measure}
+    return lib.get_position_multiplier(config, {'_futures_meta': meta})
+
+
+class _PM:
+    def __init__(self, positions):
+        self._positions = positions
+
+    def get_open_positions(self):
+        return self._positions
+
+
+def test_cents_quoted_grains_divide_by_100():
+    # API contract_size / MIC as returned by /futures/eod/fut-underlying-info
+    assert _mult('S', 5000.0, mic='XCBT') == 50.0
+    assert _mult('C', 5000.0, mic='XCBT') == 50.0
+    assert _mult('W', 5000.0, mic='XCBT') == 50.0
+    assert _mult('O', 5000.0, mic='XCBT') == 50.0
+    assert _mult('BO', 60000.0, mic='XCBT') == 600.0
+
+
+def test_globex_alias_resolves_through_internal_root():
+    assert _mult('ZS', 5000.0, root='S', mic='XCBT') == 50.0
+    assert _mult('ZL', 60000.0, root='BO', mic='XCBT') == 600.0
+    assert _mult('LE', 40000.0, root='LC', mic='XCME') == 400.0
+
+
+def test_livestock_milk_softs_lumber():
+    assert _mult('LC', 40000.0, mic='XCME') == 400.0
+    assert _mult('LH', 40000.0, mic='XCME') == 400.0
+    assert _mult('FC', 50000.0, mic='XCME') == 500.0
+    assert _mult('DA', 200000.0, mic='XCME') == 2000.0
+    assert _mult('KC', 37500.0, mic='IEPA') == 375.0
+    assert _mult('SB', 112000.0, mic='IEPA') == 1120.0
+    assert _mult('CT', 50000.0, mic='IEPA') == 500.0
+    assert _mult('LBR', 27500.0, mic='XCME') == 27.5
+
+
+def test_same_root_on_other_exchange_is_untouched():
+    # C / W / CT also exist on ICE London (XNLI) — must not be rescaled
+    assert _mult('C', 5000.0, mic='XNLI') == 5000.0
+    assert _mult('W', 5000.0, mic='XNLI') == 5000.0
+    assert _mult('CT', 50000.0, mic='XNLI') == 50000.0
+
+
+def test_dollar_priced_and_bonds_unchanged():
+    assert _mult('ES', 50.0, mic='XCME') == 50.0
+    assert _mult('CL', 1000.0, mic='XNYM') == 1000.0
+    assert _mult('GC', 100.0, mic='XCEC') == 100.0
+    assert _mult('SM', 100.0, mic='XCBT') == 100.0
+    assert _mult('RR', 2000.0, mic='XCBT') == 2000.0
+    assert _mult('CC', 10.0, mic='IEPA') == 10.0
+    assert _mult('ZB', 100000.0, root='US', mic='XCBT') == 1000.0
+
+
+def test_extended_cent_priced_roots():
+    assert _mult('KW', 5000.0, mic='XCBT') == 50.0
+    assert _mult('HRS', 5000.0, mic='XCBT') == 50.0
+    assert _mult('CKW', 5000.0, mic='XCBT') == 50.0
+    assert _mult('BCX', 50000.0, mic='XCBT') == 500.0
+    assert _mult('PRK', 40000.0, mic='XCME') == 400.0
+    assert _mult('BTN', 20000.0, mic='XCME') == 200.0
+    assert _mult('DK', 200000.0, mic='XCME') == 2000.0
+    assert _mult('CB', 20000.0, mic='XCME') == 200.0
+    assert _mult('NF', 44000.0, mic='XCME') == 440.0
+    assert _mult('SYP', 22000.0, mic='XCME') == 22.0
+    assert _mult('LB', 110000.0, mic='XCME') == 110.0
+    assert _mult('OJ', 15000.0, mic='IEPA') == 150.0
+    assert _mult('IS', 5000.0, mic='IEPA') == 50.0
+
+
+def test_colliding_symbols_on_other_exchanges_untouched():
+    # KW on CME, IS on NYMEX (natural gas index), SB1 on NYMEX (WTI-Brent) are other products
+    assert _mult('KW', 5000.0, mic='XCME') == 5000.0
+    assert _mult('IS', 2500.0, mic='XNYM') == 2500.0
+    assert _mult('SB1', 1000.0, mic='XNYM') == 1000.0
+
+
+def test_dollar_priced_dairy_metals_rates_unchanged():
+    assert _mult('CSC1', 20000.0, mic='XCME') == 20000.0
+    assert _mult('BLK', 20000.0, mic='XCME') == 20000.0
+    assert _mult('JQ', 1000.0, mic='XCME') == 1000.0
+    assert _mult('AL', 44000.0, mic='XCEC') == 44000.0
+    assert _mult('COB', 2204.0, mic='XCEC') == 2204.0
+    assert _mult('SR3', 2500.0, mic='XCME') == 2500.0
+    assert _mult('ED', 2500.0, mic='XCME') == 2500.0
+    assert _mult('TU', 200000.0, mic='XCBT') == 2000.0
+
+
+def test_override_still_wins():
+    config = {'asset_type': 'futures', 'symbol': 'S', 'multiplier_override': 42}
+    meta = {'multiplier': 5000.0, 'root': 'S', 'mic': 'XCBT'}
+    assert lib.get_position_multiplier(config, {'_futures_meta': meta}) == 42.0
+
+
+def test_cme_fx_uses_contract_size():
+    # quoted in USD per 1 unit of foreign currency: EC 1.14, JY 0.0063
+    assert _mult('6E', 125000.0, root='EC', mic='XCME', measure='CURRENCY') == 125000.0
+    assert _mult('JY', 12500000.0, mic='XCME', measure='CURRENCY') == 12500000.0
+    assert _mult('MP', 500000.0, mic='XCME', measure='CURRENCY') == 500000.0
+    assert _mult('SR3', 2500.0, mic='XCME', measure='CURRENCY') == 2500.0
+
+
+def test_power_and_gas_require_override():
+    for sym, size, measure in (('TTF', 1.0, 'MEGA_WATT_HOURS'), ('UKG', 1000.0, 'THERMS')):
+        try:
+            _mult(sym, size, mic='XNYM', measure=measure)
+        except ValueError as e:
+            assert 'multiplier_override' in str(e)
+        else:
+            raise AssertionError(f'{sym}: expected ValueError')
+    config = {'asset_type': 'futures', 'symbol': 'TTF', 'multiplier_override': 720}
+    meta = {'multiplier': 1.0, 'root': 'TTF', 'mic': 'XNYM', 'measure': 'MEGA_WATT_HOURS'}
+    assert lib.get_position_multiplier(config, {'_futures_meta': meta}) == 720.0
+
+
+def test_micro_crypto_zero_contract_size():
+    assert _mult('MBT', 0.0, mic='XCME', measure='BITCOIN') == 0.1
+    assert _mult('MET', 0.0, mic='XCME', measure='ETHER') == 0.1
+    assert _mult('BFF', 0.0, mic='XCME', measure='BITCOIN') == 0.02
+    assert _mult('BTC', 5.0, mic='XCME', measure='BITCOIN') == 5.0
+
+
+def test_bond_rule_only_on_cbot():
+    assert _mult('UB', 100000.0, root='UL', mic='XCBT', measure='CURRENCY') == 1000.0
+    assert _mult('ZT', 200000.0, root='TU', mic='XCBT', measure='CURRENCY') == 2000.0
+    assert _mult('UB', 1000.0, mic='XNYM', measure='BARRELS') == 1000.0   # NYMEX Brent swap named UB
+
+
+def test_futures_hedge_default_multiplier_warns_once():
+    import contextlib
+    import io
+    pos = {'strategy_type': 'LONG_CALL', 'contracts': 1, 'strike': 5000.0, 'expiration': '2026-11-20',
+           'total_cost': 1000.0, 'entry_max_risk': 1000.0}
+    cfg = {'symbol': 'NDX', 'delta_hedge': {'enabled': True},
+           'portfolio_stop_loss': {'enabled': True, 'value': -0.10}}
+    row = pd.DataFrame([{'close': 5000.0, 'bid': 5000.0, 'ask': 5000.0}])
+    get_opt = lambda s, e, t: {'bid': 5.0, 'ask': 5.2}  # noqa: E731
+    lib._HEDGE_MULT_WARNED.discard('NDX')
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        for _ in range(2):
+            lib.check_portfolio_stop_loss([_PM([pos])], None, get_opt, cfg, row, hedge_shares=-2, cycle_hedge_pnl=0.0)
+    assert buf.getvalue().count('hedge_multiplier=get_hedge_multiplier(config)') == 1
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        lib.check_portfolio_stop_loss([_PM([pos])], None, get_opt, {**cfg, 'symbol': 'SPY'}, row,
+                                      hedge_shares=-2, cycle_hedge_pnl=0.0)
+    assert 'hedge_multiplier' not in buf.getvalue()
+
+
+def test_brent_roots():
+    assert _mult('BRN', 0.0, mic='NDEX') == 1000.0
+    assert _mult('WAB-D', 0.0, mic='NDEX') == 1000.0
+    assert _mult('BZ', 1000.0, root='BZ1', mic='XNYM', measure='BARRELS') == 1000.0
+    assert _mult('ZO', 1000.0, mic='XNYM', measure='BARRELS') == 1000.0
+
+
+def test_pos_unit_multiplier_fallbacks():
+    assert lib._pos_unit_multiplier({'unit_multiplier': 50.0}) == 50.0
+    assert lib._pos_unit_multiplier({'unit_multiplier': None}) == 100.0
+    assert lib._pos_unit_multiplier({}) == 100.0
+    assert lib._pos_unit_multiplier(None) == 100.0
+    assert lib._pos_unit_multiplier({'unit_multiplier': 'x'}) == 100.0
+
+
+def test_calculate_risk_uses_unit_multiplier():
+    ic = {'strategy_type': 'IRON_CONDOR', 'contracts': 1, 'total_cost': -200.0, 'wing_width': 10}
+    assert lib.StrategyRegistry.calculate_risk(ic)[0] == 1200.0          # (10*100-200)*1.5
+    assert lib.StrategyRegistry.calculate_risk({**ic, 'unit_multiplier': 50.0})[0] == 450.0
+    cc = {'strategy_type': 'COVERED_CALL', 'contracts': 2, 'total_cost': -300.0,
+          'underlying_entry_price': 100.0, 'call_premium': 300.0}
+    assert lib.StrategyRegistry.calculate_risk(cc) == (19700.0, 20000.0)
+    assert lib.StrategyRegistry.calculate_risk({**cc, 'unit_multiplier': 50.0}) == (9700.0, 10000.0)
+
+
+def test_hedge_instrument_multiplier():
+    assert lib._hedge_instrument_multiplier({'symbol': 'SPX', 'delta_hedge': {'enabled': True}}) == ('futures', 5.0)
+    assert lib._hedge_instrument_multiplier({'symbol': 'SPY', 'delta_hedge': {'enabled': True}}) == ('stock', 1.0)
+    cfg = {'symbol': 'SPX', 'delta_hedge': {'enabled': True, 'futures_multiplier': 50}}
+    assert lib._hedge_instrument_multiplier(cfg) == ('futures', 50.0)
+
+
+def test_delta_hedge_futures_option_units():
+    # 2 long soybean calls, delta 0.5, $50 per 1 cent → $50 per cent of exposure → -50 units
+    pos = {'id': 'p1', 'strategy_type': 'LONG_CALL', 'contracts': 2, 'strike': 1000.0,
+           'expiration': '2026-11-20', 'unit_multiplier': 50.0}
+    cfg = {'symbol': 'S', 'asset_type': 'futures',
+           'delta_hedge': {'enabled': True, 'rebalance_threshold_min': 1,
+                           'rebalance_threshold_pct': 0.0, 'use_bid_ask': False}}
+    a = lib.check_portfolio_delta_hedge([_PM([pos])], None, lambda s, e, t: {'delta': 0.5}, 0, cfg)
+    assert a['target_shares'] == -50 and a['hedge_multiplier'] == 1.0
+
+
+def test_delta_hedge_spx_micro_futures_cash_flow():
+    pos = {'id': 'p1', 'strategy_type': 'LONG_CALL', 'contracts': 1, 'strike': 5000.0,
+           'expiration': '2026-11-20'}
+    cfg = {'symbol': 'SPX', 'delta_hedge': {'enabled': True, 'rebalance_threshold_min': 1,
+                                            'rebalance_threshold_pct': 0.0, 'use_bid_ask': False}}
+    row = pd.DataFrame([{'close': 5000.0, 'bid': 5000.0, 'ask': 5000.0}])
+    a = lib.check_portfolio_delta_hedge([_PM([pos])], None, lambda s, e, t: {'delta': 0.5}, 0, cfg, row)
+    assert a['instrument'] == 'futures' and a['hedge_multiplier'] == 5.0
+    assert a['shares_diff'] == -10                      # 0.5 * 100 * 1 / 5 MES
+    assert a['cash_flow'] == 10 * 5000.0 * 5.0
+
+
+def test_portfolio_stop_hedge_valued_per_contract():
+    pos = {'strategy_type': 'LONG_CALL', 'contracts': 1, 'strike': 5000.0, 'expiration': '2026-11-20',
+           'total_cost': 1000.0, 'entry_max_risk': 1000.0}
+    cfg = {'symbol': 'SPX', 'delta_hedge': {'enabled': True},
+           'portfolio_stop_loss': {'enabled': True, 'value': -0.10}}
+    row = pd.DataFrame([{'close': 5000.0, 'bid': 5000.0, 'ask': 5000.0}])
+    get_opt = lambda s, e, t: {'bid': 5.0, 'ask': 5.2}  # noqa: E731
+    hm = lib.get_hedge_multiplier(cfg)
+    assert hm == 5.0
+    # short 2 MES sold at 5000, price unchanged → hedge P&L 0, options -500
+    r = lib.check_portfolio_stop_loss([_PM([pos])], None, get_opt, cfg, row,
+                                      hedge_shares=-2, cycle_hedge_pnl=2 * 5000.0 * 5.0,
+                                      hedge_multiplier=hm)
+    assert r['hedge_unrealized'] == 0.0 and r['combined_pnl'] == -500.0
+    # realized hedge P&L kept when the hedge is flat
+    r = lib.check_portfolio_stop_loss([_PM([pos])], None, get_opt, cfg, row,
+                                      hedge_shares=0, cycle_hedge_pnl=-300.0)
+    assert r['hedge_unrealized'] == -300.0 and r['combined_pnl'] == -800.0
+
+
+def test_portfolio_stop_legacy_caller_unchanged():
+    # legacy caller: cash_flow = -diff * price without multiplier, no hedge_multiplier kwarg
+    pos = {'strategy_type': 'LONG_CALL', 'contracts': 1, 'strike': 5000.0, 'expiration': '2026-11-20',
+           'total_cost': 1000.0, 'entry_max_risk': 1000.0}
+    cfg = {'symbol': 'SPX', 'delta_hedge': {'enabled': True},
+           'portfolio_stop_loss': {'enabled': True, 'value': -0.10}}
+    row = pd.DataFrame([{'close': 5000.0, 'bid': 5000.0, 'ask': 5000.0}])
+    r = lib.check_portfolio_stop_loss([_PM([pos])], None, lambda s, e, t: {'bid': 5.0, 'ask': 5.2}, cfg, row,
+                                      hedge_shares=-60, cycle_hedge_pnl=60 * 5000.0)
+    assert r['hedge_unrealized'] == 0.0
+
+
+def test_stop_loss_manager_gets_unit_multiplier():
+    cfg = {'asset_type': 'futures', 'symbol': 'ES', 'multiplier_override': 50,
+           'stop_loss_enabled': True, 'stop_loss_config': {'type': 'pl_loss', 'value': 0.5}}
+    pm = lib.PositionManager(cfg, debug=False)
+    pm.open_position(position_id='p1', strategy_type='LONG_CALL', symbol='ES',
+                     entry_date=pd.Timestamp('2025-01-02'), entry_price=2000.0, quantity=50, contracts=1,
+                     total_cost=2000.0, strike=6000.0, expiration=pd.Timestamp('2025-02-21'),
+                     is_short_bias=False, underlying_entry_price=6000.0)
+    assert pm.positions['p1']['unit_multiplier'] == 50.0
+    assert pm.sl_manager.positions['p1']['unit_multiplier'] == 50.0
+
+
+def test_override_far_off_resolved_multiplier_warns_once():
+    import contextlib
+    import io
+    config = {'asset_type': 'futures', 'symbol': '6E', 'multiplier_override': 12.5}
+    pre = {'_futures_meta': {'multiplier': 125000.0, 'root': 'EC', 'mic': 'XCME', 'measure': 'CURRENCY'}}
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        assert lib.get_position_multiplier(config, pre) == 12.5
+        assert lib.get_position_multiplier(config, pre) == 12.5
+    assert buf.getvalue().count('multiplier_override=12.5') == 1
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        assert lib.get_position_multiplier({**config, 'multiplier_override': 125000}, pre) == 125000.0
+    assert 'multiplier_override' not in buf.getvalue()
+
+
+def test_futures_option_premium_and_stop_values():
+    pos = {'strategy_type': 'LONG_CALL', 'contracts': 2, 'strike': 1000.0, 'expiration': '2026-11-20',
+           'total_cost': 2000.0, 'entry_max_risk': 2000.0, 'unit_multiplier': 50.0}
+    cfg = {'symbol': 'S', 'asset_type': 'futures', 'portfolio_stop_loss': {'enabled': True, 'value': -0.10}}
+    r = lib.check_portfolio_stop_loss([_PM([pos])], None, lambda s, e, t: {'bid': 10.0, 'ask': 10.5}, cfg)
+    assert r['options_unrealized'] == 10.0 * 50.0 * 2 - 2000.0
+
+
+if __name__ == '__main__':
+    failed = 0
+    for name, fn in sorted((n, f) for n, f in globals().items() if n.startswith('test_') and callable(f)):
+        try:
+            fn()
+            print(f'PASS {name}')
+        except Exception:
+            failed += 1
+            print(f'FAIL {name}')
+            traceback.print_exc()
+    print(f'{failed} failed')
+    sys.exit(1 if failed else 0)