Merge pull request #2872 from freqtrade/interface_ordertimeoutcallback

Buy order timeout callback

docs/strategy-advanced.md

@@ -0,0 +1,91 @@
+# Advanced Strategies
+
+This page explains some advanced concepts available for strategies.
+If you're just getting started, please be familiar with the methods described in the [Strategy Customization](strategy-customization.md) documentation first.
+
+## Custom order timeout rules
+
+Simple, timebased order-timeouts can be configured either via strategy or in the configuration in the `unfilledtimeout` section.
+
+However, freqtrade also offers a custom callback for both ordertypes, which allows you to decide based on custom criteria if a order did time out or not.
+
+!!! Note
+    Unfilled order timeouts are not relevant during backtesting or hyperopt, and are only relevant during real (live) trading. Therefore these methods are only called in these circumstances.
+
+### Custom order timeout example
+
+A simple example, which applies different unfilled-timeouts depending on the price of the asset can be seen below.
+It applies a tight timeout for higher priced assets, while allowing more time to fill on cheap coins.
+
+The function must return either `True` (cancel order) or `False` (keep order alive).
+
+``` python
+from datetime import datetime, timestamp
+from freqtrade.persistence import Trade
+
+class Awesomestrategy(IStrategy):
+
+    # ... populate_* methods
+
+    # Set unfilledtimeout to 25 hours, since our maximum timeout from below is 24 hours.
+    unfilledtimeout = {
+        'buy': 60 * 25,
+        'sell': 60 * 25
+    }
+
+    def check_buy_timeout(self, pair: str, trade: 'Trade', order: dict, **kwargs) -> bool:
+        if trade.open_rate > 100 and trade.open_date < datetime.utcnow() - timedelta(minutes=5):
+            return True
+        elif trade.open_rate > 10 and trade.open_date < datetime.utcnow() - timedelta(minutes=3):
+            return True
+        elif trade.open_rate < 1 and trade.open_date < datetime.utcnow() - timedelta(hours=24):
+           return True
+        return False
+
+
+    def check_sell_timeout(self, pair: str, trade: 'Trade', order: dict, **kwargs) -> bool:
+        if trade.open_rate > 100 and trade.open_date < datetime.utcnow() - timedelta(minutes=5):
+            return True
+        elif trade.open_rate > 10 and trade.open_date < datetime.utcnow() - timedelta(minutes=3):
+            return True
+        elif trade.open_rate < 1 and trade.open_date < datetime.utcnow() - timedelta(hours=24):
+           return True
+        return False
+```
+
+!!! Note
+    For the above example, `unfilledtimeout` must be set to something bigger than 24h, otherwise that type of timeout will apply first.
+
+### Custom order timeout example (using additional data)
+
+``` python
+from datetime import datetime, timestamp
+from freqtrade.persistence import Trade
+
+class Awesomestrategy(IStrategy):
+
+    # ... populate_* methods
+
+    # Set unfilledtimeout to 25 hours, since our maximum timeout from below is 24 hours.
+    unfilledtimeout = {
+        'buy': 60 * 25,
+        'sell': 60 * 25
+    }
+
+    def check_buy_timeout(self, pair: str, trade: Trade, order: dict, **kwargs) -> bool:
+        ob = self.dp.orderbook(pair, 1)
+        current_price = ob['bids'][0][0]
+        # Cancel buy order if price is more than 2% above the order.
+        if current_price > order['price'] * 1.02:
+            return True
+        return False
+
+
+    def check_sell_timeout(self, pair: str, trade: Trade, order: dict, **kwargs) -> bool:
+        ob = self.dp.orderbook(pair, 1)
+        current_price = ob['asks'][0][0]
+        # Cancel sell order if price is more than 2% below the order.
+        if current_price < order['price'] * 0.98:
+            return True
+        return False
+```

docs/strategy-customization.md

@@ -1,7 +1,6 @@
 # Strategy Customization
 
-This page explains where to customize your strategies, and add new
-indicators.
+This page explains where to customize your strategies, and add new indicators.
 
 ## Install a custom strategy file
 

docs/utils.md

@@ -77,7 +77,7 @@ Results will be located in `user_data/strategies/<strategyclassname>.py`.
 
 ``` output
 usage: freqtrade new-strategy [-h] [--userdir PATH] [-s NAME]
-                              [--template {full,minimal}]
+                              [--template {full,minimal,advanced}]
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -86,10 +86,10 @@ optional arguments:
   -s NAME, --strategy NAME
                         Specify strategy class name which will be used by the
                         bot.
-  --template {full,minimal}
-                        Use a template which is either `minimal` or `full`
-                        (containing multiple sample indicators). Default:
-                        `full`.
+  --template {full,minimal,advanced}
+                        Use a template which is either `minimal`, `full`
+                        (containing multiple sample indicators) or `advanced`.
+                        Default: `full`.
 
 ```
 
@@ -105,6 +105,12 @@ With custom user directory
 freqtrade new-strategy --userdir ~/.freqtrade/ --strategy AwesomeStrategy
 ```
 
+Using the advanced template (populates all optional functions and methods)
+
+```bash
+freqtrade new-strategy --strategy AwesomeStrategy --template advanced
+```
+
 ## Create new hyperopt
 
 Creates a new hyperopt from a template similar to SampleHyperopt.
@@ -114,7 +120,7 @@ Results will be located in `user_data/hyperopts/<classname>.py`.
 
 ``` output
 usage: freqtrade new-hyperopt [-h] [--userdir PATH] [--hyperopt NAME]
-                              [--template {full,minimal}]
+                              [--template {full,minimal,advanced}]
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -122,10 +128,10 @@ optional arguments:
                         Path to userdata directory.
   --hyperopt NAME       Specify hyperopt class name which will be used by the
                         bot.
-  --template {full,minimal}
-                        Use a template which is either `minimal` or `full`
-                        (containing multiple sample indicators). Default:
-                        `full`.
+  --template {full,minimal,advanced}
+                        Use a template which is either `minimal`, `full`
+                        (containing multiple sample indicators) or `advanced`.
+                        Default: `full`.
 ```
 
 ### Sample usage of new-hyperopt