StrideBot

StrideBot is a production-oriented Telegram assistant for crypto and macro market intelligence. It combines real-time market data, AI-generated analysis, watchlists, alerts, premium subscriptions, coupon workflows, scheduled channel publishing, and an HTTP dashboard/health API.

---

Table of Contents

• What StrideBot Does
• Core Capabilities
• Architecture
• Project Structure
• Requirements
• Configuration
• Run Locally
• Telegram Commands
• HTTP Health + Dashboard API
• Data Storage
• Background Jobs and Channel Posting
• Operational Notes
• Testing
• Troubleshooting

---

What StrideBot Does

StrideBot is designed to be more than a simple “/price” bot:

• Handles free, premium, and admin user flows.
• Provides AI responses, analysis, and summaries.
• Tracks user conversation history and preferences.
• Supports price alerts and personal watchlists.
• Exposes web endpoints for live stats, rates, and status.
• Runs scheduler-driven content workflows for channel intelligence posts.

---

Core Capabilities

User-facing

• /price, /top10, /marketupdate for market snapshots.
• /analysis, /summary, /forexanalysis, /polymarket for AI-assisted market interpretation.
• /watch, /watchlist, /unwatch for tracked assets.
• /alert, /myalerts, /cancelalert for alerting.
• /news, /rates, /forex, /stock for cross-asset information.

Premium and monetization

• Premium command scopes and plan gating.
• Telegram Stars payment support and payment record tracking.
• Coupon creation + redemption workflows.

Admin + operations

• Broadcast and user-management commands.
• Persistent analytics and audit logging.
• Health/dashboard HTTP service with multiple JSON endpoints.
• Sentry integration, structured logging, and graceful process termination behavior.

---

Architecture

StrideBot is a Python application centered around python-telegram-bot:

