Version 1.0 | Last Updated: May 06, 2025
Important
ONLY FOR PYTHON 3.12
StockBot is a Telegram bot designed to provide users with stock market insights, including price predictions, news parsing, and fundamental analysis. Built using the Pyrogram library, the bot integrates with a deep learning model for stock price forecasting, a news parser for real-time market updates, and a database for user and stock management. The bot supports user authentication, stock tracking, and admin controls, with a token-based system for accessing premium features.
The project leverages TensorFlow for stock price predictions, yfinance for financial data, and BeautifulSoup for web scraping. It includes asynchronous news parsing, real-time notifications, and report generation in Excel format.
- User Management: Register, manage, and delete user accounts with admin controls for banning/unbanning and role assignment.
- Stock Tracking: Add/remove stocks to a user's watchlist and retrieve detailed stock information.
- Price Prediction: Forecast stock prices for the next 60 days using a pre-trained deep learning model.
- News Parsing: Fetch and filter news from Investing.com, notifying users of articles relevant to their tracked stocks.
- Fundamental Analysis: Provide buy/sell recommendations based on financial metrics like P/E ratio, ROE, and risk factors.
- Report Generation: Generate Excel reports with stock data for user analysis.
- Token System: Limit access to premium features (e.g., price predictions) using a token-based system.
- Admin Panel: Manage users, assign admin roles, send tokens, and monitor system activity.
- Multilingual Support: Planned language selection (currently in development).
- Asynchronous Processing: Handle news parsing and notifications concurrently using asyncio.
To run StockBot, ensure the following dependencies are installed:
Install dependencies:
pip install -r req.txtAdditionally, you need:
- A Telegram Bot Token (obtained via BotFather).
- API ID and API Hash from my.telegram.org.
- A pre-trained stock prediction model (
best_model.keras) and scaler (stock_scaler.save).
git clone https://github.com/Nighty3098/InvestingAssistant --recurse-submodules
cd InvestingAssistant
poetry shell
poetry install
cd src
-
Environment Variables: Create a
config.pyfile with the following:API_ID = "your_api_id" # From my.telegram.org API_HASH = "your_api_hash" # From my.telegram.org BOT_TOKEN = "your_bot_token" # From BotFather app = Client("StockBot", api_id=API_ID, api_hash=API_HASH, bot_token=BOT_TOKEN) data_file = "data.db" # SQLite database file log_file = "bot.log" # Log file logger = ... # Configure logging (see main.py)
-
Database: The bot uses SQLite (
data.db) to store user data, stocks, and tokens. Thedb.pymodule handles table creation and queries. -
Model Files: Ensure
best_model.kerasandstock_scaler.saveare inIPSA_MODEL/price/. These are required for price predictions.
-
Start the Bot: Run the main script:
python main.py
-
Interact with the Bot:
- Open Telegram and start a chat with your bot.
- Use the
/startcommand to initialize the bot. - If unregistered, you'll be prompted to register.
- Registered users see the main menu; admins see the admin panel.
-
Outputs:
client_data/: Stores generated reports (*.xlsx) and forecast plots (*.png).logs/: Contains bot logs (bot.log).data.db: SQLite database with user and stock data.
| Command | Description | Access |
|---|---|---|
/start |
Initialize the bot and show menu | All users |
/send_tokens |
Send tokens to a user | Admins only |
The bot uses inline keyboards for navigation. Key actions include:
-
User Actions:
register_user: Register a new user.my_stocks: View tracked stocks.add_stocks/remove_stocks: Manage stock watchlist.get_price: Request a stock price prediction (requires tokens).news: Fetch news for a specified period (admin-only or in development).settings: Access settings (e.g., set city, language).remove_account: Delete user account.to_main: Return to the main menu.
-
Admin Actions:
admin_panel: Access the admin panel.users_menu: List all users with details (ID, tokens, role, status).add_admin/rm_admin: Add/remove admin role for a user.ban_user/unblock_user: Ban/unban a user.
The bot uses a user_states dictionary to track user input states (e.g., adding, removing, price, news). This ensures proper handling of text inputs based on the current context.
- Purpose: Predicts stock prices for the next 60 days using a pre-trained TensorFlow model.
- Key Methods:
predict_future(ticker): Generates 60-day price forecasts.analyze(ticker, threshold=0.05): Provides a forecast summary with expected price change.predict_plt(ticker, user_id): Creates a plot of historical and forecasted prices.
- Dependencies: TensorFlow, yfinance, Matplotlib, joblib.
- Output: Forecast message, price change percentage, and a plot (
client_data/forecast_{user_id}_{ticker}.png).
- Purpose: Scrapes news from Investing.com and filters articles relevant to user-tracked stocks.
- Key Methods:
is_stocks_in_news(url, user_id, ...): Checks if tracked stocks are mentioned in an article.get_news_text(url): Extracts article text.parse_investing_news(url, period, user_id): Parses news articles within a specified period.start_parsing(period, user_id): Aggregates news from multiple sources.check_new_articles(user_id): Asynchronously checks for new articles every 2 minutes.
- Dependencies: BeautifulSoup, requests, user-agent.
- Output: Formatted news messages with title, summary, URL, and price influence prediction.
- Purpose: Provides buy/sell recommendations based on fundamental analysis.
- Key Methods:
analyze_fundamentals(ticker): Scores stocks based on P/E ratio, ROE, debt-to-equity, revenue growth, beta, and risk metrics.analyze(ticker, forecast_growth): Generates a recommendation with risk assessment.
- Dependencies: yfinance, pandas.
- Output: Recommendation message (e.g., "STRONG BUY", "SELL") with risk details.
- Purpose: Generates Excel reports with stock data.
- Key Methods:
download_data(ticker): Fetches stock data via yfinance.save_report(data): Saves data to an Excel file.
- Dependencies: pandas, yfinance.
- Output: Excel file (
client_data/{ticker}_report.xlsx).
- Purpose: Manages user data, stocks, tokens, and admin roles using SQLite.
- Key Functions (assumed based on usage):
check_user_account(user_id): Checks if a user is registered.check_user_ban(username): Checks if a user is banned.is_admin(user_id): Verifies admin status.get_users_stocks(user_id): Retrieves a user's tracked stocks.update_tokens(user_id, amount): Updates user tokens.add_city_to_db(user_id, city): Stores user city for timezone handling.
- Output: SQLite database (
data.db).
-
User Interaction:
- User sends
/start. - If unregistered, they click "Register" (
register_usercallback). - Registered users see the main menu with options like "My Stocks", "Get Price", "News", and "Settings".
- To add a stock, user selects "My Stocks" → "Add Stocks", enters a ticker (e.g., "AAPL"), and confirms.
- To get a price prediction, user selects "Get Price", enters a ticker, and receives a forecast plot and report (if tokens are available).
- User sends
-
Admin Interaction:
- Admin sends
/startand sees the admin panel. - They can list users (
users_menu), ban/unban users (ban_user/unblock_user), or send tokens (/send_tokens username tokens). - Admin can add/remove other admins (
add_admin/rm_admin).
- Admin sends
-
News Notifications:
- Users receive news updates for tracked stocks every 2 minutes (if relevant articles are found).
- News includes a title, summary, URL, and predicted price influence.
- User Authentication: Checks user registration and ban status before granting access.
- Admin Controls: Restricts sensitive actions (e.g., banning users, sending tokens) to admins.
- Token System: Limits API-heavy features (e.g., price predictions) to prevent abuse.
- Logging: Comprehensive logging for debugging and monitoring (
bot.log).
- API Limits: yfinance and Investing.com have request limits, which may cause failures during high usage.
- News Parsing: Limited to Investing.com sources and may miss relevant articles from other platforms.
- Model Accuracy: Price predictions depend on the pre-trained model's quality and may not account for sudden market events.
- Language Support: Multilingual support is in development and not fully implemented.
- Error Handling: Some errors (e.g., network failures) may not be gracefully handled for users.
- Model Dependency: Ensure
best_model.kerasandstock_scaler.saveare available. Train the model using the provided stock prediction script if needed. - Timezone Handling: News parsing uses user-specified cities for timezone conversion. Default timezone may cause inaccuracies if not set.
- Token Management: Admins must manually assign tokens using
/send_tokens. Consider automating token allocation in future updates. - Scalability: For large user bases, consider optimizing database queries and news parsing with caching or parallel processing.
- Extensibility: Add support for more news sources, technical indicators, or real-time market data feeds.
- Pyrogram Documentation: https://docs.pyrogram.org/
- TensorFlow Documentation: https://www.tensorflow.org/
- yfinance Documentation: https://github.com/ranaroussi/yfinance
- BeautifulSoup Documentation: https://www.crummy.com/software/BeautifulSoup/
- Investing.com: https://www.investing.com/
For support, open an issue on the project repository or contact the development team.
🤖 Built with Pyrogram and TensorFlow