🔮 Feecast - AI Crypto Fee Prediction Platform

AI-powered fee predictions for Bitcoin and Ethereum transactions

Features • Quick Start • Architecture • API Docs • Training

---

✨ Features

• 🤖 ML-Powered Predictions - LSTM and XGBoost models trained on historical fee data
• ⚡ Real-time Data - Live fee data from mempool.space and Etherscan APIs
• 📊 Multiple Timeframes - Predictions for 1-6h, 6-24h, and 24-72h ahead
• 🎯 Confidence Scores - Know how reliable each prediction is
• 🌐 Beautiful UI - Modern React frontend with real-time updates
• 🐳 Docker Ready - One-command deployment with Docker Compose

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 14+ (or use Docker)
• Redis (optional, for caching)

Option 1: Docker Compose (Recommended)

# Clone and navigate to project
cd pridiction

# Create environment file
cp config/secrets.env.example config/secrets.env
# Edit secrets.env with your API keys

# Start all services
cd docker
docker-compose up -d

# Access the application
# Frontend: http://localhost
# API: http://localhost:8000
# API Docs: http://localhost:8000/docs

Option 2: Local Development

1. Backend Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp config/secrets.env.example config/secrets.env
# Edit with your database URL and API keys

# Initialize database (requires PostgreSQL)
psql -U postgres -f scripts/init_database.sql

# Start the API
python -m src.api.main

2. Frontend Setup

# Navigate to frontend
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Access at http://localhost:3000

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                      Frontend (React)                    │
│              http://localhost:3000                       │
└─────────────────────┬───────────────────────────────────┘
                      │ HTTP/REST
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   Backend (FastAPI)                      │
│              http://localhost:8000                       │
├─────────────────────┬───────────────────────────────────┤
│                     │                                    │
│  ┌──────────────────▼──────────────────┐                │
│  │         Prediction Service           │                │
│  │  ┌───────────┐  ┌───────────────┐   │                │
│  │  │   LSTM    │  │   XGBoost     │   │                │
│  │  │   Model   │  │    Model      │   │                │
│  │  └───────────┘  └───────────────┘   │                │
│  └──────────────────────────────────────┘                │
│                     │                                    │
└─────────────────────┼───────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
┌───────────┐  ┌───────────┐  ┌───────────┐
│ PostgreSQL│  │   Redis   │  │ Blockchain│
│  Database │  │   Cache   │  │   APIs    │
└───────────┘  └───────────┘  └───────────┘

---

📁 Project Structure

pridiction/
├── config/                 # Configuration files
│   ├── config.yaml        # Main configuration
│   └── secrets.env        # Environment secrets
├── data/                   # Data storage
│   ├── raw/               # Raw collected data
│   └── processed/         # Processed datasets
├── docker/                 # Docker configuration
│   ├── docker-compose.yml
│   ├── Dockerfile.api
│   ├── Dockerfile.collector
│   └── Dockerfile.frontend
├── frontend/               # React application
│   ├── src/
│   │   ├── App.jsx        # Main component
│   │   └── index.css      # Styles
│   └── package.json
├── models/                 # Trained ML models
│   ├── btc_lstm_*.h5
│   ├── eth_lstm_*.h5
│   └── *_scaler.pkl
├── scripts/                # Utility scripts
│   └── init_database.sql  # Database schema
├── src/                    # Python source code
│   ├── api/               # FastAPI application
│   │   ├── main.py
│   │   ├── models.py
│   │   ├── prediction.py
│   │   └── database.py
│   ├── data_collection/   # Data collectors
│   │   ├── btc_collector.py
│   │   ├── eth_collector.py
│   │   └── scheduler.py
│   ├── models/            # ML model classes
│   │   ├── lstm_model.py
│   │   └── xgboost_model.py
│   ├── preprocessing/     # Feature engineering
│   │   ├── feature_engineering.py
│   │   └── data_cleaning.py
│   └── training/          # Training pipeline
│       ├── train.py
│       └── evaluate.py
├── requirements.txt
└── README.md

---

📊 API Documentation

Base URL

• Development: http://localhost:8000
• Production: Configure in deployment

Endpoints

Health Check

GET /health

Current Fees

GET /api/current-fees/{crypto}

• crypto: BTC or ETH

Response:

{
  "crypto": "BTC",
  "fees": {
    "low": 5.0,
    "medium": 12.0,
    "high": 25.0
  },
  "timestamp": "2026-01-16T12:00:00",
  "unit": "sat/vB"
}

Generate Predictions

POST /api/predict
Content-Type: application/json

{
  "crypto": "BTC"
}

Response:

{
  "crypto": "BTC",
  "current_fees": { "low": 5.0, "medium": 12.0, "high": 25.0 },
  "predictions": [
    {
      "timeframe": "1-6 hours",
      "target_time": "2026-01-16T15:00:00",
      "fees": { "low": 6.0, "medium": 13.0, "high": 27.0 },
      "confidence": 85.0
    }
  ],
  "model_version": "v1.0.0",
  "generated_at": "2026-01-16T12:00:00"
}

Historical Data

GET /api/historical/{crypto}?hours=24

Interactive API documentation available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

🧠 Training Models

1. Collect Data

First, collect historical fee data (minimum 3-6 months recommended):

# Start data collection
python -m src.data_collection.scheduler

# Or run collectors individually
python -m src.data_collection.btc_collector
python -m src.data_collection.eth_collector

2. Train Models

from src.training.train import ModelTrainer

# Train BTC LSTM model
trainer = ModelTrainer(crypto='BTC', model_type='LSTM')
model, metrics, model_id = trainer.run_full_pipeline(
    data_filepath='postgresql://...',  # or CSV path
    epochs=100,
    batch_size=32
)

# Train ETH XGBoost model
trainer = ModelTrainer(crypto='ETH', model_type='XGBoost')
model, metrics, model_id = trainer.run_full_pipeline('data/processed/eth_fees.csv')

3. Evaluate Models

from src.training.evaluate import ModelEvaluator

evaluator = ModelEvaluator(model, X_test, y_test)
print(evaluator.generate_report())
evaluator.plot_predictions(save_path='evaluation/predictions.png')

---

⚙️ Configuration

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
ETHERSCAN_API_KEY	Etherscan API key for ETH data	Recommended
REDIS_URL	Redis connection string	No
MODELS_DIR	Directory containing trained models	No
DEBUG	Enable debug mode	No

config.yaml

# Data collection interval (seconds)
data_collection:
  interval_seconds: 300  # 5 minutes

# Model hyperparameters
model:
  lstm:
    lookback_steps: 48  # 4 hours of history
    hidden_units: [128, 64, 32]
    dropout_rate: 0.2

---

🐳 Docker Commands

# Build all services
docker-compose build

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f api

# Stop all services
docker-compose down

# Remove volumes (reset data)
docker-compose down -v

---

📈 Model Performance

Expected performance targets:

Timeframe	MAPE Target	Confidence
1-6 hours	< 15%	80-90%
6-24 hours	< 25%	65-80%
24-72 hours	< 35%	50-65%

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• mempool.space - Bitcoin fee data
• Etherscan - Ethereum gas data
• TensorFlow - ML framework
• FastAPI - API framework

---

Built with ❤️ for the crypto community