Telegram Crypto Signals Bot manual

What it does

• Reads the BOT_TOKEN and CHAT_ID environment variables and stops startup if either value is not configured.
• Creates a python-telegram-bot application and starts it in polling mode with app.run_polling().
• Registers the /start command, which replies with a status message and the fixed watchlist BTCUSDT, ETHUSDT, SOLUSDT, BNBUSDT, ADAUSDT, and DOTUSDT.
• Registers the /prices command, which requests the 24-hour ticker for each watchlist symbol from the Binance /api/v3/ticker/24hr endpoint and replies with last price and percentage change.
• Contains get_klines, configured to request 50 candles at the 1h interval, and calculate_rsi, which calculates a period-14 RSI from supplied closing prices.
• Contains generate_signal, which classifies RSI and price change as FORTE BUY, BUY, FORTE SELL, SELL, or HOLD using fixed thresholds in the code.

What it does not do

• It does not calculate MACD: the Python code has no MACD calculation despite the product name and some README statements.
• It does not use CoinGecko: the code sends requests to Binance public REST endpoints defined in the BINANCE_API constant.
• It does not start scheduled automatic signals in its main flow: main neither calls nor schedules send_signals.
• It does not place purchases, sales, orders, connect wallets, or perform exchange operations.
• It does not save a history, provide a dashboard, or include a panel for changing the watchlist.
• It does not include the .env.example file referred to by the delivered READMEs.

Requirements

• Python 3: You need a Python 3 installation that can be run from a terminal. The delivered file uses the python3 interpreter in its header, and the steps below use a virtual environment.
• Telegram bot and token: Create a bot through @BotFather using Telegram’s standard procedure and keep its token private. The code requires that value in BOT_TOKEN.
• Telegram chat ID: You need to know a chat ID and put it in CHAT_ID: the startup check requires it even though the active /start and /prices path does not send direct messages to that value.
• Internet connection: Bot polling requires Telegram. The /prices command also needs access to the public Binance endpoints defined in the code. Check the terms, availability, limits, and price list of any third-party service with its provider.
• Python dependencies: requirements.txt requires python-telegram-bot==20.7, aiohttp==3.9.1, and python-dotenv>=1.0.0.
• Manually created .env file: python-dotenv is included in the dependencies and the code calls load_dotenv(). Since .env.example was not delivered, you must create .env in the directory from which you run the script.

Step-by-step setup

1. Extract the archive. Download the delivered ZIP file and extract it to a folder of your choice. The code and dependency file to use are in the original subfolder.
2. Check the files that are actually available. The extracted folder contains CONTENTS.en.md, README.en.md, and the original folder. original contains README.md, requirements.txt, and telegram-bot-crypto.py; .env.example is absent and should not be searched for or copied.
3. Create and activate a virtual environment. In a terminal, enter original. The following commands are for macOS or Linux and keep this bot’s libraries separate from other Python installations.
4. Install the delivered dependencies. With the virtual environment active, install exactly the dependencies listed in requirements.txt.
5. Create the Telegram bot. Follow Telegram’s normal @BotFather procedure to create your bot and obtain its token. Do not put the token in chats, screenshots, public repositories, or shared files.
6. Get your chat ID. Obtain a chat ID through a standard Telegram method, such as the @userinfobot method mentioned in the README. The value is required to pass the code’s configuration check.
7. Create the missing .env file. In the original folder, manually create a file named .env. Do not use real values in examples and do not publish this file.
8. Check the configuration. Make sure both lines are present and that you have not left the code’s default placeholders in place. At startup, the program stops if BOT_TOKEN or CHAT_ID is missing or begins with YOUR_.
9. Start the bot. With the virtual environment active and from the original folder, start the script. After checking credentials, the code registers the two handlers and enters Telegram polling. Keep the process running while you want to use the bot.
10. Try the available commands. Open a chat with your bot and send /start first, then /prices. The first command shows the watchlist; the second tries to retrieve and display the 24-hour ticker for every symbol. Do not expect automatic signal messages: the main file does not start that loop.