1. bot/bot.py initializes environment, logging, signal handlers, Telegram app, command scopes, middleware, scheduler, and health server.
2. bot/handlers/ contains command and interaction handlers split by domain (core, market, alerts, premium, admin).
3. bot/ai.py and prompt modules (bot/prompts/*.py) drive model responses and formatting.
4. bot/crypto.py, bot/news_sources.py, and related modules fetch market/news signals.
5. bot/scheduler.py generates recurring channel intelligence posts and breaking-news workflows.
6. bot/health.py runs an HTTP server for dashboard and monitoring endpoints.
7. bot/database.py provides DB initialization and persistence functions with Postgres-first + SQLite fallback.

---

Project Structure

bot/
  bot.py                    # Main runtime entrypoint
  handlers/
    core.py                 # Shared UX + general command flows
    market.py               # Market commands
    alerts.py               # Alert workflows
    premium.py              # Premium-specific features
    admin.py                # Admin-only controls
  ai/                       # AI integration package
    client.py               # Main response functions
    tiers.py                # Tier configuration
    search.py               # Tavily search
    pipeline.py             # Mode detection + response shaping
    context.py              # Token budgeting
    background.py           # Background thinking
  core/
    config.py               # Centralized env var loading
  database/                 # Domain modules
    connection.py           # Connection pool
    schema.py               # DB initialization
    users.py, history.py, premium.py, alerts.py, watchlist.py,
    predictions.py, memory.py, analytics.py, scheduler_state.py,
    security.py, narrative.py, referrals.py
  intelligence/             # Market intelligence modules
    whale.py                # Whale tracking
    polymarket.py           # Prediction markets
    trends.py               # Trend detection
    market_regime.py        # Market regime analysis
    news_sources.py         # News feeds
  providers/                # Provider adapters
    protocols.py            # Protocol interfaces
    adapters/               # GroqAdapter, CryptoAdapter, NewsAdapter
  events/                   # Event bus system
  scheduler/                # Timed posting + automation
  prompts/                  # Prompt builders by feature
  tests/                    # All test files
  health.py                 # HTTP health/dashboard APIs

README.md                   # This file
pyproject.toml              # Python project metadata + dependencies
requirements.txt            # Pip install requirements
uv.lock                     # Locked dependency graph

---

Requirements

• Python 3.11+
• Telegram bot token
• AI provider/API credentials used by your deployment mode
• Optional: PostgreSQL DATABASE_URL (otherwise SQLite fallback is used)

Install dependencies (pick one method):

pip install -r requirements.txt

or

uv sync

---

Configuration

Create a .env file (typically in project root or bot/, depending on your launch context) with at least:

TELEGRAM_BOT_TOKEN=...
ADMIN_USER_ID=...

Commonly used variables in this codebase include:

• TELEGRAM_BOT_TOKEN – required.
• ADMIN_USER_ID – required for admin command scope.
• CHANNEL_ID – optional channel posting target.
• DATABASE_URL – enables PostgreSQL mode.
• LOG_LEVEL – default INFO.
• DAILY_AI_CAP – global daily AI request cap.
• SENTRY_DSN – error monitoring.
• CMC_API_KEY – optional CoinMarketCap-backed fear/greed source.
• BOT_USERNAME – optional handler behavior tuning.

Note: The repository includes integrations that rely on additional provider keys depending on which features you actively use (AI/news/market extensions). Ensure all required secrets for your enabled paths are set before production deploys.

---

Run Locally

From repo root:

python bot/bot.py

Alternative (if your env is under bot/ and you run there):

cd bot
python bot.py

At runtime, StrideBot starts:

• Telegram long-polling bot.
• Background scheduler jobs.
• HTTP health/dashboard server.

---

Telegram Commands

Command availability is tier-based (free/premium/admin). Current command registration in bot/bot.py includes:

Free / default scope

/start, /help, /price, /top10, /marketupdate, /analysis, /watch, /polymarket, /unwatch, /watchlist, /alert, /myalerts, /cancelalert, /news, /summary, /premium, /redeem, /forex, /forexanalysis, /rates, /clear, /about

Premium scope additions

/stock, /myplan (plus premium-extended command descriptions)

Admin scope additions

/stats, /broadcast, /listusers, /addpremium, /removepremium, /createcoupon, /listcoupons, /testpost, /trending, /approvetrend

---

HTTP Health + Dashboard API

bot/health.py exposes operational endpoints for monitoring and front-end dashboard use.

Examples:

• / – liveness text response.
• /dashboard – dashboard page.
• /api/health/all – aggregate service health.
• /api/stats – dashboard stats payload.
• /api/prices – multi-asset price snapshot.
• /api/news – latest article feed.
• /api/feargreed – market sentiment value.
• /api/rates – FX rate payload.
• /api/leaderboard – prediction leaderboard.
• /api/prediction/open-price – cached daily BTC open.
• /api/security-log, /api/flags, /api/flags/set – ops/security controls.

---

Data Storage

The persistence layer supports:

• PostgreSQL when DATABASE_URL is available and psycopg2 is installed.
• SQLite fallback (stridebot.db) otherwise.

Schema initialization in init_db() includes tables such as:

• users, history
• alerts, watchlist
• premium_users, premium_subscriptions
• payment_records, coupons, coupon_redemptions
• admin_audit_log, analytics
• scheduler_cooldowns, posted_content
• predictions

---

Background Jobs and Channel Posting

Scheduler logic in bot/scheduler.py powers:

• recurring briefing/digest style posts,
• AI-composed market narratives,
• breaking-news trigger detection with cooldown handling,
• generated post-header images (Pillow-based rendering),
• anti-duplicate posting controls via cooldown and content-hash storage.

---

Operational Notes

• SIGTERM/SIGINT are trapped early to ensure fast old-instance shutdown during deploy rollovers.
• Webhooks are proactively cleared to avoid polling/webhook conflicts.
• Logging writes to console and rotating bot.log.
• Global error handler reports non-transient failures and can notify admin chat.
• Message and redeem rate limiting are applied in handlers.

---

Testing

uv run pytest bot/tests/ -v

If your environment lacks optional dependencies or credentials, focus on unit paths that do not require external APIs.

---

Troubleshooting

• TELEGRAM_BOT_TOKEN is missing: ensure env file is loaded in the same working directory context used to run the bot.
• Admin commands unavailable: confirm ADMIN_USER_ID is set and parseable as integer.
• Unexpected SQLite use: set DATABASE_URL and install psycopg2.
• Polling conflicts: ensure only one active bot process is running for the token.
• Feature responses look degraded: verify external provider keys and network reachability.

---

If you are extending StrideBot, start with bot/bot.py (startup orchestration), bot/handlers/ (feature routing), and bot/database.py (persistent model).