Allow and document time-based custom stoploss

closes #3206

docs/strategy-advanced.md

@@ -31,7 +31,9 @@ E.g. `current_profit = 0.05` (5% profit) - stoploss returns `0.02` - then you "l
 
 ### Custom stoploss examples
 
-Absolute stoploss. The below example sets absolute profit levels based on the current profit.
+#### Absolute stoploss
+
+The below example sets absolute profit levels based on the current profit.
 
 * Use the regular stoploss until 20% profit is reached
 * Once profit is > 20% - stoploss will be set to 7%.s
@@ -39,8 +41,10 @@ Absolute stoploss. The below example sets absolute profit levels based on the cu
 * Once profit is > 40%, stoploss will be at 25%, locking in at least 25% of the profit.
 
 ``` python
-    def stoploss_value(self, pair: str, trade: Trade, current_rate: float, current_profit: float,
-                       **kwargs) -> float:
+    custom_stoploss = True
+
+    def stoploss_value(self, pair: str, trade: Trade, current_time: datetime, current_rate: float,
+                       current_profit: float, **kwargs) -> float:
         # TODO: Add full docstring here
 
         # Calculate as `-desired_stop_from_open + current_profit` to get the distance between current_profit and initial price
@@ -53,6 +57,24 @@ Absolute stoploss. The below example sets absolute profit levels based on the cu
         return 1
 ```
 
+#### Time based trailing stop
+
+Use the initial stoploss for the first 60 minutes, after this change to 10% trailing stoploss, and after 2 hours (120 minutes) we use a 5% trailing stoploss.
+
+``` python
+    custom_stoploss = True
+
+    def stoploss_value(self, pair: str, trade: Trade, current_time: datetime, current_rate: float,
+                       current_profit: float, **kwargs) -> float:
+        # TODO: Add full docstring here
+
+        if current_time - timedelta(minutes=60) > trade.open_time:
+            return -0.10
+        elif current_time - timedelta(minutes=120) > trade.open_time:
+            return -0.05
+        return 1
+```
+
 ## Custom order timeout rules
 
 Simple, time-based order-timeouts can be configured either via strategy or in the configuration in the `unfilledtimeout` section.

freqtrade/strategy/interface.py

@@ -255,8 +255,8 @@ class IStrategy(ABC):
         """
         return True
 
-    def stoploss_value(self, pair: str, trade: Trade, current_rate: float, current_profit: float,
-                       **kwargs) -> float:
+    def stoploss_value(self, pair: str, trade: Trade, current_time: datetime, current_rate: float,
+                       current_profit: float, **kwargs) -> float:
         """
         Define custom stoploss logic
         The custom stoploss can never be below self.stoploss, which serves as a hard maximum loss.
@@ -554,6 +554,7 @@ class IStrategy(ABC):
         if self.custom_stoploss:
             stop_loss_value = strategy_safe_wrapper(self.stoploss_value, default_retval=None
                                                     )(pair=trade.pair, trade=trade,
+                                                      current_time=current_time,
                                                       current_rate=current_rate,
                                                       current_profit=current_profit)
             # Sanity check - error cases will return None