Merge pull request #974 from Lumiwealth/version/4.4.54

v4.4.54 - Per-contract trading fee accounting

Author: grzesir

CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## 4.4.54 - Unreleased
+## 4.4.54 - 2026-03-08
+
+### Added
+- `TradingFee` now supports `per_contract_fee` for broker-style option commissions charged per contract.
+- Regression tests for `per_contract_fee` initialization and trade-cost calculations in backtesting.
+
+### Changed
+- `TradingFee` fee fields now coerce through `Decimal(str(...))` for stable decimal handling across float inputs.
+
+### Fixed
+- Backtesting trade-cost calculations now apply `per_contract_fee * quantity` for taker and maker fee paths (`market`, `stop`, `limit`, `stop_limit`, `smart_limit`).
 
 ## 4.4.53 - 2026-03-06
 

lumibot/backtesting/backtesting_broker.py

@@ -1869,9 +1869,11 @@ def calculate_trade_cost(self, order: Order, strategy, price: float):
             if trading_fee.taker is True and order_type_value in {"market", "stop"}:
                 trade_cost += trading_fee.flat_fee
                 trade_cost += Decimal(str(price)) * Decimal(str(order.quantity)) * trading_fee.percent_fee
+                trade_cost += Decimal(str(order.quantity)) * trading_fee.per_contract_fee
             elif trading_fee.maker is True and order_type_value in {"limit", "stop_limit", "smart_limit"}:
                 trade_cost += trading_fee.flat_fee
                 trade_cost += Decimal(str(price)) * Decimal(str(order.quantity)) * trading_fee.percent_fee
+                trade_cost += Decimal(str(order.quantity)) * trading_fee.per_contract_fee
 
         return trade_cost
 

lumibot/entities/trading_fee.py

@@ -4,14 +4,18 @@
 class TradingFee:
     """TradingFee class. Used to define the trading fees for a broker in a strategy/backtesting."""
 
-    def __init__(self, flat_fee=0.0, percent_fee=0.0, maker=True, taker=True):
+    def __init__(self, flat_fee=0.0, percent_fee=0.0, per_contract_fee=0.0, maker=True, taker=True):
         """
         Parameters
         ----------
         flat_fee : Decimal, float, or None
             Flat fee to pay for each order. This is a fixed fee that is paid for each order in the quote currency.
         percent_fee : Decimal, float, or None
             Percentage fee to pay for each order. This is a percentage of the order value that is paid for each order in the quote currency.
+        per_contract_fee : Decimal, float, or None
+            Fee charged per contract (multiplied by order quantity). Useful for options commissions
+            where brokers charge per contract (e.g., $0.65/contract). For a 40-contract order with
+            per_contract_fee=0.65, the total fee would be $26.00.
         maker : bool
             Whether this fee is a maker fee (applies to limit orders).
             Default is True, which means that this fee will be used on limit orders.
@@ -28,8 +32,9 @@ def __init__(self, flat_fee=0.0, percent_fee=0.0, maker=True, taker=True):
         >>> class MyStrategy(Strategy):
         >>>     pass
         >>>
-        >>> trading_fee_1 = TradingFee(flat_fee=5.2) # $5.20 flat fee
+        >>> trading_fee_1 = TradingFee(flat_fee=5.2) # $5.20 flat fee per order
         >>> trading_fee_2 = TradingFee(percent_fee=0.01) # 1% fee
+        >>> trading_fee_3 = TradingFee(per_contract_fee=0.65) # $0.65 per contract
         >>> backtesting_start = datetime(2022, 1, 1)
         >>> backtesting_end = datetime(2022, 6, 1)
         >>> result = MyStrategy.backtest(
@@ -39,7 +44,8 @@ def __init__(self, flat_fee=0.0, percent_fee=0.0, maker=True, taker=True):
         >>>     buy_trading_fees=[trading_fee_1, trading_fee_2],
         >>> )
         """
-        self.flat_fee = Decimal(flat_fee)
-        self.percent_fee = Decimal(percent_fee)
+        self.flat_fee = Decimal(str(flat_fee))
+        self.percent_fee = Decimal(str(percent_fee))
+        self.per_contract_fee = Decimal(str(per_contract_fee))
         self.maker = maker
         self.taker = taker

tests/test_tradingfee.py

@@ -1,11 +1,97 @@
+from decimal import Decimal
+from unittest.mock import MagicMock
+
 from lumibot.entities import TradingFee, TradingSlippage
 
 
 class TestTradingFee:
     def test_init(self):
         fee = TradingFee(flat_fee=5.2)
