Skip to content

Home

Jump to bottom
Erfan Hosseini edited this page Dec 12, 2025 · 4 revisions

GitHub Wiki Content for TradeTracker

Here is the structured content for your GitHub Wiki. You can create these pages in the "Wiki" tab of your repository.

🏠 Page: Home

Welcome to the TradeTracker Wiki!

TradeTracker is a high-performance Telegram bot designed to help professional traders journal their trades, track profits and losses (PnL), and analyze performance with precision using Python and PostgreSQL.

📚 Documentation Sections

  1. Installation Guide - Step-by-step instructions to set up the bot on Windows, Linux, or a VPS.
  2. User Manual - How to use every feature of the bot (Logging trades, generating reports, editing).
  3. Database Schema - Technical details about the PostgreSQL structure for developers.
  4. Troubleshooting - Common errors and how to fix them.

🚀 Page: Installation Guide

Prerequisites

Before you start, ensure you have the following installed:

  • Python 3.8+
  • PostgreSQL (Running locally or on a server)
  • Git

Step 1: Clone the Repository

git clone https://github.com/Questionist/TradeTracker.git
cd TradeTracker

Step 2: Install Dependencies

We recommend using a virtual environment.

# Create virtual environment (Optional)
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Install libraries
pip install -r requirements.txt

Step 3: Database Setup

  1. Open your PostgreSQL tool (pgAdmin or terminal).
  2. Create a new database (e.g., tradetracker_db).
  3. The bot will automatically create the necessary tables (calcbalances, balances, calcmessageid) on the first run using the init_db() function.

Step 4: Configuration

Open main_en.py and update the constants at the top:

TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
DB_HOST = "localhost"
DB_USER = "postgres"
DB_NAME = "tradetracker_db"
DB_PASS = "your_password"
SUDOS = (12345678, 87654321) # Add your numeric Telegram ID here

Step 5: Run the Bot

python main_en.py

📖 Page: User Manual

1. Starting the Bot

Send /start to the bot. If your User ID is in the SUDOS list, you will see the main menu.

  • Note: Unauthorized users will receive an access denied message.

2. Logging a New Trade

Click on "New Report". The bot will guide you through a wizard:

  1. Currency: Enter the ticker (e.g., BTCUSD, EURUSD).
  2. Balance: Enter your current account balance (only asked if it's the first trade of the day).
  3. Lots: Enter the lot size (e.g., 0.1, 1.0).
  4. Type: Choose Long or Short.
  5. Entry Targets: Enter one or multiple entry prices.
  6. Take Profit (TP): Enter one or multiple TP targets.
  7. Stop Loss (SL): Enter your SL price.

Result: The bot calculates the potential PnL, updates your database, and shows the new balance.

3. Viewing Reports

  • Daily Report: Shows a list of all trades for a selected day. Click on an ID to see full details (Entry, Exit, PnL per trade).
  • Weekly Report: Groups trades by week (Mon-Sun). Shows total Profit/Loss for that week.
  • Monthly Report: Aggregates performance by month. Useful for long-term analysis.

4. Editing & Deleting

  • Edit Balance: If you made a deposit or withdrawal, you can manually update the balance for a specific day.
  • Delete Report: Removes a specific trade entry. The bot automatically recalculates the linked daily balance.

⚙️ Page: Database Schema

For developers contributing to TradeTracker, here is the database structure:

Table: balances

Stores the snapshot of the account for each trading day.

Column Type Description
id BIGSERIAL Primary Key
userid BIGINT Telegram User ID
day TEXT Date (YYYY-MM-DD)
balance FLOAT Account balance for that day
forIds TEXT[] Array of trade IDs linked to this day

Table: calcbalances

Stores detailed information about individual trades.

Column Type Description
id BIGSERIAL Primary Key
currency TEXT Asset name (e.g., XAUUSD)
lots FLOAT Position size
type TEXT 'long' or 'short'
entrytarget FLOAT[] List of entry prices
takeprofittarget FLOAT[] List of TP prices
stoploss FLOAT Stop Loss price
totalbalance FLOAT[] Raw PnL value in USD

🔧 Page: Troubleshooting

Q: I get "DB Init Error" when running the bot. A: Check your DB_USER and DB_PASS in main_en.py. Ensure the PostgreSQL service is running.

Q: Example: The bot doesn't respond to /start. A: Ensure you have added your Telegram User ID to the SUDOS tuple in main_en.py and restarted the bot.

Q: I installed requirements but still get "ModuleNotFoundError". A: Ensure you activated your virtual environment before running the bot.

Developed with ❤️ by Questionist.ir

Clone this wiki locally