Crypto Quant AI
Documentation

Complete technical documentation for the Crypto Quant AI platform — 40 AI agents, a unified prediction engine, INR pricing, paper trading, and a Telegram bot.

Overview

Crypto Quant AI is a full-stack quantitative trading assistant built for Indian crypto traders. Instead of showing you raw charts, it runs 40 specialized AI agents every 60 seconds and merges their outputs into a single, easy-to-understand prediction per coin.

Key Numbers

Architecture

Built on FastAPI + SQLAlchemy 2.0 async + PostgreSQL (Supabase). Agents run on APScheduler. The frontend is server-side rendered Jinja2 (no React/Vue dependency).

All 40 Agents

Unified Prediction Weights

The Unified Prediction Engine merges outputs from all agents. Each source is given a weight based on its reliability and recency.

Unified Prediction

The Unified Prediction engine (app/services/unified_prediction.py) runs on each API call. It:

1. Loads all active coins
2. Fetches the latest row from each agent's output table using bulk queries
3. Scores each source on a 0–100 bullish scale
4. Calculates a weighted average, redistributing weight from missing sources
5. Returns: bull_pct, bear_pct, confidence, recommendation

Confidence Formula

Confidence measures how far the bull score is from neutral (50%). The formula uses a ×3 multiplier so strong signals feel significant:

confidence = min( abs(bull_pct - 50) × 3, 100 )

Examples:
  72% bull  → |72-50| × 3 = 66%  confidence  (STRONG BUY)
  62% bull  → |62-50| × 3 = 36%  confidence  (BUY)
  50% bull  → |50-50| × 3 =  0%  confidence  (HOLD)
  80% bull  → |80-50| × 3 = 90%  confidence  (STRONG BUY)
    

If a source (e.g. Whale Alert, CoinGlass) is unavailable, its weight is redistributed proportionally among the active sources — the engine always produces a result even with partial data.

Signal Flow (Agent 17)

Agent 17 (Decision Agent) is the only agent that creates signals. It requires 3 consecutive cycles of the same direction before firing. This prevents noise signals.

Cycle 1: BUY → confirmation_count = 1
Cycle 2: BUY → confirmation_count = 2
Cycle 3: BUY → confirmation_count = 3 → SIGNAL CREATED ✓
Cycle 4: SELL → counter resets to 0

Signal expires: 8 hours after creation (configurable via SIGNAL_MAX_AGE_HOURS)
    

Prediction API

All APIs require the X-API-Key header.

GET /api/v1/prediction/unified

Returns merged prediction from all agents for each coin.

GET /api/v1/prediction/unified?limit=20
X-API-Key: your-api-key

Response:
{
  "status": "success",
  "count": 5,
  "data": [
    {
      "symbol": "BTCUSDT",
      "base": "BTC",
      "bull_pct": 72.4,
      "bear_pct": 27.6,
      "confidence": 66.6,
      "recommendation": "STRONG BUY",
      "sources_used": 9,
      "sources": ["Signal(STRONG_BUY,78%)", "TA(RSI=38)", "MTF(uptrend)", ...]
    }
  ]
}
    

Signals API

GET /api/v1/signals/latest

GET /api/v1/signals/latest?limit=20

Market API

GET /api/v1/market/regime/current

GET /api/v1/market/regime/current

GET /api/v1/market/fear-greed/latest

GET /api/v1/market/btc-dominance/latest

GET /api/v1/market/news?limit=20

GET /api/v1/market/whale-activity?limit=20

Telegram Bot

The bot (app/services/telegram_bot.py) runs as a background polling thread. It stores every user's Telegram chat ID in the app_users table.

Login & Signup

Authentication uses cookie-based sessions. Passwords are hashed with PBKDF2-HMAC-SHA256 (100,000 iterations). Sessions expire after 30 days.

CAPTCHA is a simple math challenge (e.g., "3 + 7 = ?") signed with HMAC — no external service needed, no user tracking.

User Profile

Visit /profile to change your password or find your Telegram bot link. Your Telegram account is linked automatically when you send /start to the bot.