-        assert fee.flat_fee == 5.2
+        assert fee.flat_fee == Decimal("5.2")
+
+    def test_per_contract_fee_init(self):
+        fee = TradingFee(per_contract_fee=0.65)
+        assert fee.per_contract_fee == Decimal("0.65")
+        assert fee.flat_fee == Decimal("0")
+        assert fee.percent_fee == Decimal("0")
+
+    def test_per_contract_fee_default_zero(self):
+        fee = TradingFee(flat_fee=1.0)
+        assert fee.per_contract_fee == Decimal("0")
+
+    def test_per_contract_fee_with_flat_fee(self):
+        fee = TradingFee(flat_fee=5.0, per_contract_fee=0.65)
+        assert fee.flat_fee == Decimal("5.0")
+        assert fee.per_contract_fee == Decimal("0.65")
 
     def test_slippage_init(self):
         slippage = TradingSlippage(amount=0.15)
         assert slippage.amount == 0.15
+
+
+class TestPerContractFeeCalculation:
+    """Test that per_contract_fee is correctly multiplied by order quantity in calculate_trade_cost."""
+
+    def _make_order(self, side="sell_to_open", order_type="market", quantity=40):
+        order = MagicMock()
+        order.side = side
+        order.order_type = MagicMock()
+        order.order_type.value = order_type
+        order.quantity = quantity
+        return order
+
+    def _make_strategy(self, buy_fees=None, sell_fees=None):
+        strategy = MagicMock()
+        strategy.buy_trading_fees = buy_fees or []
+        strategy.sell_trading_fees = sell_fees or []
+        return strategy
+
+    def test_per_contract_fee_multiplied_by_quantity(self):
+        """$0.65/contract on a 40-contract order should cost $26.00."""
+        from lumibot.backtesting.backtesting_broker import BacktestingBroker
+
+        broker = BacktestingBroker.__new__(BacktestingBroker)
+        fee = TradingFee(per_contract_fee=0.65)
+        order = self._make_order(side="sell_to_open", order_type="market", quantity=40)
+        strategy = self._make_strategy(sell_fees=[fee])
+
+        cost = broker.calculate_trade_cost(order, strategy, price=1.50)
+        assert cost == Decimal("26.00")
+
+    def test_per_contract_fee_with_flat_fee(self):
+        """Both flat_fee and per_contract_fee should apply."""
+        from lumibot.backtesting.backtesting_broker import BacktestingBroker
+
+        broker = BacktestingBroker.__new__(BacktestingBroker)
+        fee = TradingFee(flat_fee=5.0, per_contract_fee=0.65)
+        order = self._make_order(side="buy_to_open", order_type="market", quantity=10)
+        strategy = self._make_strategy(buy_fees=[fee])
+
+        cost = broker.calculate_trade_cost(order, strategy, price=2.00)
+        # flat_fee=5.0 + per_contract=10*0.65=6.50 + percent=0 = 11.50
+        assert cost == Decimal("11.50")
+
+    def test_per_contract_fee_on_limit_order(self):
+        """Per-contract fee should work with limit/smart_limit orders too."""
+        from lumibot.backtesting.backtesting_broker import BacktestingBroker
+
+        broker = BacktestingBroker.__new__(BacktestingBroker)
+        fee = TradingFee(per_contract_fee=0.65)
+        order = self._make_order(side="sell_to_open", order_type="smart_limit", quantity=20)
+        strategy = self._make_strategy(sell_fees=[fee])
+
+        cost = broker.calculate_trade_cost(order, strategy, price=3.00)
+        assert cost == Decimal("13.00")  # 20 * 0.65
+
+    def test_old_flat_fee_behavior_unchanged(self):
+        """Existing flat_fee behavior should NOT change (still per-order, not per-contract)."""
+        from lumibot.backtesting.backtesting_broker import BacktestingBroker
+
+        broker = BacktestingBroker.__new__(BacktestingBroker)
+        fee = TradingFee(flat_fee=0.65)
+        order = self._make_order(side="sell_to_open", order_type="market", quantity=40)
+        strategy = self._make_strategy(sell_fees=[fee])
+
+        cost = broker.calculate_trade_cost(order, strategy, price=1.50)
+        # flat_fee is per-order, so $0.65 regardless of quantity
+        assert cost == Decimal("0.65")