Daily use

Keep the process active

Run the startup command with the virtual environment active. If you close the terminal or stop the process, the bot stops receiving polling updates.

Use /start as a quick check

Send /start to the bot chat to confirm that the bot responds and to see the fixed watchlist contained in the source.

Request prices with /prices

Send /prices whenever you want the bot to query Binance 24-hour tickers for all watchlist symbols and reply in the chat that sent the command.

Interpret the displayed data correctly

The /prices message uses lastPrice and priceChangePercent returned by the 24-hour ticker. It is not an automatic signal and is not investment advice.

Restart after changing the source

If you change WATCHLIST or any other part of the Python file, keep a copy of the original file, stop the process, and start it again to load the updated code.

Stop it when you do not need it

Stop the process in the terminal using your operating system’s normal procedure. The package has no scheduling or remote-stop feature.

Practical cases

Personal watchlist lookup

You want to query from Telegram the prices and 24-hour changes of the six already defined symbols, without opening or changing the code each time.

1. Configure BOT_TOKEN and CHAT_ID in the manually created .env file.
2. Start telegram-bot-crypto.py from the active virtual environment.
3. Send /start to confirm that the bot responds and to read the watchlist.
4. Send /prices in the bot chat whenever you want to request the tickers.

You receive a chat reply with last price and 24-hour percentage change for the watchlist defined in the delivered file.

Studying the RSI calculation in the source

You are learning Python and want to examine how the package converts a closing-price series into an RSI value and a text label.

1. Open original/telegram-bot-crypto.py in a text editor.
2. Examine get_klines and the conversion of the fifth value in each candle to a closing price.
3. Examine calculate_rsi with period 14 and generate_signal with its thresholds.
4. Keep in mind that these functions are defined in the file but are not connected to an automatic task by main.

You get a concrete example to read and verify, while distinguishing available functions from the behaviour that is actually started.

Command replies in a Telegram chat

You have made your bot available in a Telegram chat through the platform’s normal procedure and want to offer the two commands included in the code.

1. Start the process with valid credentials and an available Internet connection.
2. Send /start in the chat to display the status message and monitored symbols.
3. Send /prices in the same chat to request watchlist tickers.
4. Tell users that the reply reports market data and does not execute operations or provide advice.

The chat can receive replies from the two commands registered by the bot, subject to Telegram and Binance availability.

Tips

• Keep BOT_TOKEN only in your .env file or your system environment variables, and never send it in a Telegram chat.
• Exclude .env from public backups and version-controlled repositories; the token can control the associated bot.
• Test /start before /prices: this separates a Telegram configuration issue from a Binance data-retrieval issue.
• Remember that the change shown by /prices is the ticker’s priceChangePercent field over 24 hours, not a change calculated by the bot over an interval you select.
• The initial watchlist is fixed in the code and uses symbols in the BTCUSDT format; edit the source only if you can manage a Python list and then restart the process.
• Do not rely on the product name or README to assume MACD or scheduled signals are active: check the real behaviour of the delivered main file.
• When studying calculate_rsi, note that it uses a period of 14 and returns 50.0 for fewer than 15 prices; it is not called by /prices in the main flow.
• Keep requirements.txt with the project and always activate its virtual environment before starting the script.
• Check the terms of use, request limits, and availability of Telegram and Binance endpoints before ongoing use.
• Treat prices, changes, and any BUY or SELL label in the code as technical information, not financial advice; cryptocurrency involves risk of loss.

Troubleshooting

Startup shows ERRORE DI CONFIGURAZIONE — il programma non puo' partire.

BOT_TOKEN, CHAT_ID, or both are missing, empty, or begin with YOUR_. The _check_config check runs before the Telegram application is created. Create or correct .env in the startup folder with both variables, or set them as environment variables. Then restart with python telegram-bot-crypto.py.

The README says to copy .env.example, but that file does not exist.

