## Goal

Develop an **AI-based model** to monitor and predict Ethereum gas fees in real-time, allowing users to time their transactions for cost savings. The agent should be capable of analyzing gas price fluctuations and offering insights for optimal transaction windows, helping users reduce expenses on gas-heavy networks like Ethereum.

## Scope of Work

### Data Collection & Preprocessing

• Collect historical and real-time gas price data from sourceslike Etherscan or other public blockchain analytics APIs.

• Analyze network congestion patterns and transaction types to understand factors influencing gas prices.

• Clean, aggregate, and preprocess data to identify trends and patterns for effective prediction modeling.

### Model Development

• Develop a predictive model using machine learning techniques in Python (e.g., LSTM or Prophet) to forecast short-term gas price trends over next 7 days. 

• Consider real-time adjustments based on user-specified factors, such as urgency and maximum acceptable gas fees.

Possible model architectures could include:

• Recurrent Neural Networks (RNNs), LSTMs, or GRUs for time series forecasting.

• Transformer-based models for capturing complex patterns in gas fee fluctuations.

### Evaluation & Testing

• Validate the model against historical data to measure the accuracy and reliability of gas fee predictions.

• Test the model's accuracy against historical gas fee data and assess performance with metrics such as Mean Absolute Error (MAE) and Mean Squared Error (MSE).

•  Test the API app for response speed and ensure it aligns with real-time network changes.

### Deployment Readiness

• Prepare the agent for deployment by packaging it as a microservice, integrating API calls to get predictions and trends .
 
• Document deployment steps, including data source configuration, and make it accessible in a shared drive or GitHub repository and include it on the bepro deliverable

### Requirements

• Experience with time-series forecasting, blockchain data analytics, and real-time alerting systems using RNN , Transformers,…

• Proficiency in handling transaction data and implementing machine learning models for prediction.

### Deliverables

• **Codebase**: Documented Python code, including data processing, model architecture and the pythorch trained model.

• **Trained Model**: Ready-to-deploy model (.pth file) capable of real-time predictions.

• **Documentation**: Detailed README with installation steps, data requirements, and usage guidelines

• **Performance Report**: Evaluation metrics, testing outcomes, and improvement recommendations.
 

# Deliverable
https://drive.google.com/file/d/1HPz3aChpT5kWOSdVqp9hBCVINyiA29wN

### Notes:
- I was unable to add the link above as a deliverable
- Access to the deliverable will be granted after confirmation that the requester matches the task owner
- _Extensive_ documentation exists inside `docs/` folder

---

# Ethereum Gas Fee Prediction System

An AI-powered system for monitoring and predicting Ethereum gas fees in real-time, helping users optimize transaction timing for cost savings.

## Features

- Real-time gas price data collection from Etherscan API
- LSTM, Transformer, and XGBoost prediction models
- 7-day gas price forecasting
- RESTful API for real-time predictions
- Historical data analysis and trend identification
- Performance evaluation with MAE/MSE metrics

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your Etherscan API key
```

3. Run the application:
```bash
python main.py
```

## API Usage

### Start the server
```bash
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

### Endpoints

- `GET /health` - Health check
- `GET /gas/current` - Current gas prices
- `GET /gas/predict` - 7-day gas price predictions
- `GET /gas/history` - Historical gas price data
- `POST /gas/optimize` - Get optimal transaction timing

## Model Usage

This project provides three machine learning models for gas price prediction:

- **XGBoost** - Best performance (R² > 0.996)
- **LSTM** - Time series patterns (R² > 0.991)
- **Transformer** - Complex patterns (R² > 0.976)

### **Quick Start**
```bash
# Start API server
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

# Make predictions
curl -X POST "http://localhost:8000/gas/predict" \
  -H "Content-Type: application/json" \
  -d '{"hours_ahead": 24, "model_type": "xgboost"}'
```

## Model Training

```bash
# Train specific models
python train_model.py --model lstm --epochs 100
python train_model.py --model transformer --epochs 50
python train_model.py --model xgboost

# Train all models
python train_model.py --model all --epochs 100

# Or run directly from src/scripts/
python src/scripts/train_model.py --model lstm --epochs 100
```

## Performance Metrics

- Mean Absolute Error (MAE)
- Mean Squared Error (MSE)
- Root Mean Squared Error (RMSE)
- R-squared Score

## 📚 Documentation

Comprehensive documentation is available in the `docs/` folder:

## 🚀 Quick Start

1. **Get Etherscan API Key**: Sign up at [etherscan.io](https://etherscan.io)
2. **Configure Environment**: `echo ETHERSCAN_API_KEY=your_key > .env`
3. **Collect Data**: `python collect_data.py`
4. **Train Models**: `python train_model.py`
5. **Start API**: `python main.py`

## License

MIT License

Smart Gas Fee Predictor Model for Optimal Transaction Timing on Ethereum

Details

Description

Comments