fix: support BNFCR alternative collateral in CryptoFutureMarginModel for Binance (#9373)

Romazes · web-flow · commit 9b2a793709e0 · 2026-04-13T23:24:40.000+03:00
* fix: support BNFCR alternative collateral in CryptoFutureMarginModel for Binance (#9339) * refactor: use classic switch in BinanceFuturesBrokerageModel.GetBuyingPowerModel * fix: CryptoFutureMarginModel in BinanceCoinFuturesBrokerageModel * refactor: simplify BinanceCryptoFutureMarginModel collateral conversion * fix: restore IsCryptoCoinFuture guard in BinanceCryptoFutureMarginModel * refactor: simplify BinanceCryptoFutureMarginModel to direct BNFCR lookup Replace IsStableCoinWithoutPair foreach loop with a single TryGetValue check for BNFCR. BNFCR is EU/EEA-only (MiCA Credits Trading Mode) so the lookup is a no-op for all other users. Amount reflects availableBalance from the Binance API — the total cross-margin pool already aggregated by Binance — making the > 0 guard correct and avoiding CashBook iteration. * feat: add regression algorithm for BNFCR as sole collateral on Binance USDⓈ-M futures Asserts end-to-end that EU/MiCA accounts with zero USDT and BNFCR as the only collateral can open ADAUSDT positions. Verifies buying power, holdings AbsoluteHoldingsCost, TotalSaleVolume, TotalMarginUsed, maintenance margin consistency and TotalUnrealizedProfit accuracy. * refactor: BNFCR presence gate with CashBook iteration for supplementary collateral Replace IsStableCoinWithoutPair and hardcoded asset list with CashBook iteration gated by BNFCR presence. Binance controls which assets are in the account — all with non-zero walletBalance are valid collateral. Add tests for BNFCR zero balance and BTC collateral conversion. * refactor: aggregate all collateral without reference equality check * fix: shared collateral deduction across quote currencies for EU/MiCA BNFCR mode - Extract virtual SharesCollateral in CryptoFutureMarginModel - Override in BinanceCryptoFutureMarginModel: BNFCR present → all USDⓈ-M share pool - Add BNFCRCurrency const - Add SharedCollateralDeductsMaintenanceMarginAcrossQuoteCurrencies unit test - Refactor regression algorithm to assert shared collateral across ADAUSDT/ETHUSDC * refactor: remove dead IsCryptoCoinFuture guard from BinanceCryptoFutureMarginModel - Remove IsCryptoCoinFuture() check (coin futures use BinanceCoinFuturesBrokerageModel, not this model) - Call base.GetTotalCollateralAmount() instead of duplicating primaryCollateral.Amount - Remove CoinFutureDoesNotIncludeBnfcrAsCollateral test (tested wrong margin model) * refactor: make GetCollateralCash private in CryptoFutureMarginModel - No longer accessed by subclasses after removing direct collateral checks from BinanceCryptoFutureMarginModel
diff --git a/Algorithm.CSharp/BinanceCryptoFutureBnfcrCollateralRegressionAlgorithm.cs b/Algorithm.CSharp/BinanceCryptoFutureBnfcrCollateralRegressionAlgorithm.cs
@@ -0,0 +1,171 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+using System.Collections.Generic;
+using QuantConnect.Brokerages;
+using QuantConnect.Data;
+using QuantConnect.Data.Market;
+using QuantConnect.Interfaces;
+using QuantConnect.Orders;
+using QuantConnect.Securities;
+using QuantConnect.Securities.CryptoFuture;
+
+namespace QuantConnect.Algorithm.CSharp
+{
+    /// <summary>
+    /// Regression algorithm asserting that BNFCR serves as collateral for Binance USDⓈ-M futures
+    /// (EU/MiCA Credits Trading Mode) and that futures with different quote currencies (ADAUSDT, ETHUSDC)
+    /// correctly share the BNFCR collateral pool.
+    /// </summary>
+    public class BinanceCryptoFutureBnfcrCollateralRegressionAlgorithm : QCAlgorithm, IRegressionAlgorithmDefinition
+    {
+        private CryptoFuture _adaUsdt;
+        private CryptoFuture _ethUsdc;
+        private bool _orderPlaced;
+
+        public override void Initialize()
+        {
+            SetStartDate(2022, 12, 13);
+            SetEndDate(2022, 12, 13);
+            SetTimeZone(TimeZones.Utc);
+            SetBrokerageModel(BrokerageName.BinanceFutures, AccountType.Margin);
+
+            _adaUsdt = AddCryptoFuture("ADAUSDT");
+            _ethUsdc = AddCryptoFuture("ETHUSDC");
+
+            SetCash(0);
+            SetCash("BNFCR", 200m, 1m);
+            SetCash("ETH", 0, 1600);
+            SetCash("USDC", 0, 1);
+        }
+
+        public override void OnData(Slice slice)
+        {
+            if (_adaUsdt.Price == 0 || _orderPlaced)
+            {
+                return;
+            }
+
+            // 1. BNFCR collateral must produce positive buying power (USDT is zero)
+            var buyingPower = _adaUsdt.BuyingPowerModel.GetBuyingPower(new BuyingPowerParameters(Portfolio, _adaUsdt, OrderDirection.Buy));
+            if (buyingPower.Value <= 0)
+            {
+                throw new RegressionTestException($"Expected positive buying power from BNFCR, got {buyingPower.Value}");
+            }
+
+            // 2. Order must not be rejected
+            var ticket = Buy(_adaUsdt.Symbol, 1000);
+            _orderPlaced = true;
+            if (ticket.Status == OrderStatus.Invalid)
+            {
+                throw new RegressionTestException("Order rejected — BNFCR collateral should cover margin");
+            }
+
+            // 3. Margin must be tracked
+            if (Portfolio.TotalMarginUsed <= 0)
+            {
+                throw new RegressionTestException($"Expected positive TotalMarginUsed, got {Portfolio.TotalMarginUsed}");
+            }
+
+            // 4. Shared collateral: ETHUSDC (different quote currency) must deduct ADAUSDT margin
+            _ethUsdc.SetMarketPrice(new TradeBar { Time = Time, Symbol = _ethUsdc.Symbol, Close = 1600 });
+
+            var ethBuyingPower = _ethUsdc.BuyingPowerModel.GetBuyingPower(new BuyingPowerParameters(Portfolio, _ethUsdc, OrderDirection.Buy));
+            var adaBuyingPower = _adaUsdt.BuyingPowerModel.GetBuyingPower(new BuyingPowerParameters(Portfolio, _adaUsdt, OrderDirection.Buy));
+
+            // ETHUSDC must see less buying power than ADAUSDT - ADAUSDT maintenance margin
+            // is deducted from ETHUSDC's shared pool, but ADAUSDT skips itself.
+            if (ethBuyingPower.Value >= adaBuyingPower.Value)
+            {
+                throw new RegressionTestException(
+                    $"ETHUSDC buying power ({ethBuyingPower.Value}) must be less than ADAUSDT ({adaBuyingPower.Value}) " +
+                    $"— shared BNFCR pool must deduct ADAUSDT maintenance margin");
+            }
+        }
+
+        public override void OnEndOfAlgorithm()
+        {
+            if (!Portfolio.Invested)
+            {
+                throw new RegressionTestException("Expected an open position at end of algorithm");
+            }
+        }
+
+        public override void OnOrderEvent(OrderEvent orderEvent)
+        {
+            Debug($"{Time} {orderEvent}");
+        }
+
+        /// <summary>
+        /// This is used by the regression test system to indicate if the open source Lean repository has the required data to run this algorithm.
+        /// </summary>
+        public bool CanRunLocally { get; } = true;
+
+        /// <summary>
+        /// This is used by the regression test system to indicate which languages this algorithm is written in.
+        /// </summary>
+        public List<Language> Languages { get; } = new() { Language.CSharp };
+
+        /// <summary>
+        /// Data Points count of all timeslices of algorithm
+        /// </summary>
+        public long DataPoints => 4322;
+
+        /// <summary>
+        /// Data Points count of the algorithm history
+        /// </summary>
+        public int AlgorithmHistoryDataPoints => 0;
+
+        /// <summary>
+        /// Final status of the algorithm
+        /// </summary>
+        public AlgorithmStatus AlgorithmStatus => AlgorithmStatus.Completed;
+
+        /// <summary>
+        /// This is used by the regression test system to indicate what the expected statistics are from running the algorithm
+        /// </summary>
+        public Dictionary<string, string> ExpectedStatistics => new Dictionary<string, string>
+        {
+            {"Total Orders", "1"},
+            {"Average Win", "0%"},
+            {"Average Loss", "0%"},
+            {"Compounding Annual Return", "0%"},
+            {"Drawdown", "0%"},
+            {"Expectancy", "0"},
+            {"Start Equity", "200"},
+            {"End Equity", "206.86"},
+            {"Net Profit", "0%"},
+            {"Sharpe Ratio", "0"},
+            {"Sortino Ratio", "0"},
+            {"Probabilistic Sharpe Ratio", "0%"},
+            {"Loss Rate", "0%"},
+            {"Win Rate", "0%"},
+            {"Profit-Loss Ratio", "0"},
+            {"Alpha", "0"},
+            {"Beta", "0"},
+            {"Annual Standard Deviation", "0"},
+            {"Annual Variance", "0"},
+            {"Information Ratio", "0"},
+            {"Tracking Error", "0"},
+            {"Treynor Ratio", "0"},
+            {"Total Fees", "$0.12"},
+            {"Estimated Strategy Capacity", "$340000.00"},
+            {"Lowest Capacity Asset", "ADAUSDT 18R"},
+            {"Portfolio Turnover", "148.31%"},
+            {"Drawdown Recovery", "0"},
+            {"OrderListHash", "177ae917deb456790cfbcaaaf1ec1f5c"}
+        };
+    }
+}
diff --git a/Common/Brokerages/BinanceCoinFuturesBrokerageModel.cs b/Common/Brokerages/BinanceCoinFuturesBrokerageModel.cs
@@ -16,6 +16,7 @@
 using QuantConnect.Benchmarks;
 using QuantConnect.Orders.Fees;
 using QuantConnect.Securities;
+using QuantConnect.Securities.CryptoFuture;
 
 namespace QuantConnect.Brokerages
 {
@@ -51,5 +52,15 @@ public override IFeeModel GetFeeModel(Security security)
         {
             return new BinanceCoinFuturesFeeModel();
         }
+
+        /// <summary>
+        /// Creates the crypto future margin model for the given security
+        /// </summary>
+        /// <param name="security">The security to create the margin model for</param>
+        /// <returns>The margin model instance</returns>
+        protected override IBuyingPowerModel CreateCryptoFutureMarginModel(Security security)
+        {
+            return new CryptoFutureMarginModel(GetLeverage(security));
+        }
     }
 }
diff --git a/Common/Brokerages/BinanceFuturesBrokerageModel.cs b/Common/Brokerages/BinanceFuturesBrokerageModel.cs
@@ -72,5 +72,32 @@ public override IMarginInterestRateModel GetMarginInterestRateModel(Security sec
             }
             return base.GetMarginInterestRateModel(security);
         }
