![Logo](docs/img/logo3.png)
The most popular open-source cryptocurrency alerting tool for Telegram!
This lightweight software facilitates alerts on cryptocurrency price movements and technical indicators through Telegram using their open-source API.
About the Project • Deployment Options • Bot Commands • Add Indicators • Changelog • Contribute • Contact
📦 NOTE: Major version 3.0.0 has launched! See the 🔗CHANGELOG for more details.
The primary goal of Telegram Crypto Alerts is to be a lightweight, intuitive, and modular cryptocurrency price alert bot for the Telegram messaging client.
The bot utilizes Telegram's simple chat interface to provide users the following features:
- Get live crypto pair prices from Binance, and receive alerts on price movements like above, below, % change, and 24 hour % change
- Receive alerts on crypto technical indicators like RSI, MACD, Bollinger Bands, MA, SMA, and EMA.
- The bot has the capacity to support any technical indicator that is available on Taapi.io, but only these are shipped from the start. See How to Add Technical Indicators for more information.
- Configure bot access with a full suite of administrator commands
- Invite your friends to use the bot!
- Add additional users with their own unique alerts and configuration.
- Optional state and configuration data - Use a local JSON database or configure a MongoDB server!
This bot is designed to be easily extensible and deployable on a variety of platforms. The following are the available deployment options.:
I will choose the most cost-efficient and performant platform and deploy the bot for you. I will then manage the bot for a small fee. Please go to and fill out the form below to request a quote:
Click Here: 🔗Managed Hosting Request Form
If you have advanced technical abilities and would like to self host the bot, you can follow the steps below to set it up on your own machine or cloud server. Click the link corresponding to your setup preference:
Click Here: 🔗Deploy from Docker
Click Here: 🔗Deploy from Source
-
Returns all active alerts
View the list of all available types of simple and technical indicators with their detailed descriptions.
⚠️ Create new alert for simple indicators ONLY (see /indicators)Creates a new active simple indicator alert with the given parameters.
Parameter Description BASE/QUOTE The base and quote currencies for the alert (e.g. BTC/USDT) INDICATOR The indicator for which you want to set an alert. In the current context, the only available simple indicator is "PRICE". COMPARISON The comparison operator for the alert. Options are "ABOVE", "BELOW", "PCTCHG", or "24HRCHG". TARGET The target % change or price value for the alert, depending on comparison type. (Use percentage pts for %, e.g. 10.5 for 10.5%). optional_ENTRY_PRICE If using the "PCTCHG" comparison operator, you can specify this as an alternate entry price to the current price for calculating percentage changes. For example, the following command sets an alert for when the price of BTC/USDT changes by 10% relative to an entry price of 1200:
/new_alert BTC/USDT PRICE PCTCHG 10.0 1200
⚠️ Create new alert for technical indicators ONLY (see /indicators)Creates a new active technical indicator alert with the given parameters.
Parameter Description BASE/QUOTE The base currency for the alert (e.g. BTC/USDT) INDICATOR The ID for the technical indicator (e.g. RSI) TIMEFRAME The desired time interval for the indicator. Options: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 12h, 1d, or 1w PARAMS No-space-comma-separated list of param=value pairs for the indicator. E.g. period=10,stddev=3. Use "default" to skip passing params and use default values. See /indicators for available params OUTPUT_VALUE The desired output value to monitor. See /indicators for available output values COMPARISON The comparison operator for the alert. Options: ABOVE or BELOW TARGET The target value of OUTPUT_VALUE for the alert to trigger For example, the following command sets an alert for the ETH/USDT pair that triggers when the value of the upper Bollinger Band (calculated on the 1d timeframe) is above 1500:
/new_alert ETH/USDT BBANDS 1d default valueUpperBand ABOVE 1500
Cancels the pair alert at the given index
Parameter Description BASE/QUOTE The base and quote currencies for the alert (e.g. BTC/USDT) INDEX The index of the alert you want to cancel. You can see the indexes by using the /view_alerts BASE/QUOTE
command.For example, if you want to cancel the first alert of the BTC/USDT pair, you would use:
/cancel_alert BTC/USDT 1
-
Parameter Description BASE/QUOTE The base and quote currencies for the price data (e.g. BTC/USDT) For example, if you want to get the current price of the BTC/USDT pair, you would use:
/get_price BTC/USDT
This command does not take any parameters. It gets the current pair price for all pairs with active alerts.
Parameter Description BASE/QUOTE The base and quote currencies for the alert (e.g. BTC/USDT) INDICATOR The ID for the technical indicator (e.g. BBANDS) TIMEFRAME The desired time interval for the indicator. Options: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 12h, 1d, or 1w PARAMS No-space-comma-separated list of param=value pairs for the indicator. E.g. period=10,stddev=3. Use "default" to use the default values for the indicator For example, the following command gets the current value(s) of the Bollinger Bands indicator for the ETH/USDT pair on the 1d timeframe using the default parameters:
/get_indicator ETH/USDT BBANDS 1d default
-
Returns the current general configuration for the bot
Modify individual configuration settings. You can change multiple settings by separating them with a space.
For example, the following command sets the
send_email_alerts
config key to True:/set_config send_email_alerts=True
Allows you to view or modify the current list of Telegram channels set to receive alerts from the bot.
Parameter Description ACTION This can be either VIEW
,ADD
, orREMOVE
. Each action has different effects and parameters:VIEW - Returns the current list of Telegram channels in which to send price alerts. This action does not require any additional parameters. ADD - Adds the specified Telegram channel IDs to the channel registry. The IDs should be separated by commas. For example: /channels ADD 123456789,987654321
REMOVE - Removes the specified Telegram channel IDs from the channel registry. The IDs should be separated by commas. For example: /channels REMOVE 123456789,987654321
TG_CHANNEL_ID This is a list of Telegram channel IDs (separated by a comma no-spaces). These channels will be added or removed from the channel registry based on the ACTION parameter. This parameter is not required when ACTION is VIEW
.For example, the following command adds two Telegram channels to the alerts registry:
/channels ADD 123456789,987654321
Allows you to view or modify the current list of email addresses set to receive alerts from the bot.
⚠️ Registered emails will only be sent if you have configured the bot to use SendGrid for email alerts.Parameter Description ACTION This can be either VIEW
,ADD
, orREMOVE
. Each action has different effects and parameters:VIEW - Returns the current list of email addresses in which to send price alerts. This action does not require any additional parameters. ADD - Adds the specified email addresses to the email registry. The email addresses should be separated by commas. For example: /emails ADD [email protected],[email protected]
REMOVE - Removes the specified email addresses from the email registry. The email addresses should be separated by commas. For example: /emails REMOVE [email protected],[email protected]
EMAIL This is a list of email addresses (separated by a comma no-spaces). These email addresses will be added or removed from the email registry based on the ACTION parameter. This parameter is not required when ACTION is VIEW
.For example, the following command adds two email addresses to the alerts registry:
/emails ADD [email protected],[email protected]
-
Allows you to view or modify the current list of bot administrators.
Parameter Description ACTION This can be either VIEW
,ADD
, orREMOVE
. Each action has different effects and parameters:VIEW - Returns the current list of administrators. This action does not require any additional parameters. ADD - Adds the specified Telegram user IDs to the administrators registry. The IDs should be separated by commas. For example: /admins ADD 123456789,987654321
REMOVE - Removes the specified Telegram user IDs from the administrators registry. The IDs should be separated by commas. For example: /admins REMOVE 123456789,987654321
TG_USER_ID This is a list of Telegram user IDs (separated by a comma no-spaces). These user IDs will be added or removed from the administrators registry based on the ACTION parameter. This parameter is not required when ACTION is VIEW
.For example, the following command adds two administrators to the registry:
/admins ADD 123456789,987654321
Allows you to view or modify the bot's whitelist.
Parameter Description ACTION This can be either VIEW
,ADD
, orREMOVE
. Each action has different effects and parameters:VIEW - Returns the current whitelist. This action does not require any additional parameters. ADD - Adds the specified Telegram user IDs to the whitelist. The IDs should be separated by commas. For example: /whitelist ADD 123456789,987654321
REMOVE - Removes the specified Telegram user IDs from the whitelist. The IDs should be separated by commas. For example: /whitelist REMOVE 123456789,987654321
TG_USER_ID This is a list of Telegram user IDs (separated by a comma no-spaces). These user IDs will be added or removed from the whitelist based on the ACTION parameter. This parameter is not required when ACTION is VIEW
.For example, the following command adds two users to the whitelist:
/whitelist ADD 123456789,987654321
Returns the current process logs
As stated previously, the bot is designed to be easily extensible. View the currently available indicators by using the /indicators
command on the bot. If your indicator is not listed, head over to taapi.io/indicators and find the indicator you want to add. You can add any technical indicator that is supplied by taapi.io by following the steps below:
-
Shut the bot down if it is currently running using
CRTL+C
in the terminal window. -
Open the
/util/add_indicators.ipynb
file using jupyter notebook.If you don't have jupyter installed, see this guide: https://jupyter.org/install
-
Make a new cell, and use the
db.add_indicator
function to add the indicator to the database:View the previous examples of how the existing indicators were added to the database using the
db.add_indicator
function (seeTADatabaseClient.add_indicator
in/src/indicators.py
)The usage of the
db.add_indicator
function is as follows:db.add_indicator( indicator_id # Name/abbreviation of the endpoint as shown on taapi.io (e.g. BBANDS, MACD, MA) name # The full name of the indicator on taapi.io (e.g. Bollinger Bands, Moving) endpoint # the endpoint for the indicator in the following format: https://api.taapi.io/{indicator_id}?secret={api_key}&exchange=binance reference_url # The url to the taapi.io documentation for the indicator params # A list of tuples to specify additional parameters for the indicator: (param_name, param_description, default_value) output # A list of output values for the indicator, as shown on taapi.io (e.g. upperBand, middleBand, lowerBand) )
-
endpoint - Must match the format shown above. The bot automatically adds the
symbol
andinterval
required parameters. Additional parameters can be added using theparams
. -
params - The
param_name
must match the name of the parameter as shown on taapi.io. Theparam_description
is a short description of the parameter (used in the /indicators command). Thedefault_value
is your custom default value for the parameter.Using the following screenshot below as an example:
The params list would look like the following:
[ ("optInFastPeriod", "Fast period length", 12), ("optInSlowPeriod", "Slow period length", 26), ("optInSignalPeriod", "Signal smoothing", 9), ]
-
output - The
output
list must match the output values as shown on taapi.io.Additionally, the output value must be directly accessible from the API response as keys in a dictionary. For example, the following response would be valid:
{ "valueMACD": 737.4052287912818, "valueMACDSignal": 691.8373005221695, "valueMACDHist": 45.56792826911237 }
Because of this, parameters such as
backtracks
are restricted because they turn the response into a list of dictionaries. The bot is not designed to handle this type of response. The following response would NOT be valid:[ { "valueMACD": 979.518807843051, "valueMACDSignal": 893.54139321284, "valueMACDHist": 85.977414630211, "backtrack": 0 }, { "valueMACD": 949.7317001653792, "valueMACDSignal": 872.0470395552873, "valueMACDHist": 77.6846606100919, "backtrack": 1 }, ]
You may need to DYOR to ensure that the parameters that you are configuring will result in a valid response.
-
Contributions are always welcome!
To contribute to the project, please do the following:
- Create a new issue and describe your idea/suggestion in detail
- Fork the project
- Create a branch for your new edits (E.g. new-indicator)
- Implement and test your changes (test, test, test!)
- Submit your pull request
I am actively maintaining this project, and I will respond to any issues or pull requests as soon as possible.
Please Star ⭐ the project if it helps you so that visibility increases to help others!
If you have any questions, feel free to reach out to me on Telegram.
See the future plans for the project 🔗 Here