stable/docs/bot-usage.md

302 lines
13 KiB
Markdown
Raw Normal View History

# Start the bot
This page explains the different parameters of the bot and how to run it.
2018-01-02 02:17:10 +00:00
!!! Note:
If you've used `setup.sh`, don't forget to activate your virtual environment (`source .env/bin/activate`) before running freqtrade commands.
2018-01-02 02:17:10 +00:00
## Bot commands
2018-01-02 02:17:10 +00:00
```
2019-03-29 19:19:40 +00:00
usage: freqtrade [-h] [-v] [--logfile FILE] [--version] [-c PATH] [-d PATH]
[-s NAME] [--strategy-path PATH] [--db-url PATH]
[--sd-notify]
2019-03-04 06:24:41 +00:00
{backtesting,edge,hyperopt} ...
2018-01-02 02:17:10 +00:00
2019-01-03 13:38:38 +00:00
Free, open source crypto trading bot
2018-01-02 02:17:10 +00:00
positional arguments:
{backtesting,edge,hyperopt}
2019-03-04 06:24:41 +00:00
backtesting Backtesting module.
edge Edge module.
hyperopt Hyperopt module.
2018-01-02 02:17:10 +00:00
optional arguments:
-h, --help show this help message and exit
2019-03-04 06:24:41 +00:00
-v, --verbose Verbose mode (-vv for more, -vvv to get all messages).
2019-03-29 19:19:40 +00:00
--logfile FILE Log to the file specified
2019-07-18 09:12:34 +00:00
-V, --version show program's version number and exit
2018-01-18 07:06:37 +00:00
-c PATH, --config PATH
2019-03-04 06:24:41 +00:00
Specify configuration file (default: None). Multiple
2019-06-19 21:04:11 +00:00
--config options may be used. Can be set to '-' to
read config from stdin.
2018-05-30 05:24:13 +00:00
-d PATH, --datadir PATH
2019-03-04 06:24:41 +00:00
Path to backtest data.
-s NAME, --strategy NAME
2019-03-04 06:24:41 +00:00
Specify strategy class name (default:
DefaultStrategy).
--strategy-path PATH Specify additional strategy lookup path.
2018-06-07 03:36:39 +00:00
--db-url PATH Override trades database URL, this is useful if
dry_run is enabled or in custom deployments (default:
2019-03-04 06:24:41 +00:00
None).
--sd-notify Notify systemd service manager.
2018-01-02 02:17:10 +00:00
```
### How to specify which configuration file be used?
The bot allows you to select which configuration file you want to use by means of
the `-c/--config` command line option:
2018-01-02 02:17:10 +00:00
```bash
freqtrade -c path/far/far/away/config.json
2018-01-02 02:17:10 +00:00
```
Per default, the bot loads the `config.json` configuration file from the current
working directory.
### How to use multiple configuration files?
The bot allows you to use multiple configuration files by specifying multiple
`-c/--config` options in the command line. Configuration parameters
defined in the latter configuration files override parameters with the same name
defined in the previous configuration files specified in the command line earlier.
For example, you can make a separate configuration file with your key and secrete
for the Exchange you use for trading, specify default configuration file with
empty key and secrete values while running in the Dry Mode (which does not actually
require them):
```bash
freqtrade -c ./config.json
```
and specify both configuration files when running in the normal Live Trade Mode:
```bash
freqtrade -c ./config.json -c path/to/secrets/keys.config.json
```
This could help you hide your private Exchange key and Exchange secrete on you local machine
by setting appropriate file permissions for the file which contains actual secrets and, additionally,
prevent unintended disclosure of sensitive private data when you publish examples
of your configuration in the project issues or in the Internet.
See more details on this technique with examples in the documentation page on
2019-04-01 17:25:13 +00:00
[configuration](configuration.md).
### How to use **--strategy**?
This parameter will allow you to load your custom strategy class.
Per default without `--strategy` or `-s` the bot will load the
`DefaultStrategy` included with the bot (`freqtrade/strategy/default_strategy.py`).
2018-01-18 07:06:37 +00:00
The bot will search your strategy file within `user_data/strategies` and `freqtrade/strategy`.
2018-01-18 07:06:37 +00:00
To load a strategy, simply pass the class name (e.g.: `CustomStrategy`) in this parameter.
2018-01-18 07:06:37 +00:00
2018-11-15 18:54:17 +00:00
**Example:**
In `user_data/strategies` you have a file `my_awesome_strategy.py` which has
2018-03-25 14:42:20 +00:00
a strategy class called `AwesomeStrategy` to load it:
2018-01-18 07:06:37 +00:00
```bash
freqtrade --strategy AwesomeStrategy
2018-01-18 07:06:37 +00:00
```
2018-11-15 18:54:17 +00:00
If the bot does not find your strategy file, it will display in an error
message the reason (File not found, or errors in your code).
2018-01-18 07:06:37 +00:00
Learn more about strategy file in
2019-05-19 07:07:43 +00:00
[Strategy Customization](strategy-customization.md).
2018-01-18 07:06:37 +00:00
### How to use **--strategy-path**?
2018-03-27 16:46:42 +00:00
This parameter allows you to add an additional strategy lookup path, which gets
checked before the default locations (The passed path must be a directory!):
2018-03-27 16:46:42 +00:00
```bash
freqtrade --strategy AwesomeStrategy --strategy-path /some/directory
2018-03-27 16:46:42 +00:00
```
2018-01-18 07:06:37 +00:00
#### How to install a strategy?
This is very simple. Copy paste your strategy file into the directory
2018-03-27 16:46:42 +00:00
`user_data/strategies` or use `--strategy-path`. And voila, the bot is ready to use it.
2018-01-18 07:06:37 +00:00
### How to use **--db-url**?
2018-11-15 18:54:17 +00:00
When you run the bot in Dry-run mode, per default no transactions are
stored in a database. If you want to store your bot actions in a DB
2018-06-07 03:36:39 +00:00
using `--db-url`. This can also be used to specify a custom database
in production mode. Example command:
2018-01-02 02:17:10 +00:00
```bash
freqtrade -c config.json --db-url sqlite:///tradesv3.dry_run.sqlite
2018-01-02 02:17:10 +00:00
```
## Backtesting commands
Backtesting also uses the config specified via `-c/--config`.
```
2019-03-04 06:24:41 +00:00
usage: freqtrade backtesting [-h] [-i TICKER_INTERVAL] [--timerange TIMERANGE]
2019-04-22 19:11:56 +00:00
[--max_open_trades MAX_OPEN_TRADES]
[--stake_amount STAKE_AMOUNT] [-r] [--eps] [--dmmp]
[-l]
[--strategy-list STRATEGY_LIST [STRATEGY_LIST ...]]
[--export EXPORT] [--export-filename PATH]
2018-01-02 02:17:10 +00:00
optional arguments:
-h, --help show this help message and exit
-i TICKER_INTERVAL, --ticker-interval TICKER_INTERVAL
2019-03-04 06:24:41 +00:00
Specify ticker interval (1m, 5m, 30m, 1h, 1d).
--timerange TIMERANGE
2019-03-04 06:24:41 +00:00
Specify what timerange of data to use.
2019-04-22 19:11:56 +00:00
--max_open_trades MAX_OPEN_TRADES
Specify max_open_trades to use.
--stake_amount STAKE_AMOUNT
Specify stake_amount.
-r, --refresh-pairs-cached
Refresh the pairs files in tests/testdata with the
latest data from the exchange. Use it if you want to
run your optimization commands with up-to-date data.
2018-07-19 11:20:15 +00:00
--eps, --enable-position-stacking
Allow buying the same pair multiple times (position
2019-03-04 06:24:41 +00:00
stacking).
2018-07-19 11:20:15 +00:00
--dmmp, --disable-max-market-positions
2018-07-17 19:05:31 +00:00
Disable applying `max_open_trades` during backtest
(same as setting `max_open_trades` to a very high
2019-03-04 06:24:41 +00:00
number).
-l, --live Use live data.
--strategy-list STRATEGY_LIST [STRATEGY_LIST ...]
2019-08-06 04:27:38 +00:00
Provide a space-separated list of strategies to
backtest Please note that ticker-interval needs to be
set either in config or via command line. When using
this together with --export trades, the strategy-name
is injected into the filename (so backtest-data.json
becomes backtest-data-DefaultStrategy.json
2019-03-04 06:24:41 +00:00
--export EXPORT Export backtest results, argument are: trades. Example
--export=trades
2018-07-17 19:05:31 +00:00
--export-filename PATH
Save backtest results to this filename requires
--export to be set as well Example --export-
2018-07-17 19:05:31 +00:00
filename=user_data/backtest_data/backtest_today.json
(default: user_data/backtest_data/backtest-
result.json)
2018-01-02 02:17:10 +00:00
```
### Getting historic data for backtesting
The first time your run Backtesting, you will need to download some historic data first.
This can be accomplished by using `freqtrade download-data`.
Check the corresponding [help page section](backtesting.md#Getting-data-for-backtesting-and-hyperopt) for more details
2018-01-02 02:17:10 +00:00
## Hyperopt commands
2018-06-15 07:45:19 +00:00
To optimize your strategy, you can use hyperopt parameter hyperoptimization
to find optimal parameter values for your stategy.
2018-01-02 02:17:10 +00:00
```
2019-03-04 06:24:41 +00:00
usage: freqtrade hyperopt [-h] [-i TICKER_INTERVAL] [--timerange TIMERANGE]
2019-07-18 18:02:28 +00:00
[--max_open_trades INT]
[--stake_amount STAKE_AMOUNT] [-r]
2019-07-25 05:49:33 +00:00
[--customhyperopt NAME] [--hyperopt-path PATH]
2019-07-22 16:37:34 +00:00
[--eps] [-e INT]
2019-07-18 18:02:28 +00:00
[-s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...]]
[--dmmp] [--print-all] [--no-color] [-j JOBS]
2019-07-18 18:02:28 +00:00
[--random-state INT] [--min-trades INT] [--continue]
[--hyperopt-loss NAME]
2018-01-02 02:17:10 +00:00
optional arguments:
-h, --help show this help message and exit
-i TICKER_INTERVAL, --ticker-interval TICKER_INTERVAL
2019-07-18 18:02:28 +00:00
Specify ticker interval (`1m`, `5m`, `30m`, `1h`,
`1d`).
2019-03-04 06:24:41 +00:00
--timerange TIMERANGE
Specify what timerange of data to use.
2019-07-18 18:02:28 +00:00
--max_open_trades INT
Specify max_open_trades to use.
--stake_amount STAKE_AMOUNT
Specify stake_amount.
2019-04-22 19:11:56 +00:00
-r, --refresh-pairs-cached
Refresh the pairs files in tests/testdata with the
latest data from the exchange. Use it if you want to
run your optimization commands with up-to-date data.
2019-03-04 06:24:41 +00:00
--customhyperopt NAME
Specify hyperopt class name (default:
2019-07-18 18:02:28 +00:00
`DefaultHyperOpts`).
2019-07-22 16:37:34 +00:00
--hyperopt-path PATH Specify additional lookup path for Hyperopts and
Hyperopt Loss functions.
2018-07-19 11:20:15 +00:00
--eps, --enable-position-stacking
Allow buying the same pair multiple times (position
2019-03-04 06:24:41 +00:00
stacking).
2019-07-18 18:02:28 +00:00
-e INT, --epochs INT Specify number of epochs (default: 100).
-s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...], --spaces {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...]
Specify which parameters to hyperopt. Space-separated
list. Default: `all`.
2018-07-19 11:20:15 +00:00
--dmmp, --disable-max-market-positions
2018-07-17 19:05:31 +00:00
Disable applying `max_open_trades` during backtest
(same as setting `max_open_trades` to a very high
2019-03-04 06:24:41 +00:00
number).
--print-all Print all results, not only the best ones.
--no-color Disable colorization of hyperopt results. May be
useful if you are redirecting output to a file.
-j JOBS, --job-workers JOBS
The number of concurrently running jobs for
hyperoptimization (hyperopt worker processes). If -1
(default), all CPUs are used, for -2, all CPUs but one
are used, etc. If 1 is given, no parallel computing
code is used at all.
2019-07-18 18:02:28 +00:00
--random-state INT Set random state to some positive integer for
reproducible hyperopt results.
--min-trades INT Set minimal desired number of trades for evaluations
in the hyperopt optimization path (default: 1).
--continue Continue hyperopt from previous runs. By default,
temporary files will be removed and hyperopt will
start from scratch.
2019-08-12 04:45:27 +00:00
--hyperopt-loss NAME Specify the class name of the hyperopt loss function
2019-07-18 18:02:28 +00:00
class (IHyperOptLoss). Different functions can
generate completely different results, since the
2019-08-12 04:45:27 +00:00
target for optimization is different. Built-in
Hyperopt-loss-functions are: DefaultHyperOptLoss,
OnlyProfitHyperOptLoss, SharpeHyperOptLoss.
(default: `DefaultHyperOptLoss`).
2018-01-02 02:17:10 +00:00
```
2018-11-15 18:54:17 +00:00
## Edge commands
To know your trade expectancy and winrate against historical data, you can use Edge.
2018-11-15 18:54:17 +00:00
```
2019-04-22 19:11:56 +00:00
usage: freqtrade edge [-h] [-i TICKER_INTERVAL] [--timerange TIMERANGE]
[--max_open_trades MAX_OPEN_TRADES]
[--stake_amount STAKE_AMOUNT] [-r]
[--stoplosses STOPLOSS_RANGE]
2018-11-15 18:54:17 +00:00
optional arguments:
-h, --help show this help message and exit
-i TICKER_INTERVAL, --ticker-interval TICKER_INTERVAL
2019-03-04 06:24:41 +00:00
Specify ticker interval (1m, 5m, 30m, 1h, 1d).
2018-11-15 18:54:17 +00:00
--timerange TIMERANGE
2019-03-04 06:24:41 +00:00
Specify what timerange of data to use.
2019-04-22 19:11:56 +00:00
--max_open_trades MAX_OPEN_TRADES
Specify max_open_trades to use.
--stake_amount STAKE_AMOUNT
Specify stake_amount.
2018-11-15 18:54:17 +00:00
-r, --refresh-pairs-cached
2019-03-04 06:24:41 +00:00
Refresh the pairs files in tests/testdata with the
2018-11-15 18:54:17 +00:00
latest data from the exchange. Use it if you want to
2019-04-22 19:11:56 +00:00
run your optimization commands with up-to-date data.
2018-11-15 18:54:17 +00:00
--stoplosses STOPLOSS_RANGE
2019-03-04 06:24:41 +00:00
Defines a range of stoploss against which edge will
assess the strategy the format is "min,max,step"
2018-11-15 18:54:17 +00:00
(without any space).example:
--stoplosses=-0.01,-0.1,-0.001
```
To understand edge and how to read the results, please read the [edge documentation](edge.md).
2018-01-02 02:17:10 +00:00
## Next step
2018-11-15 18:54:17 +00:00
The optimal strategy of the bot will change with time depending of the market trends. The next step is to
2019-05-19 07:07:43 +00:00
[Strategy Customization](strategy-customization.md).