cryptocodi bot

Telegram utility bot for the @cryptocodi crypto community. Works in private messages and Telegram groups.

Features

• detects up to the configured limit of UTC, GMT/UTC offset, CET, and KYIV times in one message and converts them between supported timezones;
• detects cryptocurrency and basic fiat currency amounts (USD, EUR, CAD, PLN, RUB, UAH) and approximately converts them to USD and UAH;
• converts USD amounts to cryptocurrency amounts with formats such as 10$ BNB and $10 BNB;
• supports tickers, full coin names, compact amounts with k (thousands) and m (millions) suffixes, and multiple crypto pairs in one message;
• shows 24-hour price changes for one unit of cryptocurrency or a supported fiat currency;
• adds CoinGecko chart links and a crypto-response delete button;
• calculates simple mathematical expressions with +, -, *, /, ** and parentheses;
• calculates crypto expressions such as 3*2 BNB and converts the result;
• recognizes ×, Latin x, and Cyrillic х as multiplication;
• the /id command shows current chat and user data, accepts /id <user_id>, and supports selecting another entity in a private chat;
• supports English, Ukrainian, and Russian messages, stores separate language preferences for users and groups, and allows only group administrators to change the group language;
• fetches current rates through the CoinGecko Demo API;
• writes general logs and separate logs for detected messages;
• limits the daily number of conversions and CoinGecko requests;
• updates the related reply after a message is edited and does not reply again if crypto values, UTC time, or a mathematical expression did not change.

Commands

• /start or /help — show information, examples, and change language;
• /language — change the bot message language; in groups, the command is available only to the owner and administrators;
• /id — show the current chat and user ID;
• /id <user_id> — approximately estimate the Telegram account creation month.

Message examples:

10:00 UTC
10:00 GMT+3
10:00 CET
10:00 KYIV
start 10:00 UTC, finish 12:00 CET
Event starts at 10:00utc
0.3 BNB
10$ BNB
$10 BNB
25k USDT
1m BNB
Price: 0,34 ETH
1 bitcoin
100 EUR
100 CAD
100 PLN
3*2
(10 + 5) / 3
3*2 BNB
/id
/id 603206097
/language

Local setup

Python 3.10 or newer is required.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

Fill .env with your own values:

• TELEGRAM_BOT_TOKEN — token from BotFather;
• COINGECKO_API_KEY — CoinGecko Demo API key;
• MAX_TIME_MATCHES_PER_MESSAGE — maximum timezone matches processed from one message, 5 by default;
• the remaining variables control limits, parser caps, and priority users/groups.

The real .env must not be committed to Git.

Install development dependencies and run tests:

python -m pip install -r requirements-dev.txt
pytest

Run time conversion coverage:

pytest --cov=time_converter --cov=telegram_bot.handlers.time_message_handler

Run the bot:

python main.py

Deployment on Ubuntu 24.04

Simple screen run

This option runs the bot manually inside a GNU screen session under a regular Linux user. It is useful for development and debugging because you can reconnect to the bot session, but it does not start the bot automatically after a server reboot.

Install the required system packages:

sudo apt update
sudo apt install -y git python3 python3-venv python3-pip screen

Clone and configure the project in the regular user's home directory:

cd ~
git clone https://github.com/deKibi/cryptocodi-bot.git
cd cryptocodi-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
nano .env

Check the project path. This is only an example path to the cloned GitHub repository; replace it with the actual path on your server where needed:

pwd
# Example output:
# /home/denys/cryptocodi-bot

If systemd autostart is configured

This block is only relevant if you configured and started the cryptocodi-bot systemd service. Do not run the bot in screen while the systemd service is already running, because that starts two bot instances at the same time.

Check whether the service is running:

sudo systemctl status cryptocodi-bot

Stop the service before starting the bot manually in screen:

sudo systemctl stop cryptocodi-bot
sudo journalctl -u cryptocodi-bot -n 50

Start a named screen session:

screen -S cryptocodi-bot

Inside the screen session, start the bot:

source .venv/bin/activate
python main.py

Useful screen controls:

• Detach while keeping the bot running: press Ctrl+A, then D.
• Reconnect to the bot session: screen -r cryptocodi-bot.
• List sessions: screen -ls.
• Stop the bot after reconnecting: press Ctrl+C.

Run the bot again later without repeating the clone and setup steps:

cd ~/cryptocodi-bot
screen -S cryptocodi-bot
source .venv/bin/activate
python main.py

After stopping the bot in screen, start the systemd service again if needed:

sudo systemctl start cryptocodi-bot
sudo systemctl status cryptocodi-bot
sudo journalctl -u cryptocodi-bot -f

Run as a systemd service

Use this option when the bot should start together with the system and restart after crashes.

Create the service file:

sudo nano /etc/systemd/system/cryptocodi-bot.service

Replace User=denys and /home/denys/cryptocodi-bot with your Linux user and project path if needed.

[Unit]
Description=Cryptocodi Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=denys
WorkingDirectory=/home/denys/cryptocodi-bot
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/denys/cryptocodi-bot/.venv/bin/python /home/denys/cryptocodi-bot/main.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

Before starting the service, make sure the bot is not already running in screen. If it is running, reconnect and stop it with Ctrl+C:

screen -r cryptocodi-bot

Check active screen sessions if needed:

screen -ls

sudo systemctl daemon-reload
sudo systemctl enable cryptocodi-bot
sudo systemctl start cryptocodi-bot

Check service status:

sudo systemctl status cryptocodi-bot

Useful service commands:

sudo systemctl stop cryptocodi-bot
sudo systemctl status cryptocodi-bot
sudo systemctl start cryptocodi-bot
sudo systemctl restart cryptocodi-bot
sudo journalctl -u cryptocodi-bot -f

Useful journalctl controls:

• Follow live systemd logs for the bot service: sudo journalctl -u cryptocodi-bot -f.
• Stop following logs and return to the shell: press Ctrl+C.
• Pressing Ctrl+C here does not stop the bot; use sudo systemctl stop cryptocodi-bot for that.

Useful autostart commands:

sudo systemctl enable cryptocodi-bot
sudo systemctl disable cryptocodi-bot

• Enable autostart after reboot: sudo systemctl enable cryptocodi-bot.
• Disable autostart after reboot: sudo systemctl disable cryptocodi-bot.
• Disabling autostart does not stop the currently running service; use sudo systemctl stop cryptocodi-bot for that.

Logs

Logs are written to:

logs/bot.log
logs/detected_time_convertions.jsonl
logs/detected_crypto_convertions.jsonl
logs/detected_calculations.jsonl

They rotate daily and keep the last 30 days.

Structure

• time_converter/ — UTC time parsing and conversion;
• crypto_converter/ — amount parsing, coin lookup, and price fetching;
• calculator/ — parsing and safe calculation of mathematical expressions;
• telegram_bot/ — Telegram handlers, response formatting, and logging;
• telegram_bot/localization/ — translations and user language preferences;
• telegram_bot/state/ — limited in-memory state for processed messages;
• main.py — bot entry point.

License

Copyright © 2026 Denys Kibitkin. All rights reserved.

This repository is publicly available for viewing and educational reference. No permission is granted to copy, modify, distribute, or use the source code without prior written permission.