The delivered archive does not contain .env.example, although README.md and README.en.md list it. Manually create .env in the original folder with two lines: BOT_TOKEN and CHAT_ID. Do not create or copy configuration files from untrusted sources.

Python reports ModuleNotFoundError for telegram, aiohttp, or dotenv.

Dependencies are not installed in the interpreter used to start the bot, or the virtual environment is not active. Enter the original folder, activate .venv, and run python -m pip install -r requirements.txt again before restarting the script.

The bot does not respond to /start or /prices.

The process may not be running, the token may not be valid, or Telegram polling may not connect under your network conditions. Check that the terminal running the script remains open, verify the token in your private environment, and review the bot configuration using Telegram’s standard procedure. Do not share the token while checking.

The /prices command does not return data or hits an error while retrieving it.

The command depends on Internet access and responses from Binance public endpoints for each symbol; the command code has no custom network-error handling. Check connectivity, provider availability, and its terms or request limits. Try again later without artificially increasing request frequency.

No automatic signals arrive every hour.

The send_signals function contains a loop with a 3600-second pause, but main does not call it or create an asyncio task to run it. Treat the delivered package as a command-based bot. Do not assume automatic sending is active merely because the function exists in the file or is mentioned in the README.

I am looking for a MACD indicator in messages or source code.

The name and README mention MACD, but telegram-bot-crypto.py does not implement a MACD calculation and no command displays one. Do not use this package to obtain MACD. Base use only on /start, /prices, and functions that are actually present, or separately assess any code changes.

I set CHAT_ID but do not receive automatic direct messages in that chat.

CHAT_ID passes the startup check and appears in send_signals, but that function is not started by main. The registered commands instead reply to the chat of the incoming Telegram update. Use /start and /prices in the desired chat to verify actual behaviour. Do not rely on CHAT_ID for automatic sending with the delivered code.

Limits to know

• The started behaviour is limited to polling and the /start and /prices commands; the delivered main has no automatic signal process.
• MACD is not implemented in the source, although it appears in the product name and README.
• The actual data source in the code is Binance, not CoinGecko; BINANCE_API and the watchlist symbols are source constants.
• BUY and SELL labels are technical thresholds in an inactive function and are not financial advice, an invitation to trade, or a guarantee of outcome. Cryptocurrency is risky and you can lose capital.
• The package does not trade, manage wallets, retain data, or include history, a dashboard, scheduled notifications, or graphical configuration.
• Telegram, Binance, and the network are external services: availability, access, terms, and limits can change. Respect provider rules and request limits.
• The bot token and chat ID must be protected. The package has no .env.example and should not be completed with secrets published by third parties.

Frequently asked questions

Which files are actually included?

The package includes CONTENTS.en.md, README.en.md, original/README.md, original/requirements.txt, and original/telegram-bot-crypto.py. There are no PDFs and no .env.example.

Which delivered files are in English and which are Italian?

CONTENTS.en.md and README.en.md are English. original/README.md is Italian, and the Python file’s visible console and Telegram messages are Italian. requirements.txt is language-neutral.

Do I have to use .env.example?

No, because it was not delivered. Manually create .env in the working folder and add BOT_TOKEN and CHAT_ID using your private values.

Does the bot send automatic signals?

Not in the delivered main flow. send_signals is defined but is not called by main, so the hourly loop and direct send do not start.

Does the bot calculate MACD?

No. The source implements calculate_rsi and generate_signal but contains no MACD calculation.

Which markets or symbols does it use?

The WATCHLIST constant contains BTCUSDT, ETHUSDT, SOLUSDT, BNBUSDT, ADAUSDT, and DOTUSDT. /prices requests the Binance 24-hour ticker for each one.

Do I need a Binance API key?

The delivered code does not read or require a Binance API key. It uses public URLs embedded in the source; you must still check the provider’s terms, availability, and limits.

Can I change the watchlist?

Yes, only by editing the WATCHLIST constant in original/telegram-bot-crypto.py and restarting the bot. This is not configuration available through .env.