From ceed3c663b3eb5498d2eeff232f4122945e58126 Mon Sep 17 00:00:00 2001
From: Matthias <xmatthias@outlook.com>
Date: Wed, 4 Aug 2021 07:15:14 +0200
Subject: [PATCH] Document using protections

---
 docs/hyperopt.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

diff --git a/docs/hyperopt.md b/docs/hyperopt.md
index 4fba925d0..95a1cfcc5 100644
--- a/docs/hyperopt.md
+++ b/docs/hyperopt.md
@@ -326,7 +326,7 @@ There are four parameter types each suited for different purposes.
 !!! Warning
     Hyperoptable parameters cannot be used in `populate_indicators` - as hyperopt does not recalculate indicators for each epoch, so the starting value would be used in this case.
 
-### Optimizing an indicator parameter
+## Optimizing an indicator parameter
 
 Assuming you have a simple strategy in mind - a EMA cross strategy (2 Moving averages crossing) - and you'd like to find the ideal parameters for this strategy.
 
@@ -413,6 +413,94 @@ While this strategy is most likely too simple to provide consistent profit, it s
     While this may slow down the hyperopt startup speed, the overall performance will increase as the Hyperopt execution itself may pick the same value for multiple epochs (changing other values).
     You should however try to use space ranges as small as possible. Every new column will require more memory, and every possibility hyperopt can try will increase the search space.
 
+## Optimizing protections
+
+Freqtrade can also optimize protections. How you optimize protections is up to you, and the following should be considered as example only.
+
+The strategy will simply need to define the "protections" entry as property returning a list of protection configurations.
+
+``` python
+from pandas import DataFrame
+from functools import reduce
+
+import talib.abstract as ta
+
+from freqtrade.strategy import IStrategy
+from freqtrade.strategy import CategoricalParameter, DecimalParameter, IntParameter
+import freqtrade.vendor.qtpylib.indicators as qtpylib
+
+class MyAwesomeStrategy(IStrategy):
+    stoploss = -0.05
+    timeframe = '15m'
+    # Define the parameter spaces
+    coolback_lookback = IntParameter(2, 48, default=5, space="protection", optimize=True)
+    stop_duration = IntParameter(12, 200, default=5, space="protection", optimize=True)
+    use_stop_protection = CategoricalParameter([True, False], default=True, space="protection", optimize=True)
+
+
+    @property
+    def protections(self):
+        prot = []
+
+        prot.append({
+            "method": "CooldownPeriod",
+            "stop_duration_candles": self.coolback_lookback.value
+        })
+        if self.use_stop_protection.value:
+            prot.append({
+                "method": "StoplossGuard",
+                "lookback_period_candles": 24 * 3,
+                "trade_limit": 4,
+                "stop_duration_candles": self.stop_duration.value,
+                "only_per_pair": False
+            })
+
+        return protection
+
+    def populate_indicators(self, dataframe: DataFrame, metadata: dict) -> DataFrame:
+        # ...
+        
+```
+
+You can then run hyperopt as follows:
+`freqtrade hyperopt --hyperopt-loss SharpeHyperOptLossDaily --strategy MyAwesomeStrategy --spaces protection`
+
+!!! Note
+    The protection space is not part of the default space, and is only available with the Parameters Hyperopt interface, not with the legacy hyperopt interface (which required separate hyperopt files).
+    Freqtrade will also automatically change the "--enable-protections" flag if the protection space is selected.
+
+### Migrating from previous property setups
+
+A migration from a previous setup is pretty simple, and can be accomplished by converting the protections entry to a property.
+In simple terms, the following configuration will be converted to the below.
+
+``` python
+class MyAwesomeStrategy(IStrategy):
+    protections = [
+        {
+            "method": "CooldownPeriod",
+            "stop_duration_candles": 4
+        }
+    ]
+```
+
+Result
+
+``` python
+class MyAwesomeStrategy(IStrategy):
+    
+    @property
+    def protections(self):
+        return [
+            {
+                "method": "CooldownPeriod",
+                "stop_duration_candles": 4
+            }
+        ]
+```
+
+You will then obviously also change potential interesting entries to parameters to allow hyper-optimization.
+
 ## Loss-functions
 
 Each hyperparameter tuning requires a target. This is usually defined as a loss function (sometimes also called objective function), which should decrease for more desirable results, and increase for bad results.