stable/docs/telegram-usage.md

391 lines
14 KiB
Markdown
Raw Normal View History

2018-01-02 02:17:10 +00:00
# Telegram usage
2019-05-25 14:27:36 +00:00
## Setup your Telegram bot
2019-04-05 04:49:15 +00:00
2019-05-25 14:27:36 +00:00
Below we explain how to create your Telegram Bot, and how to get your
Telegram user id.
### 1. Create your Telegram bot
Start a chat with the [Telegram BotFather](https://telegram.me/BotFather)
2020-08-06 05:54:54 +00:00
Send the message `/newbot`.
2019-05-25 14:27:36 +00:00
*BotFather response:*
> Alright, a new bot. How are we going to call it? Please choose a name for your bot.
Choose the public name of your bot (e.x. `Freqtrade bot`)
*BotFather response:*
> Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
Choose the name id of your bot and send it to the BotFather (e.g. "`My_own_freqtrade_bot`")
*BotFather response:*
> Done! Congratulations on your new bot. You will find it at `t.me/yourbots_name_bot`. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.
> Use this token to access the HTTP API: `22222222:APITOKEN`
> For a description of the Bot API, see this page: https://core.telegram.org/bots/api Father bot will return you the token (API key)
Copy the API Token (`22222222:APITOKEN` in the above example) and keep use it for the config parameter `token`.
Don't forget to start the conversation with your bot, by clicking `/START` button
2020-11-15 12:13:44 +00:00
### 2. Telegram user_id
2020-11-15 14:40:40 +00:00
2020-11-15 12:13:44 +00:00
#### Get your user id
2019-05-25 14:27:36 +00:00
Talk to the [userinfobot](https://telegram.me/userinfobot)
Get your "Id", you will use it for the config parameter `chat_id`.
2018-01-02 02:17:10 +00:00
2020-11-15 12:13:44 +00:00
#### Use Group id
2020-11-15 14:40:40 +00:00
You can use bots in telegram groups by just adding them to the group. You can find the group id by first adding a [RawDataBot](https://telegram.me/rawdatabot) to your group. The Group id is shown as id in the `"chat"` section, which the RawDataBot will send to you:
``` json
"chat":{
"id":-1001332619709
}
```
For the Freqtrade configuration, you can then use the the full value (including `-` if it's there) as string:
```json
"chat_id": "-1001332619709"
```
2021-11-09 14:16:51 +00:00
!!! Warning "Using telegram groups"
When using telegram groups, you're giving every member of the telegram group access to your freqtrade bot and to all commands possible via telegram. Please make sure that you can trust everyone in the telegram group to avoid unpleasent surprises.
2020-11-15 12:13:44 +00:00
## Control telegram noise
Freqtrade provides means to control the verbosity of your telegram bot.
2020-09-22 18:19:46 +00:00
Each setting has the following possible values:
* `on` - Messages will be sent, and user will be notified.
* `silent` - Message will be sent, Notification will be without sound / vibration.
* `off` - Skip sending a message-type all together.
Example configuration showing the different settings:
``` json
"telegram": {
"enabled": true,
"token": "your_telegram_token",
"chat_id": "your_telegram_chat_id",
"notification_settings": {
"status": "silent",
"warning": "on",
"startup": "off",
"buy": "silent",
"sell": {
"roi": "silent",
"emergency_sell": "on",
"force_sell": "on",
"sell_signal": "silent",
"trailing_stop_loss": "on",
"stop_loss": "on",
"stoploss_on_exchange": "on",
"custom_sell": "silent"
},
"buy_cancel": "silent",
"sell_cancel": "on",
"buy_fill": "off",
"sell_fill": "off",
"protection_trigger": "off",
"protection_trigger_global": "on"
},
"reload": true,
"balance_dust_level": 0.01
},
```
2021-04-20 05:57:34 +00:00
`buy` notifications are sent when the order is placed, while `buy_fill` notifications are sent when the order is filled on the exchange.
`sell` notifications are sent when the order is placed, while `sell_fill` notifications are sent when the order is filled on the exchange.
`*_fill` notifications are off by default and must be explicitly enabled.
`protection_trigger` notifications are sent when a protection triggers and `protection_trigger_global` notifications trigger when global protections are triggered.
2021-04-20 05:57:34 +00:00
`balance_dust_level` will define what the `/balance` command takes as "dust" - Currencies with a balance below this will be shown.
`reload` allows you to disable reload-buttons on selected messages.
2020-12-20 15:50:42 +00:00
## Create a custom keyboard (command shortcut buttons)
2020-12-22 06:36:53 +00:00
2020-12-20 13:48:49 +00:00
Telegram allows us to create a custom keyboard with buttons for commands.
The default custom keyboard looks like this.
2020-12-22 06:36:53 +00:00
2020-12-20 13:48:49 +00:00
```python
[
2020-12-22 06:36:53 +00:00
["/daily", "/profit", "/balance"], # row 1, 3 commands
["/status", "/status table", "/performance"], # row 2, 3 commands
["/count", "/start", "/stop", "/help"] # row 3, 4 commands
2020-12-20 13:48:49 +00:00
]
2020-12-22 06:36:53 +00:00
```
2020-12-20 13:48:49 +00:00
### Usage
2020-12-22 06:36:53 +00:00
2020-12-20 13:48:49 +00:00
You can create your own keyboard in `config.json`:
2020-12-22 06:36:53 +00:00
2020-12-20 13:48:49 +00:00
``` json
"telegram": {
"enabled": true,
"token": "your_telegram_token",
"chat_id": "your_telegram_chat_id",
2020-12-20 15:50:42 +00:00
"keyboard": [
2020-12-20 13:48:49 +00:00
["/daily", "/stats", "/balance", "/profit"],
["/status table", "/performance"],
2020-12-22 06:36:53 +00:00
["/reload_config", "/count", "/logs"]
2020-12-20 13:48:49 +00:00
]
},
```
2020-12-22 06:36:53 +00:00
!!! Note "Supported Commands"
Only the following commands are allowed. Command arguments are not supported!
`/start`, `/stop`, `/status`, `/status table`, `/trades`, `/profit`, `/performance`, `/daily`, `/stats`, `/count`, `/locks`, `/balance`, `/stopbuy`, `/reload_config`, `/show_config`, `/logs`, `/whitelist`, `/blacklist`, `/edge`, `/help`, `/version`
2020-12-20 13:48:49 +00:00
2018-01-02 02:17:10 +00:00
## Telegram commands
2019-04-05 04:49:15 +00:00
2018-12-31 13:00:36 +00:00
Per default, the Telegram bot shows predefined commands. Some commands
are only available by sending them to the bot. The table below list the
2018-01-02 02:17:10 +00:00
official commands. You can ask at any moment for help with `/help`.
2020-08-08 13:06:13 +00:00
| Command | Description |
|----------|-------------|
| `/start` | Starts the trader
| `/stop` | Stops the trader
| `/stopbuy` | Stops the trader from opening new trades. Gracefully closes open trades according to their rules.
| `/reload_config` | Reloads the configuration file
| `/show_config` | Shows part of the current configuration with relevant settings to operation
2020-08-14 13:44:52 +00:00
| `/logs [limit]` | Show last log messages.
2020-08-08 13:06:13 +00:00
| `/status` | Lists all open trades
| `/status <trade_id>` | Lists one or more specific trade. Separate multiple <trade_id> with a blank space.
2020-08-08 13:06:13 +00:00
| `/status table` | List all open trades in a table format. Pending buy orders are marked with an asterisk (*) Pending sell orders are marked with a double asterisk (**)
| `/trades [limit]` | List all recently closed trades in a table format.
| `/delete <trade_id>` | Delete a specific trade from the Database. Tries to close open orders. Requires manual handling of this trade on the exchange.
| `/count` | Displays number of trades used and available
2020-12-21 09:03:27 +00:00
| `/locks` | Show currently locked pairs.
| `/unlock <pair or lock_id>` | Remove the lock for this pair (or for this lock id).
| `/profit [<n>]` | Display a summary of your profit/loss from close trades and some stats about your performance, over the last n days (all trades by default)
2020-08-08 13:06:13 +00:00
| `/forcesell <trade_id>` | Instantly sells the given trade (Ignoring `minimum_roi`).
| `/forcesell all` | Instantly sells all open trades (Ignoring `minimum_roi`).
| `/forcebuy <pair> [rate]` | Instantly buys the given pair. Rate is optional and only applies to limit orders. (`forcebuy_enable` must be set to True)
2020-08-08 13:06:13 +00:00
| `/performance` | Show performance of each finished trade grouped by pair
| `/balance` | Show account balance per currency
| `/daily <n>` | Shows profit or loss per day, over the last n days (n defaults to 7)
| `/weekly <n>` | Shows profit or loss per week, over the last n weeks (n defaults to 8)
| `/monthly <n>` | Shows profit or loss per month, over the last n months (n defaults to 6)
2020-12-07 14:03:16 +00:00
| `/stats` | Shows Wins / losses by Sell reason as well as Avg. holding durations for buys and sells
2020-08-08 13:06:13 +00:00
| `/whitelist` | Show the current whitelist
| `/blacklist [pair]` | Show the current blacklist, or adds a pair to the blacklist.
| `/edge` | Show validated pairs by Edge if it is enabled.
| `/help` | Show help message
| `/version` | Show version
2018-01-02 02:17:10 +00:00
## Telegram commands in action
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Below, example of Telegram message you will receive for each command.
### /start
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
> **Status:** `running`
### /stop
2018-10-10 18:08:29 +00:00
2018-12-31 13:00:36 +00:00
> `Stopping trader ...`
2018-01-02 02:17:10 +00:00
> **Status:** `stopped`
2019-03-17 18:36:25 +00:00
### /stopbuy
> **status:** `Setting max_open_trades to 0. Run /reload_config to reset.`
2019-03-17 18:36:25 +00:00
Prevents the bot from opening new trades by temporarily setting "max_open_trades" to 0. Open trades will be handled via their regular rules (ROI / Sell-signal, stoploss, ...).
After this, give the bot time to close off open trades (can be checked via `/status table`).
Once all positions are sold, run `/stop` to completely stop the bot.
`/reload_config` resets "max_open_trades" to the value set in the configuration and resets this command.
2019-03-17 18:36:25 +00:00
!!! Warning
2019-03-23 18:43:23 +00:00
The stop-buy signal is ONLY active while the bot is running, and is not persisted anyway, so restarting the bot will cause this to reset.
2019-03-17 18:36:25 +00:00
### /status
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
For each open trade, the bot will send you the following message.
2021-12-19 15:24:46 +00:00
Enter Tag is configurable via Strategy.
2018-01-02 02:17:10 +00:00
2019-04-01 17:25:13 +00:00
> **Trade ID:** `123` `(since 1 days ago)`
> **Current Pair:** CVC/BTC
2021-12-19 15:24:46 +00:00
> **Direction:** Long
> **Leverage:** 1.0
2019-04-01 17:25:13 +00:00
> **Amount:** `26.64180098`
2021-12-19 15:24:46 +00:00
> **Enter Tag:** Awesome Long Signal
2019-04-01 17:25:13 +00:00
> **Open Rate:** `0.00007489`
> **Current Rate:** `0.00007489`
> **Current Profit:** `12.95%`
> **Stoploss:** `0.00007389 (-0.02%)`
2018-01-02 02:17:10 +00:00
2019-03-17 18:36:25 +00:00
### /status table
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Return the status of all open trades in a table format.
2020-08-06 05:54:54 +00:00
2018-01-02 02:17:10 +00:00
```
2018-12-31 13:00:36 +00:00
ID Pair Since Profit
---- -------- ------- --------
2021-12-19 15:24:46 +00:00
67 SC/BTC L 1 d 13.33%
123 CVC/BTC S 1 h 12.95%
2018-01-02 02:17:10 +00:00
```
2019-03-17 18:36:25 +00:00
### /count
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Return the number of trades used and available.
2020-08-06 05:54:54 +00:00
2018-01-02 02:17:10 +00:00
```
current max
2018-12-31 13:00:36 +00:00
--------- -----
2 10
2018-01-02 02:17:10 +00:00
```
2019-03-17 18:36:25 +00:00
### /profit
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Return a summary of your profit/loss and performance.
2019-04-01 17:25:13 +00:00
> **ROI:** Close trades
2021-07-15 05:11:44 +00:00
> ∙ `0.00485701 BTC (2.2%) (15.2 Σ%)`
2019-04-01 17:25:13 +00:00
> ∙ `62.968 USD`
> **ROI:** All trades
2021-07-15 05:11:44 +00:00
> ∙ `0.00255280 BTC (1.5%) (6.43 Σ%)`
2019-04-01 17:25:13 +00:00
> ∙ `33.095 EUR`
>
> **Total Trade Count:** `138`
> **First Trade opened:** `3 days ago`
> **Latest Trade opened:** `2 minutes ago`
> **Avg. Duration:** `2:33:45`
> **Best Performing:** `PAY/BTC: 50.23%`
2018-01-02 02:17:10 +00:00
2021-07-15 05:11:44 +00:00
The relative profit of `1.2%` is the average profit per trade.
The relative profit of `15.2 Σ%` is be based on the starting capital - so in this case, the starting capital was `0.00485701 * 1.152 = 0.00738 BTC`.
Starting capital is either taken from the `available_capital` setting, or calculated by using current wallet size - profits.
2019-03-17 18:36:25 +00:00
### /forcesell <trade_id>
2018-01-02 02:17:10 +00:00
> **BITTREX:** Selling BTC/LTC with limit `0.01650000 (profit: ~-4.07%, -0.00008168)`
### /forcebuy <pair> [rate]
2018-10-10 18:08:29 +00:00
2019-04-08 08:20:15 +00:00
> **BITTREX:** Buying ETH/BTC with limit `0.03400000` (`1.000000 ETH`, `225.290 USD`)
2018-10-10 18:08:29 +00:00
Omitting the pair will open a query asking for the pair to buy (based on the current whitelist).
![Telegram force-buy screenshot](assets/telegram_forcebuy.png)
2018-10-10 18:08:29 +00:00
Note that for this to work, `forcebuy_enable` needs to be set to true.
2020-11-28 02:37:52 +00:00
[More details](configuration.md#understand-forcebuy_enable)
2019-03-17 18:36:25 +00:00
### /performance
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Return the performance of each crypto-currency the bot has sold.
> Performance:
> 1. `RCN/BTC 0.003 BTC (57.77%) (1)`
> 2. `PAY/BTC 0.0012 BTC (56.91%) (1)`
> 3. `VIB/BTC 0.0011 BTC (47.07%) (1)`
> 4. `SALT/BTC 0.0010 BTC (30.24%) (1)`
> 5. `STORJ/BTC 0.0009 BTC (27.24%) (1)`
2019-04-01 17:25:13 +00:00
> ...
2018-01-02 02:17:10 +00:00
2019-03-17 18:36:25 +00:00
### /balance
2018-10-10 18:08:29 +00:00
2018-01-02 02:17:10 +00:00
Return the balance of all crypto-currency your have on the exchange.
2019-04-01 17:25:13 +00:00
> **Currency:** BTC
> **Available:** 3.05890234
> **Balance:** 3.05890234
> **Pending:** 0.0
2018-01-02 02:17:10 +00:00
2019-04-01 17:25:13 +00:00
> **Currency:** CVC
> **Available:** 86.64180098
> **Balance:** 86.64180098
> **Pending:** 0.0
2018-01-02 02:17:10 +00:00
2019-03-17 18:36:25 +00:00
### /daily <n>
2018-10-10 18:08:29 +00:00
Per default `/daily` will return the 7 last days. The example below if for `/daily 3`:
2018-01-02 02:17:10 +00:00
> **Daily Profit over the last 3 days:**
```
2018-12-31 13:00:36 +00:00
Day Profit BTC Profit USD
---------- -------------- ------------
2018-01-03 0.00224175 BTC 29,142 USD
2018-01-02 0.00033131 BTC 4,307 USD
2018-01-02 02:17:10 +00:00
2018-01-01 0.00269130 BTC 34.986 USD
```
### /weekly <n>
Per default `/weekly` will return the 8 last weeks, including the current week. Each week starts
from Monday. The example below if for `/weekly 3`:
> **Weekly Profit over the last 3 weeks (starting from Monday):**
```
Monday Profit BTC Profit USD
---------- -------------- ------------
2018-01-03 0.00224175 BTC 29,142 USD
2017-12-27 0.00033131 BTC 4,307 USD
2017-12-20 0.00269130 BTC 34.986 USD
```
### /monthly <n>
Per default `/monthly` will return the 6 last months, including the current month. The example below
if for `/monthly 3`:
> **Monthly Profit over the last 3 months:**
```
Month Profit BTC Profit USD
---------- -------------- ------------
2018-01 0.00224175 BTC 29,142 USD
2017-12 0.00033131 BTC 4,307 USD
2017-11 0.00269130 BTC 34.986 USD
```
### /whitelist
Shows the current whitelist
2019-03-27 17:19:42 +00:00
> Using whitelist `StaticPairList` with 22 pairs
> `IOTA/BTC, NEO/BTC, TRX/BTC, VET/BTC, ADA/BTC, ETC/BTC, NCASH/BTC, DASH/BTC, XRP/BTC, XVG/BTC, EOS/BTC, LTC/BTC, OMG/BTC, BTG/BTC, LSK/BTC, ZEC/BTC, HOT/BTC, IOTX/BTC, XMR/BTC, AST/BTC, XLM/BTC, NANO/BTC`
2019-03-24 15:29:58 +00:00
### /blacklist [pair]
2019-03-24 15:29:58 +00:00
Shows the current blacklist.
If Pair is set, then this pair will be added to the pairlist.
2020-08-06 05:54:54 +00:00
Also supports multiple pairs, separated by a space.
Use `/reload_config` to reset the blacklist.
2019-03-27 17:19:42 +00:00
> Using blacklist `StaticPairList` with 2 pairs
>`DODGE/BTC`, `HOT/BTC`.
2019-03-27 11:54:00 +00:00
### /edge
2020-08-06 05:54:54 +00:00
Shows pairs validated by Edge along with their corresponding win-rate, expectancy and stoploss values.
2019-03-27 11:54:00 +00:00
> **Edge only validated following pairs:**
```
Pair Winrate Expectancy Stoploss
-------- --------- ------------ ----------
DOCK/ETH 0.522727 0.881821 -0.03
PHX/ETH 0.677419 0.560488 -0.03
HOT/ETH 0.733333 0.490492 -0.03
HC/ETH 0.588235 0.280988 -0.02
ARDR/ETH 0.366667 0.143059 -0.01
```
2019-03-17 18:36:25 +00:00
### /version
2018-10-10 18:08:29 +00:00
2018-12-31 13:00:36 +00:00
> **Version:** `0.14.3`