A professional, user-friendly paper trading bot that runs in Telegram with interactive features, real-time market data, and a competitive leaderboard system.
/startcreates your account with ₹50,000 starting cash/helpcomprehensive guide with command examples/search <QUERY>enhanced search with full stock details, live price, charts, and quick buy buttons/chart <TICKER> [PERIOD]sends interactive price chart images/buy <TICKER> <SHARES>buys shares at current live price/sell <TICKER> <SHARES>sells shares at current live price (FIFO)/portfolioshows cash, live stock value, net worth, P/L% with refresh & leaderboard buttons/leaderboardview top 10 traders ranked by net worth with medals 🥇🥈🥉
/send <@username or USER_ID> <AMOUNT>send money to other users/donate <@username or USER_ID> <AMOUNT>donate money (admins have unlimited funds)
- Quick Buy Buttons: Buy 1, 5, or 10 shares directly from search results
- Chart Period Buttons: Switch between 1M and 3M charts with one tap
- Refresh Portfolio: Update live prices instantly with a button
- Leaderboard Access: View rankings from portfolio with one tap
- Professional UI: Emoji-rich, well-organized displays with visual separators
- Hardcoded owner (
1350561286) with supreme authority /promoteand/demotefor admin management (owner only)/grant,/addcash,/ban,/unban(admin commands)- Owner can ban/demote any user including admins
- Admins have unlimited funds for donations
- Python 3.10+ (works on Python 3.13)
- A Telegram bot token from BotFather
- PostgreSQL database (local Docker Postgres or Railway Postgres)
main.py— Telegram botschema.sql— PostgreSQL tablesrequirements.txt— dependencies.env— local env vars (ignored by git)
From the project folder:
docker run --name paper-pg -e POSTGRES_PASSWORD=password -e POSTGRES_DB=trading_bot -p 5432:5432 -d postgres:15Confirm it is running:
docker psdocker cp schema.sql paper-pg:/tmp/schema.sql
docker exec -it paper-pg psql -U postgres -d trading_bot -f /tmp/schema.sql
docker exec -it paper-pg psql -U postgres -d trading_bot -c "\\dt"You should see users and portfolio tables.
python -m pip install -r requirements.txtThis bot reads environment variables using os.getenv. For local testing, set them in your terminal session.
PowerShell (Windows):
$env:TELEGRAM_BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
$env:DATABASE_URL = "postgresql://postgres:password@localhost:5432/trading_bot"python main.pyOpen Telegram and message your bot.
Enhanced stock search with full information display:
- Live price with change % (📈 green for up, 📉 red for down)
- Previous close, day range, 52-week range
- Volume and market cap
- Quick buy buttons (1, 5, 10 shares)
- Chart period buttons (1M, 3M)
- Lists additional results if multiple matches
Examples:
/search reliance
/search tata motors
/search tesla
Sends interactive chart image of closing prices.
Periods: 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, max
Examples:
/chart TCS.NS 3mo
/chart AAPL 1y
/chart BTC-USD 6mo
View your complete portfolio with:
- Cash balance
- Live stock values
- Net worth & total P/L%
- Detailed P/L for each holding
- 🔄 Refresh button to update live prices
- 📊 Leaderboard button to see rankings
View top 10 traders ranked by net worth:
- 🥇🥈🥉 Medal badges for top 3
- Net worth and P/L% for each trader
- Your position highlighted with ➤
- Motivational message to climb ranks
Buy stocks at current market price.
Examples:
/buy AAPL 2
/buy RELIANCE.NS 10
/buy BTC-USD 0.5
Alternative: Use quick buy buttons from /search results!
Sell stocks at current market price (FIFO).
Examples:
/sell TCS.NS 5
/sell TSLA 1
Send cash to another user.
Examples:
/send @friend 1000
/send 123456789 500
Important:
- Type
@and select recipient from Telegram's autocomplete - Or use numeric user ID
- Plain text @username won't work (Telegram Bot API limitation)
Donate money to another user.
- Normal users: Deducts from your balance (same as
/send) - Admin users: Credits target without deducting (unlimited funds)
Comprehensive guide showing:
- All commands with examples
- Supported markets (US, NSE, BSE, Crypto, Forex, Commodities)
- Ticker format examples
- Admin/owner commands (if applicable)
Available to admin users and owner (user ID 1350561286):
/grant <USER_ID> <AMOUNT>— Add funds to any user/addcash <AMOUNT>— Add funds to yourself/ban <USER_ID> [REASON]— Ban a user from the bot/unban <USER_ID>— Unban a user
Exclusive to owner (user ID 1350561286):
/promote <USER_ID>— Grant admin rights to a user/demote <USER_ID>— Revoke admin rights (even from admins)
Owner privileges:
- Can ban/demote any user including admins
- Supreme authority over all bot operations
More ticker examples:
- US:
AAPL,TSLA,MSFT - NSE (India):
RELIANCE.NS,TCS.NS,INFY.NS - BSE (India):
RELIANCE.BO,TCS.BO - Indices:
^NSEI(NIFTY 50),^NSEBANK(NIFTY Bank),^GSPC(S&P 500) - Crypto:
BTC-USD,ETH-USD
What it does:
- Fetches current live price from
yfinance - Checks if you have enough cash
- Deducts cash from
users.balance - Inserts a new lot into
portfoliowith(ticker, shares, buy_price)
Example:
/sell AAPL 1
NSE sell example:
/sell RELIANCE.NS 1
What it does:
- Fetches current live price from
yfinance - Ensures you have enough shares
- Removes shares from your stored lots (FIFO)
- Adds proceeds back to
users.balance
Shows:
- Cash balance
- Each ticker: shares, avg cost, live price, live value, unrealized P/L
- Net worth = cash + total live stock value
- Total P/L% = (net worth − 10000) / 10000 * 100
- Tables missing (
relation users does not exist): Run the schema step again. - Local Postgres SSL error: Local Docker Postgres doesn’t use SSL by default; the code auto-disables SSL when host is
localhost. - Market data:
yfinanceis best-effort. Some tickers/markets can be delayed or unavailable.
- Create a Railway project
- Add a PostgreSQL database
- Set variables:
TELEGRAM_BOT_TOKENDATABASE_URL(Railway provides this)
- Run
schema.sqlonce on the Railway database - Deploy the repo (Procfile runs
python main.py)