diff --git a/docs/configuration.md b/docs/configuration.md index e1c7e77d5..5d4b1f2c3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -5,11 +5,11 @@ By default, these settings are configured via the configuration file (see below) ## The Freqtrade configuration file -The bot uses a set of configuration parameters during its operation that all together conform the bot configuration. It normally reads its configuration from a file (Freqtrade configuration file). +The bot uses a set of configuration parameters during its operation that all together conform to the bot configuration. It normally reads its configuration from a file (Freqtrade configuration file). Per default, the bot loads the configuration from the `config.json` file, located in the current working directory. -You can specify a different configuration file used by the bot with the `-c/--config` command line option. +You can specify a different configuration file used by the bot with the `-c/--config` command-line option. Multiple configuration files can be specified and used by the bot or the bot can read its configuration parameters from the process standard input stream. @@ -25,30 +25,30 @@ Multiple configuration files can be specified and used by the bot or the bot can If you used the [Quick start](installation.md/#quick-start) method for installing the bot, the installation script should have already created the default configuration file (`config.json`) for you. -If default configuration file is not created we recommend you to use `freqtrade new-config --config config.json` to generate a basic configuration file. +If the default configuration file is not created we recommend you to use `freqtrade new-config --config config.json` to generate a basic configuration file. -The Freqtrade configuration file is to be written in the JSON format. +The Freqtrade configuration file is to be written in JSON format. Additionally to the standard JSON syntax, you may use one-line `// ...` and multi-line `/* ... */` comments in your configuration files and trailing commas in the lists of parameters. -Do not worry if you are not familiar with JSON format -- simply open the configuration file with an editor of your choice, make some changes to the parameters you need, save your changes and, finally, restart the bot or, if it was previously stopped, run it again with the changes you made to the configuration. The bot validates syntax of the configuration file at startup and will warn you if you made any errors editing it, pointing out problematic lines. +Do not worry if you are not familiar with JSON format -- simply open the configuration file with an editor of your choice, make some changes to the parameters you need, save your changes and, finally, restart the bot or, if it was previously stopped, run it again with the changes you made to the configuration. The bot validates the syntax of the configuration file at startup and will warn you if you made any errors editing it, pointing out problematic lines. ## Configuration parameters The table below will list all configuration parameters available. Freqtrade can also load many options via command line (CLI) arguments (check out the commands `--help` output for details). -The prevelance for all Options is as follows: +The prevalence for all Options is as follows: - CLI arguments override any other option -- Configuration files are used in sequence (last file wins), and override Strategy configurations. -- Strategy configurations are only used if they are not set via configuration or via command line arguments. These options are marked with [Strategy Override](#parameters-in-the-strategy) in the below table. +- Configuration files are used in sequence (the last file wins) and override Strategy configurations. +- Strategy configurations are only used if they are not set via configuration or command-line arguments. These options are marked with [Strategy Override](#parameters-in-the-strategy) in the below table. Mandatory parameters are marked as **Required**, which means that they are required to be set in one of the possible ways. | Parameter | Description | |------------|-------------| -| `max_open_trades` | **Required.** Number of open trades your bot is allowed to have. Only one open trade per pair is possible, so the length of your pairlist is another limitation which can apply. If -1 then it is ignored (i.e. potentially unlimited open trades, limited by the pairlist). [More information below](#configuring-amount-per-trade).
**Datatype:** Positive integer or -1. +| `max_open_trades` | **Required.** Number of open trades your bot is allowed to have. Only one open trade per pair is possible, so the length of your pairlist is another limitation that can apply. If -1 then it is ignored (i.e. potentially unlimited open trades, limited by the pairlist). [More information below](#configuring-amount-per-trade).
**Datatype:** Positive integer or -1. | `stake_currency` | **Required.** Crypto-currency used for trading.
**Datatype:** String | `stake_amount` | **Required.** Amount of crypto-currency your bot will use for each trade. Set it to `"unlimited"` to allow the bot to use all available balance. [More information below](#configuring-amount-per-trade).
**Datatype:** Positive float or `"unlimited"`. | `tradable_balance_ratio` | Ratio of the total account balance the bot is allowed to trade. [More information below](#configuring-amount-per-trade).
*Defaults to `0.99` 99%).*
**Datatype:** Positive float between `0.1` and `1.0`. @@ -141,7 +141,7 @@ Mandatory parameters are marked as **Required**, which means that they are requi ### Parameters in the strategy -The following parameters can be set in configuration file or strategy. +The following parameters can be set in the configuration file or strategy. Values set in the configuration file always overwrite values set in the strategy. * `minimal_roi` @@ -169,15 +169,15 @@ There are several methods to configure how much of the stake currency the bot wi #### Minimum trade stake -The minimum stake amount will depend by exchange and pair, and is usually listed in the exchange support pages. +The minimum stake amount will depend on exchange and pair and is usually listed in the exchange support pages. Assuming the minimum tradable amount for XRP/USD is 20 XRP (given by the exchange), and the price is 0.6$. -The minimum stake amount to buy this pair is therefore `20 * 0.6 ~= 12`. +The minimum stake amount to buy this pair is, therefore, `20 * 0.6 ~= 12`. This exchange has also a limit on USD - where all orders must be > 10$ - which however does not apply in this case. To guarantee safe execution, freqtrade will not allow buying with a stake-amount of 10.1$, instead, it'll make sure that there's enough space to place a stoploss below the pair (+ an offset, defined by `amount_reserve_percent`, which defaults to 5%). -With a reserve of 5%, the minimum stake amount would be ~12.6$ (`12 * (1 + 0.05)`). If we take in account a stoploss of 10% on top of that - we'd end up with a value of ~14$ (`12.6 / (1 - 0.1)`). +With a reserve of 5%, the minimum stake amount would be ~12.6$ (`12 * (1 + 0.05)`). If we take into account a stoploss of 10% on top of that - we'd end up with a value of ~14$ (`12.6 / (1 - 0.1)`). To limit this calculation in case of large stoploss values, the calculated minimum stake-limit will never be more than 50% above the real limit. @@ -191,13 +191,13 @@ Freqtrade will reserve 1% for eventual fees when entering a trade and will there You can configure the "untouched" amount by using the `tradable_balance_ratio` setting. -For example, if you have 10 ETH available in your wallet on the exchange and `tradable_balance_ratio=0.5` (which is 50%), then the bot will use a maximum amount of 5 ETH for trading and considers this as available balance. The rest of the wallet is untouched by the trades. +For example, if you have 10 ETH available in your wallet on the exchange and `tradable_balance_ratio=0.5` (which is 50%), then the bot will use a maximum amount of 5 ETH for trading and considers this as an available balance. The rest of the wallet is untouched by the trades. !!! Danger This setting should **not** be used when running multiple bots on the same account. Please look at [Available Capital to the bot](#assign-available-capital) instead. !!! Warning - The `tradable_balance_ratio` setting applies to the current balance (free balance + tied up in trades). Therefore, assuming the starting balance of 1000, a configuration with `tradable_balance_ratio=0.99` will not guarantee that 10 currency units will always remain available on the exchange. For example, the free amount may reduce to 5 units if the total balance is reduced to 500 (either by a losing streak, or by withdrawing balance). + The `tradable_balance_ratio` setting applies to the current balance (free balance + tied up in trades). Therefore, assuming the starting balance of 1000, a configuration with `tradable_balance_ratio=0.99` will not guarantee that 10 currency units will always remain available on the exchange. For example, the free amount may reduce to 5 units if the total balance is reduced to 500 (either by a losing streak or by withdrawing balance). #### Assign available Capital @@ -207,7 +207,7 @@ This can be accomplished by setting `available_capital` to the desired starting Assuming your account has 10.000 USDT and you want to run 2 different strategies on this exchange. You'd set `available_capital=5000` - granting each bot an initial capital of 5000 USDT. The bot will then split this starting balance equally into `max_open_trades` buckets. -Profitable trades will result in increased stake-sizes for this bot - without affecting stake-sizes of the other bot. +Profitable trades will result in increased stake-sizes for this bot - without affecting the stake-sizes of the other bot. !!! Warning "Incompatible with `tradable_balance_ratio`" Setting this option will replace any configuration of `tradable_balance_ratio`. @@ -215,9 +215,9 @@ Profitable trades will result in increased stake-sizes for this bot - without af #### Amend last stake amount Assuming we have the tradable balance of 1000 USDT, `stake_amount=400`, and `max_open_trades=3`. -The bot would open 2 trades, and will be unable to fill the last trading slot, since the requested 400 USDT are no longer available, since 800 USDT are already tied in other trades. +The bot would open 2 trades and will be unable to fill the last trading slot, since the requested 400 USDT are no longer available since 800 USDT are already tied in other trades. -To overcome this, the option `amend_last_stake_amount` can be set to `True`, which will enable the bot to reduce stake_amount to the available balance in order to fill the last trade slot. +To overcome this, the option `amend_last_stake_amount` can be set to `True`, which will enable the bot to reduce stake_amount to the available balance to fill the last trade slot. In the example above this would mean: @@ -245,7 +245,7 @@ For example, the bot will at most use (0.05 BTC x 3) = 0.15 BTC, assuming a conf #### Dynamic stake amount -Alternatively, you can use a dynamic stake amount, which will use the available balance on the exchange, and divide that equally by the amount of allowed trades (`max_open_trades`). +Alternatively, you can use a dynamic stake amount, which will use the available balance on the exchange, and divide that equally by the number of allowed trades (`max_open_trades`). To configure this, set `stake_amount="unlimited"`. We also recommend to set `tradable_balance_ratio=0.99` (99%) - to keep a minimum balance for eventual fees. @@ -263,18 +263,18 @@ To allow the bot to trade all the available `stake_currency` in your account (mi ``` !!! Tip "Compounding profits" - This configuration will allow increasing / decreasing stakes depending on the performance of the bot (lower stake if bot is loosing, higher stakes if the bot has a winning record, since higher balances are available), and will result in profit compounding. + This configuration will allow increasing/decreasing stakes depending on the performance of the bot (lower stake if the bot is losing, higher stakes if the bot has a winning record since higher balances are available), and will result in profit compounding. !!! Note "When using Dry-Run Mode" - When using `"stake_amount" : "unlimited",` in combination with Dry-Run, Backtesting or Hyperopt, the balance will be simulated starting with a stake of `dry_run_wallet` which will evolve over time. - It is therefore important to set `dry_run_wallet` to a sensible value (like 0.05 or 0.01 for BTC and 1000 or 100 for USDT, for example), otherwise it may simulate trades with 100 BTC (or more) or 0.05 USDT (or less) at once - which may not correspond to your real available balance or is less than the exchange minimal limit for the order amount for the stake currency. + When using `"stake_amount" : "unlimited",` in combination with Dry-Run, Backtesting or Hyperopt, the balance will be simulated starting with a stake of `dry_run_wallet` which will evolve. + It is therefore important to set `dry_run_wallet` to a sensible value (like 0.05 or 0.01 for BTC and 1000 or 100 for USDT, for example), otherwise, it may simulate trades with 100 BTC (or more) or 0.05 USDT (or less) at once - which may not correspond to your real available balance or is less than the exchange minimal limit for the order amount for the stake currency. --8<-- "includes/pricing.md" ### Understand minimal_roi The `minimal_roi` configuration parameter is a JSON object where the key is a duration -in minutes and the value is the minimum ROI as ratio. +in minutes and the value is the minimum ROI as a ratio. See the example below: ```json @@ -289,7 +289,7 @@ See the example below: Most of the strategy files already include the optimal `minimal_roi` value. This parameter can be set in either Strategy or Configuration file. If you use it in the configuration file, it will override the `minimal_roi` value from the strategy file. -If it is not set in either Strategy or Configuration, a default of 1000% `{"0": 10}` is used, and minimal roi is disabled unless your trade generates 1000% profit. +If it is not set in either Strategy or Configuration, a default of 1000% `{"0": 10}` is used, and minimal ROI is disabled unless your trade generates 1000% profit. !!! Note "Special case to forcesell after a specific time" A special case presents using `"": -1` as ROI. This forces the bot to sell a trade after N Minutes, no matter if it's positive or negative, so represents a time-limited force-sell. @@ -335,7 +335,7 @@ the buy order is fulfilled. `order_types` set in the configuration file overwrites values set in the strategy as a whole, so you need to configure the whole `order_types` dictionary in one place. If this is configured, the following 4 values (`buy`, `sell`, `stoploss` and -`stoploss_on_exchange`) need to be present, otherwise the bot will fail to start. +`stoploss_on_exchange`) need to be present, otherwise, the bot will fail to start. For information on (`emergencysell`,`forcesell`, `forcebuy`, `stoploss_on_exchange`,`stoploss_on_exchange_interval`,`stoploss_on_exchange_limit_ratio`) please see stop loss documentation [stop loss on exchange](stoploss.md) @@ -386,7 +386,7 @@ Configuration: If `stoploss_on_exchange` is enabled and the stoploss is cancelled manually on the exchange, then the bot will create a new stoploss order. !!! Warning "Warning: stoploss_on_exchange failures" - If stoploss on exchange creation fails for some reason, then an "emergency sell" is initiated. By default, this will sell the asset using a market order. The order-type for the emergency-sell can be changed by setting the `emergencysell` value in the `order_types` dictionary - however this is not advised. + If stoploss on exchange creation fails for some reason, then an "emergency sell" is initiated. By default, this will sell the asset using a market order. The order-type for the emergency-sell can be changed by setting the `emergencysell` value in the `order_types` dictionary - however, this is not advised. ### Understand order_time_in_force @@ -396,12 +396,12 @@ is executed on the exchange. Three commonly used time in force are: **GTC (Good Till Canceled):** This is most of the time the default time in force. It means the order will remain -on exchange till it is canceled by user. It can be fully or partially fulfilled. +on exchange till it is cancelled by the user. It can be fully or partially fulfilled. If partially fulfilled, the remaining will stay on the exchange till cancelled. **FOK (Fill Or Kill):** -It means if the order is not executed immediately AND fully then it is canceled by the exchange. +It means if the order is not executed immediately AND fully then it is cancelled by the exchange. **IOC (Immediate Or Canceled):** @@ -422,7 +422,7 @@ The possible values are: `gtc` (default), `fok` or `ioc`. ``` !!! Warning - This is an ongoing work. For now it is supported only for binance. + This is ongoing work. For now, it is supported only for binance. Please don't change the default value unless you know what you are doing and have researched the impact of using different values. ### Exchange configuration @@ -431,7 +431,7 @@ Freqtrade is based on [CCXT library](https://github.com/ccxt/ccxt) that supports exchange markets and trading APIs. The complete up-to-date list can be found in the [CCXT repo homepage](https://github.com/ccxt/ccxt/tree/master/python). However, the bot was tested by the development team with only Bittrex, Binance and Kraken, - so the these are the only officially supported exchanges: + so these are the only officially supported exchanges: - [Bittrex](https://bittrex.com/): "bittrex" - [Binance](https://www.binance.com/): "binance" @@ -457,11 +457,11 @@ A exchange configuration for "binance" would look as follows: }, ``` -This configuration enables binance, as well as rate limiting to avoid bans from the exchange. +This configuration enables binance, as well as rate-limiting to avoid bans from the exchange. `"rateLimit": 200` defines a wait-event of 0.2s between each call. This can also be completely disabled by setting `"enableRateLimit"` to false. !!! Note - Optimal settings for rate limiting depend on the exchange and the size of the whitelist, so an ideal parameter will vary on many other settings. + Optimal settings for rate-limiting depend on the exchange and the size of the whitelist, so an ideal parameter will vary on many other settings. We try to provide sensible defaults per exchange where possible, if you encounter bans please make sure that `"enableRateLimit"` is enabled and increase the `"rateLimit"` parameter step by step. ### What values can be used for fiat_display_currency? @@ -475,7 +475,7 @@ The valid values are: "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "CZK", "DKK", "EUR", "GBP", "HKD", "HUF", "IDR", "ILS", "INR", "JPY", "KRW", "MXN", "MYR", "NOK", "NZD", "PHP", "PKR", "PLN", "RUB", "SEK", "SGD", "THB", "TRY", "TWD", "ZAR", "USD" ``` -In addition to fiat currencies, a range of cryto currencies are supported. +In addition to fiat currencies, a range of crypto currencies is supported. The valid values are: @@ -486,7 +486,7 @@ The valid values are: ## Using Dry-run mode We recommend starting the bot in the Dry-run mode to see how your bot will -behave and what is the performance of your strategy. In the Dry-run mode the +behave and what is the performance of your strategy. In the Dry-run mode, the bot does not engage your money. It only runs a live simulation without creating trades on the exchange. @@ -512,7 +512,7 @@ creating trades on the exchange. Once you will be happy with your bot performance running in the Dry-run mode, you can switch it to production mode. !!! Note - A simulated wallet is available during dry-run mode, and will assume a starting capital of `dry_run_wallet` (defaults to 1000). + A simulated wallet is available during dry-run mode and will assume a starting capital of `dry_run_wallet` (defaults to 1000). ### Considerations for dry-run @@ -520,7 +520,7 @@ Once you will be happy with your bot performance running in the Dry-run mode, yo * Wallets (`/balance`) are simulated based on `dry_run_wallet`. * Orders are simulated, and will not be posted to the exchange. * Market orders fill based on orderbook volume the moment the order is placed. -* Limit orders fill once price reaches the defined level - or time out based on `unfilledtimeout` settings. +* Limit orders fill once the price reaches the defined level - or time out based on `unfilledtimeout` settings. * In combination with `stoploss_on_exchange`, the stop_loss price is assumed to be filled. * Open orders (not trades, which are stored in the database) are reset on bot restart. @@ -533,7 +533,7 @@ you run it in production mode. ### Setup your exchange account You will need to create API Keys (usually you get `key` and `secret`, some exchanges require an additional `password`) from the Exchange website and you'll need to insert this into the appropriate fields in the configuration or when asked by the `freqtrade new-config` command. -API Keys are usually only required for live trading (trading for real money, bot running in "production mode", executing real orders on the exchange) and are not required for the bot running in dry-run (trade simulation) mode. When you setup the bot in dry-run mode, you may fill these fields with empty values. +API Keys are usually only required for live trading (trading for real money, bot running in "production mode", executing real orders on the exchange) and are not required for the bot running in dry-run (trade simulation) mode. When you set up the bot in dry-run mode, you may fill these fields with empty values. ### To switch your bot in production mode @@ -545,7 +545,7 @@ API Keys are usually only required for live trading (trading for real money, bot "dry_run": false, ``` -**Insert your Exchange API key (change them by fake api keys):** +**Insert your Exchange API key (change them by fake API keys):** ```json { @@ -563,7 +563,7 @@ API Keys are usually only required for live trading (trading for real money, bot You should also make sure to read the [Exchanges](exchanges.md) section of the documentation to be aware of potential configuration details specific to your exchange. !!! Hint "Keep your secrets secret" - To keep your secrets secret, we recommend to use a 2nd configuration for your API keys. + To keep your secrets secret, we recommend using a 2nd configuration for your API keys. Simply use the above snippet in a new configuration file (e.g. `config-private.json`) and keep your settings in this file. You can then start the bot with `freqtrade trade --config user_data/config.json --config user_data/config-private.json <...>` to have your keys loaded.