+
+        /// <summary>
+        /// Gets a new buying power model for the security.
+        /// For <see cref="SecurityType.CryptoFuture"/>, returns a <see cref="BinanceCryptoFutureMarginModel"/>
+        /// that recognizes supplementary stable coin collateral (e.g. BNFCR for EU Credits Trading Mode).
+        /// </summary>
+        /// <param name="security">The security to get a buying power model for</param>
+        /// <returns>The buying power model for this brokerage/security</returns>
+        public override IBuyingPowerModel GetBuyingPowerModel(Security security)
+        {
+            if (security?.Type == SecurityType.CryptoFuture)
+            {
+                return CreateCryptoFutureMarginModel(security);
+            }
+
+            return base.GetBuyingPowerModel(security);
+        }
+
+        /// <summary>
+        /// Creates the crypto future margin model for the given security
+        /// </summary>
+        /// <param name="security">The security to create the margin model for</param>
+        /// <returns>The margin model instance</returns>
+        protected virtual IBuyingPowerModel CreateCryptoFutureMarginModel(Security security)
+        {
+            return new BinanceCryptoFutureMarginModel(GetLeverage(security));
+        }
     }
 }
diff --git a/Common/Securities/CryptoFuture/BinanceCryptoFutureMarginModel.cs b/Common/Securities/CryptoFuture/BinanceCryptoFutureMarginModel.cs
@@ -0,0 +1,93 @@
+/*
+ * QUANTCONNECT.COM - Democratizing Finance, Empowering Individuals.
+ * Lean Algorithmic Trading Engine v2.0. Copyright 2014 QuantConnect Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+namespace QuantConnect.Securities.CryptoFuture
+{
+    /// <summary>
+    /// Binance-specific crypto future margin model that includes supplementary stable coin
+    /// currencies as alternative collateral for non-coin (USDⓈ-M) futures.
+    /// </summary>
+    /// <remarks>
+    /// EU/EEA users under MiCA Credits Trading Mode have BNFCR in their account.
+    /// When BNFCR is present, this model aggregates all supplementary collateral assets
+    /// using their walletBalance values converted to the primary collateral currency.
+    /// Non-EU accounts don't have BNFCR — the check is a no-op for them.
+    /// See: https://www.binance.com/en/support/faq/detail/0e857c392a2d47cebde0af762d9255ae
+    /// </remarks>
+    public class BinanceCryptoFutureMarginModel : CryptoFutureMarginModel
+    {
+        /// <summary>
+        /// Binance Futures Credits currency symbol, present in EU/EEA accounts under MiCA Credits Trading Mode.
+        /// </summary>
+        private const string BNFCRCurrency = "BNFCR";
+
+        /// <summary>
+        /// Creates a new instance
+        /// </summary>
+        /// <param name="leverage">The leverage to use, default 25x</param>
+        public BinanceCryptoFutureMarginModel(decimal leverage = 25)
+            : base(leverage)
+        {
+        }
+
+        /// <summary>
+        /// Gets the total collateral amount for a Binance crypto future, including supplementary
+        /// collateral assets for EU/EEA accounts in MiCA Credits Trading Mode.
+        /// For coin futures (e.g. BTCUSD), only the primary collateral (base currency) is used.
+        /// </summary>
+        /// <param name="portfolio">The algorithm's portfolio</param>
+        /// <param name="security">The crypto future security</param>
+        /// <param name="primaryCollateral">The primary collateral cash (e.g. USDT)</param>
+        /// <returns>Total collateral amount in terms of the primary collateral currency</returns>
+        protected override decimal GetTotalCollateralAmount(
+            SecurityPortfolioManager portfolio, Security security, Cash primaryCollateral)
+        {
+            // BNFCR presence means EU/EEA account in MiCA Credits Trading Mode.
+            // Non-EU accounts don't have BNFCR in CashBook — skip entirely.
+            var cashBook = portfolio.CashBook;
+            if (!cashBook.ContainsKey(BNFCRCurrency))
+            {
+                return base.GetTotalCollateralAmount(portfolio, security, primaryCollateral);
+            }
+
+            // Aggregate all collateral assets using walletBalance values.
+            // Binance controls which assets are in the account — we sum everything
+            // with a non-zero balance, converting to the primary collateral currency.
+            // Negative amounts (e.g. BNFCR fees) correctly reduce the total.
+            var total = 0m;
+            foreach (var kvp in cashBook)
+            {
+                var cash = kvp.Value;
+                if (cash.Amount == 0)
+                {
+                    continue;
+                }
+
+                total += cashBook.Convert(cash.Amount, cash.Symbol, primaryCollateral.Symbol);
+            }
+
+            return total;
+        }
+
+        /// <summary>
+        /// When BNFCR is present (EU/MiCA mode), all USDⓈ-M futures share the same collateral
+        /// pool regardless of quote currency (USDT, USDC, etc.).
+        /// </summary>
+        protected override bool SharesCollateral(SecurityPortfolioManager portfolio, Cash collateralCurrency, Security otherCryptoFuture)
+        {
+            return portfolio.CashBook.ContainsKey(BNFCRCurrency) || base.SharesCollateral(portfolio, collateralCurrency, otherCryptoFuture);
+        }
+    }
+}
diff --git a/Common/Securities/CryptoFuture/CryptoFutureMarginModel.cs b/Common/Securities/CryptoFuture/CryptoFutureMarginModel.cs
@@ -86,14 +86,14 @@ public override InitialMargin GetInitialMarginRequirement(InitialMarginParameter
         protected override decimal GetMarginRemaining(SecurityPortfolioManager portfolio, Security security, OrderDirection direction)
         {
             var collateralCurrency = GetCollateralCash(security);
-            var totalCollateralCurrency = collateralCurrency.Amount;
+            var totalCollateralCurrency = GetTotalCollateralAmount(portfolio, security, collateralCurrency);
             var result = totalCollateralCurrency;
 
             foreach (var kvp in portfolio.Where(holdings => holdings.Value.Invested && holdings.Value.Type == SecurityType.CryptoFuture && holdings.Value.Symbol != security.Symbol))
             {
                 var otherCryptoFuture = portfolio.Securities[kvp.Key];
                 // check if we share the collateral
-                if (collateralCurrency == GetCollateralCash(otherCryptoFuture))
+                if (SharesCollateral(portfolio, collateralCurrency, otherCryptoFuture))
                 {
                     // we reduce the available collateral based on total usage of all other positions too
                     result -= otherCryptoFuture.BuyingPowerModel.GetMaintenanceMargin(MaintenanceMarginParameters.ForCurrentHoldings(otherCryptoFuture));
@@ -139,6 +139,18 @@ protected override decimal GetMarginRemaining(SecurityPortfolioManager portfolio
             return result < 0 ? 0 : result;
         }
 
+        /// <summary>
+        /// Determines whether the given security shares collateral with another crypto future.
+        /// </summary>
+        /// <param name="portfolio">The algorithm's portfolio</param>
+        /// <param name="collateralCurrency">The collateral cash for the current security</param>
+        /// <param name="otherCryptoFuture">The other crypto future security to check</param>
+        /// <returns>True if both securities share the same collateral</returns>
+        protected virtual bool SharesCollateral(SecurityPortfolioManager portfolio, Cash collateralCurrency, Security otherCryptoFuture)
+        {
+            return collateralCurrency == GetCollateralCash(otherCryptoFuture);
+        }
+
         /// <summary>
         /// Helper method to determine what's the collateral currency for the given crypto future
         /// </summary>
@@ -154,5 +166,19 @@ private static Cash GetCollateralCash(Security security)
 
             return collateralCurrency;
         }
+
+        /// <summary>
+        /// Gets the total collateral amount for the given crypto future position.
+        /// The base implementation returns only the primary collateral amount.
+        /// Override in subclasses to include supplementary collateral currencies.
+        /// </summary>
+        /// <param name="portfolio">The algorithm's portfolio</param>
+        /// <param name="security">The crypto future security</param>
+        /// <param name="primaryCollateral">The primary collateral cash (e.g. USDT for non-coin futures, BTC for coin futures)</param>
+        /// <returns>Total collateral amount in terms of the primary collateral currency</returns>
+        protected virtual decimal GetTotalCollateralAmount(SecurityPortfolioManager portfolio, Security security, Cash primaryCollateral)
+        {
+            return primaryCollateral.Amount;
+        }
     }
 }
diff --git a/Tests/Common/Securities/CryptoFuture/CryptoFutureMarginModelTests.cs b/Tests/Common/Securities/CryptoFuture/CryptoFutureMarginModelTests.cs

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@`
`16`	`16`	`using QuantConnect.Benchmarks;`
`17`	`17`	`using QuantConnect.Orders.Fees;`
`18`	`18`	`using QuantConnect.Securities;`
	`19`	`+using QuantConnect.Securities.CryptoFuture;`
`19`	`20`
`20`	`21`	`namespace QuantConnect.Brokerages`
`21`	`22`	`{`
`@@ -51,5 +52,15 @@ public override IFeeModel GetFeeModel(Security security)`
`51`	`52`	`{`
`52`	`53`	`return new BinanceCoinFuturesFeeModel();`
`53`	`54`	`}`
	`55`	`+`
	`56`	`+ /// <summary>`
	`57`	`+ /// Creates the crypto future margin model for the given security`
	`58`	`+ /// </summary>`
	`59`	`+ /// <param name="security">The security to create the margin model for</param>`
	`60`	`+ /// <returns>The margin model instance</returns>`
	`61`	`+ protected override IBuyingPowerModel CreateCryptoFutureMarginModel(Security security)`
	`62`	`+ {`
	`63`	`+ return new CryptoFutureMarginModel(GetLeverage(security));`
	`64`	`+ }`
`54`	`65`	`}`
`55`	`66`	`}`