From 2714c028421b10f6f9965284b0cabe5564b2cccb Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Mon, 4 Oct 2021 01:31:28 -0600 Subject: [PATCH 1/8] Added docs for leverage and trading mode --- docs/configuration.md | 98 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index bc8a40dcb..ba8995044 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -90,6 +90,8 @@ Mandatory parameters are marked as **Required**, which means that they are requi | `trailing_stop_positive_offset` | Offset on when to apply `trailing_stop_positive`. Percentage value which should be positive. More details in the [stoploss documentation](stoploss.md#trailing-stop-loss-only-once-the-trade-has-reached-a-certain-offset). [Strategy Override](#parameters-in-the-strategy).
*Defaults to `0.0` (no offset).*
**Datatype:** Float | `trailing_only_offset_is_reached` | Only apply trailing stoploss when the offset is reached. [stoploss documentation](stoploss.md). [Strategy Override](#parameters-in-the-strategy).
*Defaults to `false`.*
**Datatype:** Boolean | `fee` | Fee used during backtesting / dry-runs. Should normally not be configured, which has freqtrade fall back to the exchange default fee. Set as ratio (e.g. 0.001 = 0.1%). Fee is applied twice for each trade, once when buying, once when selling.
**Datatype:** Float (as ratio) +| `trading_mode` | Specifies if you want to trade regularly, trade with leverage, or trade contracts whose prices are derived from matching cryptocurrency prices. spot, margin or futures +| `collateral` | When trading with leverage, this determines if the collateral owned by the trader will be shared or isolated to each trading pair | `unfilledtimeout.buy` | **Required.** How long (in minutes or seconds) the bot will wait for an unfilled buy order to complete, after which the order will be cancelled and repeated at current (new) price, as long as there is a signal. [Strategy Override](#parameters-in-the-strategy).
**Datatype:** Integer | `unfilledtimeout.sell` | **Required.** How long (in minutes or seconds) the bot will wait for an unfilled sell order to complete, after which the order will be cancelled and repeated at current (new) price, as long as there is a signal. [Strategy Override](#parameters-in-the-strategy).
**Datatype:** Integer | `unfilledtimeout.unit` | Unit to use in unfilledtimeout setting. Note: If you set unfilledtimeout.unit to "seconds", "internals.process_throttle_secs" must be inferior or equal to timeout [Strategy Override](#parameters-in-the-strategy).
*Defaults to `minutes`.*
**Datatype:** String @@ -447,6 +449,100 @@ The possible values are: `gtc` (default), `fok` or `ioc`. This is ongoing work. For now, it is supported only for binance and kucoin. Please don't change the default value unless you know what you are doing and have researched the impact of using different values for your particular exchange. +### Understand trading_mode + +The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. + +**SPOT** + Regular trading mode. + - Shorting is not available + - There is no liquidation price + - Profits gained/lost are equal to the change in value of the assets(minus trading fees) + +#### Leverage trading modes + +!!! Warning: Trading with leverage(`trading_mode="margin"` or `trading_mode="futures"`) is very risky. +!!! Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market +!!! Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount + +> I've only been using freqtrade for a couple weeks, but I feel like I'm pretty good and could use leverage + +!!! No you're not. Do not use leverage yet. + +# TODO: include a resource to help calculate stoplosses that are above the liquidation price + +#TODO: Taken from investopedia, is that ok? +Leverage results from using borrowed capital as a funding source when investing to expand the firm's asset base and generate returns on risk capital. Leverage is an investment strategy of using borrowed money—specifically, the use of various financial instruments or borrowed capital—to increase the potential return of an investment. + + +**MARGIN** +*coming soon* + Trading occurs on the spot market, but the exchange lends currency to you in an amount equal to the chosen leverage. You pay the amount lent to you back to the exchange with interest, and your profits/losses are multiplied by the leverage specified + +**FUTURES** +*Freqtrade can only trade **perpetual futures*** + + Perpetual futures contracts are traded at a price that mirrors the underlying asset they are based off of. You are not trading the actual asset but instead are trading a derivative contract. In contract to regular futures contracts, perpetual futures can last indefinately. + + In addition to the gains/losses from the change in price of the futures contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the futures contract and the underlying asset. The difference in price between a futures contract and the underlying asset varies between exchanges. + + +``` python +"trading_mode": "spot" +``` + +### Collateral + +The possible values are: `isolated` (default), or `cross`(*coming soon*) + + # TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin +**ISOLATED** + +Margin assigned to a position is restricted to a certain amount. If the margin falls below the Maintenance Margin level, the position is liquidated. + +**CROSS** + +Margin is shared between open positions. When needed, a position will draw more margin from the total account balance to avoid liquidation. + +### Exchange configuration + +Freqtrade is based on [CCXT library](https://github.com/ccxt/ccxt) that supports over 100 cryptocurrency +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 these are the only officially supported exchanges: + +- [Bittrex](https://bittrex.com/): "bittrex" +- [Binance](https://www.binance.com/): "binance" +- [Kraken](https://kraken.com/): "kraken" + +Feel free to test other exchanges and submit your PR to improve the bot. + +Some exchanges require special configuration, which can be found on the [Exchange-specific Notes](exchanges.md) documentation page. + +#### Sample exchange configuration + +A exchange configuration for "binance" would look as follows: + +```json +"exchange": { + "name": "binance", + "key": "your_exchange_key", + "secret": "your_exchange_secret", + "ccxt_config": {"enableRateLimit": true}, + "ccxt_async_config": { + "enableRateLimit": true, + "rateLimit": 200 + }, +``` + +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. + 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? The `fiat_display_currency` configuration parameter sets the base currency to use for the @@ -485,7 +581,7 @@ creating trades on the exchange. ```json "exchange": { - "name": "bittrex", + "name": "bittrex", "key": "key", "secret": "secret", ... From 449710d66232d8ac6d43bc9301450301b31e0699 Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Mon, 4 Oct 2021 01:36:26 -0600 Subject: [PATCH 2/8] Added collateral example --- docs/configuration.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index ba8995044..84d688020 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -488,14 +488,14 @@ Leverage results from using borrowed capital as a funding source when investing ``` python -"trading_mode": "spot" +"trading_mode": "futures" ``` ### Collateral -The possible values are: `isolated` (default), or `cross`(*coming soon*) +The possible values are: `isolated`, or `cross`(*coming soon*) - # TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin +# TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin **ISOLATED** Margin assigned to a position is restricted to a certain amount. If the margin falls below the Maintenance Margin level, the position is liquidated. @@ -504,6 +504,10 @@ Margin assigned to a position is restricted to a certain amount. If the margin f Margin is shared between open positions. When needed, a position will draw more margin from the total account balance to avoid liquidation. +``` python +"collateral": "isolated" +``` + ### Exchange configuration Freqtrade is based on [CCXT library](https://github.com/ccxt/ccxt) that supports over 100 cryptocurrency From 4a0a215c45364df9644e25ba0fcfeaa18f4d5d7b Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Tue, 5 Oct 2021 01:56:43 -0600 Subject: [PATCH 3/8] moved lev docs to own file, updated config --- docs/configuration.md | 63 ++------------------------------------- docs/leverage.md | 68 ++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 66 insertions(+), 65 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 84d688020..b7c010a01 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -90,8 +90,8 @@ Mandatory parameters are marked as **Required**, which means that they are requi | `trailing_stop_positive_offset` | Offset on when to apply `trailing_stop_positive`. Percentage value which should be positive. More details in the [stoploss documentation](stoploss.md#trailing-stop-loss-only-once-the-trade-has-reached-a-certain-offset). [Strategy Override](#parameters-in-the-strategy).
*Defaults to `0.0` (no offset).*
**Datatype:** Float | `trailing_only_offset_is_reached` | Only apply trailing stoploss when the offset is reached. [stoploss documentation](stoploss.md). [Strategy Override](#parameters-in-the-strategy).
*Defaults to `false`.*
**Datatype:** Boolean | `fee` | Fee used during backtesting / dry-runs. Should normally not be configured, which has freqtrade fall back to the exchange default fee. Set as ratio (e.g. 0.001 = 0.1%). Fee is applied twice for each trade, once when buying, once when selling.
**Datatype:** Float (as ratio) -| `trading_mode` | Specifies if you want to trade regularly, trade with leverage, or trade contracts whose prices are derived from matching cryptocurrency prices. spot, margin or futures -| `collateral` | When trading with leverage, this determines if the collateral owned by the trader will be shared or isolated to each trading pair +| `trading_mode` | Specifies if you want to trade regularly, trade with leverage, or trade contracts whose prices are derived from matching cryptocurrency prices. [leverage documentation](leverage.md).
*Defaults to `"spot"`.*
**Datatype:** String +| `collateral` | When trading with leverage, this determines if the collateral owned by the trader will be shared or isolated to each trading pair [leverage documentation](leverage.md).
**Datatype:** String | `unfilledtimeout.buy` | **Required.** How long (in minutes or seconds) the bot will wait for an unfilled buy order to complete, after which the order will be cancelled and repeated at current (new) price, as long as there is a signal. [Strategy Override](#parameters-in-the-strategy).
**Datatype:** Integer | `unfilledtimeout.sell` | **Required.** How long (in minutes or seconds) the bot will wait for an unfilled sell order to complete, after which the order will be cancelled and repeated at current (new) price, as long as there is a signal. [Strategy Override](#parameters-in-the-strategy).
**Datatype:** Integer | `unfilledtimeout.unit` | Unit to use in unfilledtimeout setting. Note: If you set unfilledtimeout.unit to "seconds", "internals.process_throttle_secs" must be inferior or equal to timeout [Strategy Override](#parameters-in-the-strategy).
*Defaults to `minutes`.*
**Datatype:** String @@ -449,65 +449,6 @@ The possible values are: `gtc` (default), `fok` or `ioc`. This is ongoing work. For now, it is supported only for binance and kucoin. Please don't change the default value unless you know what you are doing and have researched the impact of using different values for your particular exchange. -### Understand trading_mode - -The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. - -**SPOT** - Regular trading mode. - - Shorting is not available - - There is no liquidation price - - Profits gained/lost are equal to the change in value of the assets(minus trading fees) - -#### Leverage trading modes - -!!! Warning: Trading with leverage(`trading_mode="margin"` or `trading_mode="futures"`) is very risky. -!!! Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market -!!! Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount - -> I've only been using freqtrade for a couple weeks, but I feel like I'm pretty good and could use leverage - -!!! No you're not. Do not use leverage yet. - -# TODO: include a resource to help calculate stoplosses that are above the liquidation price - -#TODO: Taken from investopedia, is that ok? -Leverage results from using borrowed capital as a funding source when investing to expand the firm's asset base and generate returns on risk capital. Leverage is an investment strategy of using borrowed money—specifically, the use of various financial instruments or borrowed capital—to increase the potential return of an investment. - - -**MARGIN** -*coming soon* - Trading occurs on the spot market, but the exchange lends currency to you in an amount equal to the chosen leverage. You pay the amount lent to you back to the exchange with interest, and your profits/losses are multiplied by the leverage specified - -**FUTURES** -*Freqtrade can only trade **perpetual futures*** - - Perpetual futures contracts are traded at a price that mirrors the underlying asset they are based off of. You are not trading the actual asset but instead are trading a derivative contract. In contract to regular futures contracts, perpetual futures can last indefinately. - - In addition to the gains/losses from the change in price of the futures contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the futures contract and the underlying asset. The difference in price between a futures contract and the underlying asset varies between exchanges. - - -``` python -"trading_mode": "futures" -``` - -### Collateral - -The possible values are: `isolated`, or `cross`(*coming soon*) - -# TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin -**ISOLATED** - -Margin assigned to a position is restricted to a certain amount. If the margin falls below the Maintenance Margin level, the position is liquidated. - -**CROSS** - -Margin is shared between open positions. When needed, a position will draw more margin from the total account balance to avoid liquidation. - -``` python -"collateral": "isolated" -``` - ### Exchange configuration Freqtrade is based on [CCXT library](https://github.com/ccxt/ccxt) that supports over 100 cryptocurrency diff --git a/docs/leverage.md b/docs/leverage.md index 9448c64c3..13ddf1a86 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -1,21 +1,81 @@ # Leverage +*You can't run 2 bots on the same account with leverage,* + +!!! Warning: Trading with leverage(`trading_mode="margin"` or `trading_mode="futures"`) is very risky. +!!! Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market +!!! Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount + +> I've only been using freqtrade for a couple weeks, but I feel like I'm pretty good and could use leverage + +!!! No you're not. Do not use leverage yet. +### Understand trading_mode + +The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. + +**SPOT** + Regular trading mode. + - Shorting is not available + - There is no liquidation price + - Profits gained/lost are equal to the change in value of the assets(minus trading fees) + +#### Leverage trading modes + +# TODO: include a resource to help calculate stoplosses that are above the liquidation price + +#TODO: Taken from investopedia, is that ok? +Leverage results from using borrowed capital as a funding source when investing to expand the firm's asset base and generate returns on risk capital. Leverage is an investment strategy of using borrowed money—specifically, the use of various financial instruments or borrowed capital—to increase the potential return of an investment. + + +**MARGIN** +*coming soon* + Trading occurs on the spot market, but the exchange lends currency to you in an amount equal to the chosen leverage. You pay the amount lent to you back to the exchange with interest, and your profits/losses are multiplied by the leverage specified + +**FUTURES** +*Freqtrade can only trade **perpetual futures*** + + Perpetual futures contracts are traded at a price that mirrors the underlying asset they are based off of. You are not trading the actual asset but instead are trading a derivative contract. In contract to regular futures contracts, perpetual futures can last indefinately. + + In addition to the gains/losses from the change in price of the futures contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the futures contract and the underlying asset. The difference in price between a futures contract and the underlying asset varies between exchanges. + + +``` python +"trading_mode": "futures" +``` + +### Collateral + +The possible values are: `isolated`, or `cross`(*coming soon*) + +# TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin +**ISOLATED** + +Margin assigned to a position is restricted to a certain amount. If the margin falls below the Maintenance Margin level, the position is liquidated. + +**CROSS** + +Margin is shared between open positions. When needed, a position will draw more margin from the total account balance to avoid liquidation. + +``` python +"collateral": "isolated" +``` + +### Developer For shorts, the currency which pays the interest fee for the `borrowed` currency is purchased at the same time of the closing trade (This means that the amount purchased in short closing trades is greater than the amount sold in short opening trades). For longs, the currency which pays the interest fee for the `borrowed` will already be owned by the user and does not need to be purchased. The interest is subtracted from the close_value of the trade. -## Binance margin trading interest formula +#### Binance margin trading interest formula I (interest) = P (borrowed money) * R (daily_interest/24) * ceiling(T) (in hours) [source](https://www.binance.com/en/support/faq/360030157812) -## Kraken margin trading interest formula +#### Kraken margin trading interest formula Opening fee = P (borrowed money) * R (quat_hourly_interest) Rollover fee = P (borrowed money) * R (quat_hourly_interest) * ceiling(T/4) (in hours) I (interest) = Opening fee + Rollover fee [source](https://support.kraken.com/hc/en-us/articles/206161568-What-are-the-fees-for-margin-trading-) -# TODO-lev: Mention that says you can't run 2 bots on the same account with leverage, -#TODO-lev: Create a huge risk disclaimer \ No newline at end of file + From 68810eb4f32def24085a3b91a6ebbb332aea48f1 Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Tue, 5 Oct 2021 03:23:56 -0600 Subject: [PATCH 4/8] Fixed warning --- docs/leverage.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/leverage.md b/docs/leverage.md index 13ddf1a86..8594ea719 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -1,13 +1,12 @@ # Leverage -*You can't run 2 bots on the same account with leverage,* +*You can't run 2 bots on the same account with leverage* -!!! Warning: Trading with leverage(`trading_mode="margin"` or `trading_mode="futures"`) is very risky. -!!! Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market -!!! Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount +!!! Warning "Trading with leverage is very risky" + *(`trading_mode="margin"` or `trading_mode="futures"`)* Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market. Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount > I've only been using freqtrade for a couple weeks, but I feel like I'm pretty good and could use leverage -!!! No you're not. Do not use leverage yet. +**No you're not. Do not use leverage yet.** ### Understand trading_mode The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. From b4de68e1bcb4ede8c1b6dae3eda6052d73f6c071 Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Fri, 5 Nov 2021 01:40:32 -0600 Subject: [PATCH 5/8] Updated docs to include liquidation, own definitions --- docs/leverage.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/leverage.md b/docs/leverage.md index 8594ea719..7a5fb5e3e 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -19,22 +19,21 @@ The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. #### Leverage trading modes -# TODO: include a resource to help calculate stoplosses that are above the liquidation price +# TODO-lev: include a resource to help calculate stoplosses that are above the liquidation price -#TODO: Taken from investopedia, is that ok? -Leverage results from using borrowed capital as a funding source when investing to expand the firm's asset base and generate returns on risk capital. Leverage is an investment strategy of using borrowed money—specifically, the use of various financial instruments or borrowed capital—to increase the potential return of an investment. +With leverage, a trader borrows capital from the exchange. The capital must be repayed fully to the exchange(potentially with interest), and the trader keeps any profits, or pays any losses, from any trades made using the borrowed capital. +Because the capital must always be repayed, exchanges will **liquidate** a trade (forcefully sell the traders assets) made using borrowed capital when the total value of assets in a leverage account drops to a certain point(a point where the total value of losses is less than the value of the collateral that the trader actually owns in the leverage account), in order to ensure that the trader has enough capital to pay back the borrowed assets to the exchange. The exchange will also charge a **liquidation fee**, adding to the traders losses. For this reason, **DO NOT TRADE WITH LEVERAGE IF YOU DON'T KNOW EXACTLY WHAT YOUR DOING. LEVERAGE TRADING IS HIGH RISK, AND CAN RESULT IN THE VALUE OF YOUR ASSETS DROPPING TO 0 VERY QUICKLY, WITH NO CHANCE OF INCREASING IN VALUE AGAIN** **MARGIN** -*coming soon* +*Currently unavailable* Trading occurs on the spot market, but the exchange lends currency to you in an amount equal to the chosen leverage. You pay the amount lent to you back to the exchange with interest, and your profits/losses are multiplied by the leverage specified -**FUTURES** -*Freqtrade can only trade **perpetual futures*** +**Perpetual Swaps (also known as Perpetual Futures)** - Perpetual futures contracts are traded at a price that mirrors the underlying asset they are based off of. You are not trading the actual asset but instead are trading a derivative contract. In contract to regular futures contracts, perpetual futures can last indefinately. +Perpetual swaps are contracts traded at a price that is closely tied to the underlying asset they are based off of(ex. ). You are not trading the actual asset but instead are trading a derivative contract. Perpetual swap contracts can last indefinately, in contrast to futures or option contracts. - In addition to the gains/losses from the change in price of the futures contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the futures contract and the underlying asset. The difference in price between a futures contract and the underlying asset varies between exchanges. +In addition to the gains/losses from the change in price of the contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the contract and the underlying asset. The difference in price between a contract and the underlying asset varies between exchanges. ``` python @@ -48,11 +47,10 @@ The possible values are: `isolated`, or `cross`(*coming soon*) # TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin **ISOLATED** -Margin assigned to a position is restricted to a certain amount. If the margin falls below the Maintenance Margin level, the position is liquidated. +Each market(trading pair), keeps collateral in a separate account **CROSS** - -Margin is shared between open positions. When needed, a position will draw more margin from the total account balance to avoid liquidation. +One account is used to share collateral between markets (trading pairs). Margin is taken from total account balance to avoid liquidation when needed. ``` python "collateral": "isolated" @@ -60,6 +58,8 @@ Margin is shared between open positions. When needed, a position will draw more ### Developer +**Margin mode** + For shorts, the currency which pays the interest fee for the `borrowed` currency is purchased at the same time of the closing trade (This means that the amount purchased in short closing trades is greater than the amount sold in short opening trades). For longs, the currency which pays the interest fee for the `borrowed` will already be owned by the user and does not need to be purchased. The interest is subtracted from the close_value of the trade. @@ -76,5 +76,7 @@ For longs, the currency which pays the interest fee for the `borrowed` will alre I (interest) = Opening fee + Rollover fee [source](https://support.kraken.com/hc/en-us/articles/206161568-What-are-the-fees-for-margin-trading-) +**FUTURES MODE** +Funding fees are either added or subtracted from the total amount of a trade From b620d46958007927c874a76721b28c9bc92073bd Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Fri, 5 Nov 2021 01:47:58 -0600 Subject: [PATCH 6/8] Updated formatting leverage.md --- docs/leverage.md | 75 +++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 30 deletions(-) diff --git a/docs/leverage.md b/docs/leverage.md index 7a5fb5e3e..900164867 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -1,21 +1,28 @@ -# Leverage -*You can't run 2 bots on the same account with leverage* +!!! Warning "Beta feature" + This feature is still in it's testing phase. Should you notice something you think is wrong please let us know via Discord or via Github Issue. -!!! Warning "Trading with leverage is very risky" - *(`trading_mode="margin"` or `trading_mode="futures"`)* Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market. Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that amount +!!! Note "Multiple bots on one account" + You can't run 2 bots on the same account with leverage. For leveraged / margin trading, freqtrade assumes it's the only user of the account, and all liquidation levels are calculated based on this assumption. -> I've only been using freqtrade for a couple weeks, but I feel like I'm pretty good and could use leverage +!!! Danger "Trading with leverage is very risky" + Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market. Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that stoploss. + We do not assume any responsibility for eventual losses that occur from using this software or this mode. -**No you're not. Do not use leverage yet.** -### Understand trading_mode + Please only use advanced trading modes when you know how freqtrade (and your strategy) works. + Also, never risk more than what you can afford to lose. + +## Understand `trading_mode` The possible values are: `spot` (default), `margin`(*coming soon*) or `futures`. -**SPOT** - Regular trading mode. - - Shorting is not available - - There is no liquidation price - - Profits gained/lost are equal to the change in value of the assets(minus trading fees) +### Spot + +Regular trading mode (low risk) + +- Long trades only (No short trades). +- No leverage. +- No Liquidation. +- Profits gained/lost are equal to the change in value of the assets (minus trading fees). #### Leverage trading modes @@ -25,58 +32,66 @@ With leverage, a trader borrows capital from the exchange. The capital must be r Because the capital must always be repayed, exchanges will **liquidate** a trade (forcefully sell the traders assets) made using borrowed capital when the total value of assets in a leverage account drops to a certain point(a point where the total value of losses is less than the value of the collateral that the trader actually owns in the leverage account), in order to ensure that the trader has enough capital to pay back the borrowed assets to the exchange. The exchange will also charge a **liquidation fee**, adding to the traders losses. For this reason, **DO NOT TRADE WITH LEVERAGE IF YOU DON'T KNOW EXACTLY WHAT YOUR DOING. LEVERAGE TRADING IS HIGH RISK, AND CAN RESULT IN THE VALUE OF YOUR ASSETS DROPPING TO 0 VERY QUICKLY, WITH NO CHANCE OF INCREASING IN VALUE AGAIN** -**MARGIN** +#### MARGIN *Currently unavailable* Trading occurs on the spot market, but the exchange lends currency to you in an amount equal to the chosen leverage. You pay the amount lent to you back to the exchange with interest, and your profits/losses are multiplied by the leverage specified -**Perpetual Swaps (also known as Perpetual Futures)** +#### FUTURES -Perpetual swaps are contracts traded at a price that is closely tied to the underlying asset they are based off of(ex. ). You are not trading the actual asset but instead are trading a derivative contract. Perpetual swap contracts can last indefinately, in contrast to futures or option contracts. +Perpetual swaps (also known as Perpetual Futures) are contracts traded at a price that is closely tied to the underlying asset they are based off of(ex. ). You are not trading the actual asset but instead are trading a derivative contract. Perpetual swap contracts can last indefinately, in contrast to futures or option contracts. In addition to the gains/losses from the change in price of the contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the contract and the underlying asset. The difference in price between a contract and the underlying asset varies between exchanges. -``` python +``` json "trading_mode": "futures" ``` ### Collateral -The possible values are: `isolated`, or `cross`(*coming soon*) +The possible values are: `isolated`, or `cross`(*currently unavailable*) -# TODO: I took this definition from bitmex, is that fine? https://www.bitmex.com/app/isolatedMargin -**ISOLATED** +#### ISOLATED Each market(trading pair), keeps collateral in a separate account -**CROSS** +#### CROSS +*currently unavailable* One account is used to share collateral between markets (trading pairs). Margin is taken from total account balance to avoid liquidation when needed. -``` python +``` json "collateral": "isolated" ``` ### Developer -**Margin mode** +#### Margin mode For shorts, the currency which pays the interest fee for the `borrowed` currency is purchased at the same time of the closing trade (This means that the amount purchased in short closing trades is greater than the amount sold in short opening trades). -For longs, the currency which pays the interest fee for the `borrowed` will already be owned by the user and does not need to be purchased. The interest is subtracted from the close_value of the trade. +For longs, the currency which pays the interest fee for the `borrowed` will already be owned by the user and does not need to be purchased. The interest is subtracted from the `close_value` of the trade. + +All Fees are included in `current_profit` calculations during the trade. #### Binance margin trading interest formula - I (interest) = P (borrowed money) * R (daily_interest/24) * ceiling(T) (in hours) - [source](https://www.binance.com/en/support/faq/360030157812) +$$ +I (interest) = P (borrowed money) * R (daily_interest/24) * ceiling(T) (in hours) +$$ + +[source](https://www.binance.com/en/support/faq/360030157812) #### Kraken margin trading interest formula - Opening fee = P (borrowed money) * R (quat_hourly_interest) - Rollover fee = P (borrowed money) * R (quat_hourly_interest) * ceiling(T/4) (in hours) - I (interest) = Opening fee + Rollover fee - [source](https://support.kraken.com/hc/en-us/articles/206161568-What-are-the-fees-for-margin-trading-) +$$\begin{align*} +& Opening fee = P (borrowed_money) * R (quat_hourly_interest) \\ +& Rollover fee = P (borrowed_money) * R (quat_hourly_interest) * ceiling(T/4) (in hours) \\ +& I (interest) = Opening_fee + Rollover_fee +\end{align*}$$ -**FUTURES MODE** +[source](https://support.kraken.com/hc/en-us/articles/206161568-What-are-the-fees-for-margin-trading-) + +#### FUTURES MODE Funding fees are either added or subtracted from the total amount of a trade From ca2e8888019ede2469bf8acae97b6bb22c429c00 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 30 Oct 2021 20:28:46 +0200 Subject: [PATCH 7/8] improve documentation formatting --- docs/configuration.md | 45 +++---------------------------------------- docs/exchanges.md | 2 +- docs/leverage.md | 12 +++++++++--- 3 files changed, 13 insertions(+), 46 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index b7c010a01..ee258c854 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -449,45 +449,6 @@ The possible values are: `gtc` (default), `fok` or `ioc`. This is ongoing work. For now, it is supported only for binance and kucoin. Please don't change the default value unless you know what you are doing and have researched the impact of using different values for your particular exchange. -### Exchange configuration - -Freqtrade is based on [CCXT library](https://github.com/ccxt/ccxt) that supports over 100 cryptocurrency -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 these are the only officially supported exchanges: - -- [Bittrex](https://bittrex.com/): "bittrex" -- [Binance](https://www.binance.com/): "binance" -- [Kraken](https://kraken.com/): "kraken" - -Feel free to test other exchanges and submit your PR to improve the bot. - -Some exchanges require special configuration, which can be found on the [Exchange-specific Notes](exchanges.md) documentation page. - -#### Sample exchange configuration - -A exchange configuration for "binance" would look as follows: - -```json -"exchange": { - "name": "binance", - "key": "your_exchange_key", - "secret": "your_exchange_secret", - "ccxt_config": {"enableRateLimit": true}, - "ccxt_async_config": { - "enableRateLimit": true, - "rateLimit": 200 - }, -``` - -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. - 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? The `fiat_display_currency` configuration parameter sets the base currency to use for the @@ -527,9 +488,9 @@ creating trades on the exchange. ```json "exchange": { "name": "bittrex", - "key": "key", - "secret": "secret", - ... + "key": "key", + "secret": "secret", + ... } ``` diff --git a/docs/exchanges.md b/docs/exchanges.md index badaa484a..0849af72f 100644 --- a/docs/exchanges.md +++ b/docs/exchanges.md @@ -1,6 +1,6 @@ # Exchange-specific Notes -This page combines common gotchas and informations which are exchange-specific and most likely don't apply to other exchanges. +This page combines common gotchas and Information which are exchange-specific and most likely don't apply to other exchanges. ## Exchange configuration diff --git a/docs/leverage.md b/docs/leverage.md index 900164867..626a69aab 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -1,3 +1,5 @@ +# Leverage + !!! Warning "Beta feature" This feature is still in it's testing phase. Should you notice something you think is wrong please let us know via Discord or via Github Issue. @@ -24,7 +26,7 @@ Regular trading mode (low risk) - No Liquidation. - Profits gained/lost are equal to the change in value of the assets (minus trading fees). -#### Leverage trading modes +### Leverage trading modes # TODO-lev: include a resource to help calculate stoplosses that are above the liquidation price @@ -42,6 +44,7 @@ Perpetual swaps (also known as Perpetual Futures) are contracts traded at a pric In addition to the gains/losses from the change in price of the contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the contract and the underlying asset. The difference in price between a contract and the underlying asset varies between exchanges. +In addition to the gains/losses from the change in price of the futures contract, traders also exchange funding fees, which are gains/losses worth an amount that is derived from the difference in price between the futures contract and the underlying asset. The difference in price between a futures contract and the underlying asset varies between exchanges. ``` json "trading_mode": "futures" @@ -55,12 +58,16 @@ The possible values are: `isolated`, or `cross`(*currently unavailable*) Each market(trading pair), keeps collateral in a separate account +``` json +"collateral": "isolated" +``` + #### CROSS *currently unavailable* One account is used to share collateral between markets (trading pairs). Margin is taken from total account balance to avoid liquidation when needed. ``` json -"collateral": "isolated" +"collateral": "cross" ``` ### Developer @@ -94,4 +101,3 @@ $$\begin{align*} #### FUTURES MODE Funding fees are either added or subtracted from the total amount of a trade - From 7171975a4fc5d5b58dff54181b177b2d4e87501e Mon Sep 17 00:00:00 2001 From: Sam Germain Date: Fri, 5 Nov 2021 01:54:18 -0600 Subject: [PATCH 8/8] Removed interest formulas from docs --- docs/leverage.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/leverage.md b/docs/leverage.md index 626a69aab..3f4312e68 100644 --- a/docs/leverage.md +++ b/docs/leverage.md @@ -80,24 +80,6 @@ For longs, the currency which pays the interest fee for the `borrowed` will alre All Fees are included in `current_profit` calculations during the trade. -#### Binance margin trading interest formula - -$$ -I (interest) = P (borrowed money) * R (daily_interest/24) * ceiling(T) (in hours) -$$ - -[source](https://www.binance.com/en/support/faq/360030157812) - -#### Kraken margin trading interest formula - -$$\begin{align*} -& Opening fee = P (borrowed_money) * R (quat_hourly_interest) \\ -& Rollover fee = P (borrowed_money) * R (quat_hourly_interest) * ceiling(T/4) (in hours) \\ -& I (interest) = Opening_fee + Rollover_fee -\end{align*}$$ - -[source](https://support.kraken.com/hc/en-us/articles/206161568-What-are-the-fees-for-margin-trading-) - #### FUTURES MODE Funding fees are either added or subtracted from the total amount of a trade