Skip to main content

​
Overview

This guide will help you set up PROPPR locally and run your first alert bot. You’ll clone the repository, configure credentials, and start monitoring betting markets in under 10 minutes.
PROPPR requires Python 3.11+, MongoDB, and valid API credentials for Telegram and odds providers.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.11 or higher installed
  • MongoDB running locally or Atlas connection string
  • Git for cloning the repository
  • Telegram Bot Token (get from @BotFather)
  • Odds API Key (from odds-api.io)

​
Installation Steps

1

Clone the Repository

Clone PROPPR from GitHub and navigate to the project directory:
git clone https://github.com/Jayzinq/PROPPR.git
cd PROPPR
2

Create Virtual Environment

Set up an isolated Python environment for the project:
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
The virtual environment keeps PROPPR’s dependencies separate from your system Python packages.
3

Install Dependencies

Install all required Python packages:
pip install --upgrade pip
pip install pymongo certifi python-telegram-bot python-dotenv requests schedule gspread oauth2client pandas pytz dateutil
If you encounter issues with python-telegram-bot, ensure you’re installing version 13.x (not 20.x which has breaking changes).
4

Configure Credentials

Create a .env file in the PROPPR root directory with your credentials:
.env
# MongoDB Connection
MONGODB_URI_DEVELOPMENT="mongodb://127.0.0.1:27017/"
MONGODB_DATABASE="Cerebro"

# Telegram Bot Tokens (get from @BotFather)
TELEGRAM_TOKEN_TEAM_BOT="your_team_bot_token_here"
TELEGRAM_TOKEN_PLAYER_BOT="your_player_bot_token_here"
TELEGRAM_TOKEN_EV_BOT="your_ev_bot_token_here"
TELEGRAM_TOKEN_ARB_BOT="your_arb_bot_token_here"
TELEGRAM_TOKEN_HORSE_BOT="your_horse_bot_token_here"
TELEGRAM_TOKEN_OVERTIME_BOT="your_overtime_bot_token_here"

# Odds API Keys (from odds-api.io)
ODDS_API_KEY="your_odds_api_key_here"
ODDS_API_KEY_BACKUP_1="your_backup_key_1_here"
ODDS_API_KEY_BACKUP_2="your_backup_key_2_here"

# Optional: FotMob Stats API
FOOTYSTATS_API_KEY="your_footystats_key_here"
The credentials module (config/credentials.py) automatically loads these environment variables:
config/credentials.py
from PROPPR.config import get_mongo_connection_string, get_telegram_token

# Get MongoDB connection for current environment
mongo_uri = get_mongo_connection_string()  # Auto-detects dev/prod

# Get bot-specific Telegram token
team_bot_token = get_telegram_token('team')  # Returns TELEGRAM_TOKEN_TEAM_BOT
5

Verify MongoDB Connection

Test your MongoDB connection before running bots:
python -c "
from PROPPR.config.credentials import get_mongo_connection_string, get_mongo_database
from pymongo import MongoClient

mongo_uri = get_mongo_connection_string()
db_name = get_mongo_database()

try:
client = MongoClient(mongo_uri)
db = client[db_name]
# Test connection
db.command('ping')
print(f'✓ Connected to MongoDB: {db_name}')
print(f'  Collections: {db.list_collection_names()[:5]}')
except Exception as e:
print(f'✗ MongoDB connection failed: {e}')
"
6

Run Your First Bot

Start the Team Bot to monitor team market betting opportunities:
# Run from PROPPR parent directory (Cerebro root)
cd ..
python -m PROPPR.PropprTeamBot.runners.run_team_bot
You should see output like:
============================================================
PROPPR Player Bot Starting
============================================================
2026-03-04 10:30:15 - INFO - Connecting to MongoDB...
2026-03-04 10:30:15 - INFO - Starting Telegram bot polling...
2026-03-04 10:30:16 - INFO - Bot started successfully!
The bot will poll the database every 60 seconds for new alerts matching user preferences.

​
Running Different Bots

PROPPR includes 6 specialized alert bots. Run any of them using Python’s -m flag: 
# Team market alerts (goals, corners, cards, shots)
python -m PROPPR.PropprTeamBot.runners.run_team_bot

​
Testing Your Bot

Once your bot is running, test it by sending commands in Telegram:
1

Start a Chat

Search for your bot in Telegram using the bot username from @BotFather
2

Send /start Command

Initialize the bot and register your user:
/start
The bot should respond with a welcome message and menu options.
3

Configure Settings

Use /settings to customize your alert preferences:
/settings
Configure:
  • Minimum odds (e.g., 1.5+)
  • Maximum odds (e.g., 10.0)
  • Leagues to monitor
  • Markets to track (goals, assists, etc.)
  • Stake size for Kelly calculations
4

Wait for Alerts

The bot continuously monitors MongoDB for new betting opportunities. When a match occurs:
  • Alert appears in your Telegram chat
  • Includes bookmaker links, odds, and statistics
  • Shows recommended stake (Kelly criterion)

​
Data Pipeline Services

For bots to send alerts, data services must be running to populate MongoDB:

​
WebSocket Updater

Real-time odds updates via WebSocket connections: 
python -m PROPPR.WebsocketUpdater.runners.run_websocket_updater
From WebsocketUpdater/runners/run_websocket_updater.py:28: 
def main():
    """Start the WebSocket updater"""
    logger.info("PROPPR WebSocket Updater Starting")
    from PROPPR.WebsocketUpdater.core.websocket_updater import main as ws_main
    ws_main()

​
Unified API Poller

Polls odds APIs at regular intervals: 
python -m PROPPR.UnifiedAPIPoller.runners.run_unified_poller

​
Stats Update Pipeline

Fetches player/team statistics from FotMob: 
python -m PROPPR.StatsUpdateFM.runners.run_stats_pipeline
In development, you typically run 1-2 bots + 1 data service. In production, all services run as systemd units.

​
Common Issues

Make sure you’re running from the parent directory:
# If you're in PROPPR/, go up one level
cd ..

# Now run the bot
python -m PROPPR.PropprTeamBot.runners.run_team_bot
The import path expects the PROPPR directory to be in your current working directory or sys.path.
Your .env file is missing required credentials. Check that:
  1. .env file exists in PROPPR root directory
  2. All required variables are set (see Step 4 above)
  3. No extra quotes around values: MONGO_URI=mongodb://... not MONGO_URI="mongodb://..."
Debug with:
python -c "from PROPPR.config.credentials import print_credential_status; print_credential_status()"
The bot depends on data services to populate MongoDB:
  1. Check MongoDB: Verify collections exist and have recent data 
    from pymongo import MongoClient
from PROPPR.config.credentials import get_mongo_connection_string

client = MongoClient(get_mongo_connection_string())
db = client['Cerebro']
print(f"Player alerts: {db.all_positive_alerts.count_documents({})}")
print(f"Team alerts: {db.all_positive_team_alerts.count_documents({})}")
  2. Run data services: Start WebsocketUpdater or UnifiedAPIPoller to populate data
  3. Check settings: Use /settings in Telegram to verify your preferences allow alerts
The free tier of odds-api.io has strict rate limits:
  • 500 requests/day for free tier
  • 5000 requests/hour for paid tier
PROPPR uses the request tracker to manage API calls:
SharedServices/tracking/request_tracker.py
from PROPPR.SharedServices.tracking import get_tracker, KEY_MAIN

tracker = get_tracker(KEY_MAIN)
tracker.can_make_request()  # Returns True if within rate limit
Consider upgrading your API plan or using multiple backup keys.

​
Next Steps

Architecture

Learn how PROPPR’s microservices work together

Development

Contributing guide and code structure

Deployment

Deploy to production with systemd services

API Reference

Complete API documentation for all modules

Build docs developers (and LLMs) love

Get started for freeTalk to us