IndexVol - Indian Options Volatility Surface Platform

An institutional-grade options analytics platform for NIFTY and BANKNIFTY, featuring real-time volatility surface modeling, risk analytics, and historical data replay capabilities.

---

Overview

IndexVol is an offline-first options analytics platform that ingests official NSE derivatives settlement data and provides comprehensive volatility analysis tools. The system supports live-replay simulation for intraday strategy testing without requiring market hours access.

Built with a Bloomberg Terminal-inspired dark theme, the platform delivers institutional-grade aesthetics with professional data visualization powered by Plotly.js.

---

Key Features

Analytics Pages

Page	Description
Dashboard	Real-time overview with spot price, ATM volatility, volatility regime indicators, and skew metrics
Option Chain	Full option chain with IV, Greeks (Delta, Gamma, Vega, Theta), pagination, and type filtering (Calls/Puts)
Volatility Smile	Interactive IV vs Strike visualization across multiple expiries with selectable expiry toggles
3D Volatility Surface	Interactive 3D surface and heatmap views with Viridis colorscale, ATM Vol, Skew, and Term Slope metrics
Risk Analytics	Volatility regime detection (LOW/NORMAL/ELEVATED/HIGH/EXTREME), ATM term structure, skew profiles, butterfly spreads
Offline Ingestion	Calendar-based date selection, automated NSE Bhavcopy download, and full analytics pipeline execution
Market Replay	WebSocket-powered historical data replay with adjustable speed (0.5x-10x), live tick feed terminal

System Features

• Instrument Switching: Seamless toggle between NIFTY and BANKNIFTY from the header dropdown
• Data Date Display: Shows currently loaded data date with automatic updates after ingestion
• Status Indicator: Live/Offline mode badge showing "LIVE REPLAY" or "OFFLINE MODE"
• Responsive Design: Mobile-friendly sidebar with hamburger menu
• Dark Theme: HSL-based theming with teal (#1e7898) primary color
• Monospace Data Display: JetBrains Mono font for numerical precision

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     React Frontend (Vite)                        │
│  Dashboard │ Option Chain │ Smile │ Surface │ Risk │ Replay     │
└──────────────────────────┬──────────────────────────────────────┘
                           │ REST API / WebSocket
┌──────────────────────────▼──────────────────────────────────────┐
│                     FastAPI Backend                              │
│     API Routes │ WebSocket Handler │ Data Context               │
└──────┬─────────────┬─────────────┬─────────────┬────────────────┘
       │             │             │             │
┌──────▼──────┐ ┌────▼─────┐ ┌─────▼─────┐ ┌─────▼──────┐
│  Ingestion  │ │ Analytics│ │  Cleaning │ │   Replay   │
│  Pipeline   │ │  Engine  │ │  Engine   │ │   Engine   │
│  (NSE Data) │ │ (IV/Grks)│ │ (Filters) │ │ (WebSocket)│
└──────┬──────┘ └────┬─────┘ └─────┬─────┘ └─────┬──────┘
       │             │             │             │
┌──────▼─────────────▼─────────────▼─────────────▼────────────────┐
│                    PostgreSQL Database                           │
│   Instruments │ Raw Options │ Clean Options │ IV/Greeks │        │
│   Volatility Smiles │ Surfaces │ Risk Metrics                   │
└─────────────────────────────────────────────────────────────────┘

---

Tech Stack

Backend

Technology	Purpose
Python 3.11+	Core runtime
FastAPI	REST API & WebSocket server
PostgreSQL 15+	Primary database
SQLAlchemy	ORM & database models
NumPy/SciPy	Numerical computations
Black-Scholes	IV computation via Newton-Raphson

Frontend

Technology	Purpose
React 18	UI framework
React Router DOM	Client-side navigation
Tailwind CSS 3	Utility-first styling
Plotly.js	Interactive 2D/3D charts
Lucide React	Icon library
Vite	Build tool & dev server

---

Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL 15+
• Node.js 18+

Backend Setup

# Clone repository
git clone https://github.com/nesarw/IndexVol.git
cd IndexVol

# Create virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Configure environment
copy .env.example .env       # Windows
# cp .env.example .env       # Linux/Mac
# Edit .env with your database credentials

# Initialize database
python -c "from backend.db.models import Base, engine; Base.metadata.create_all(engine)"

# Run backend server
uvicorn backend.api.main:app --reload

Frontend Setup

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Access Points

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Documentation	http://localhost:8000/docs
WebSocket	ws://localhost:8000/ws

---

API Endpoints

Health & Info

Method	Endpoint	Description
GET	/health	System health check
GET	/api/data-info	Get loaded data date and info
GET	/api/instruments	List available instruments

Data Ingestion

Method	Endpoint	Description
POST	/api/ingest-offline?date_str=2024-01-05	Trigger full offline ingestion pipeline
POST	/api/clean?symbol=NIFTY	Run data cleaning pipeline
POST	/api/compute-iv	Compute IV and Greeks
POST	/api/build-surface?symbol=NIFTY	Build volatility surface

Option Data

Method	Endpoint	Description
GET	/api/raw-options?symbol=NIFTY	Get raw option chain data
GET	/api/clean-options?symbol=NIFTY	Get cleaned option data
GET	/api/iv-greeks?symbol=NIFTY	Get IV and Greeks data

Volatility Analytics

Method	Endpoint	Description
GET	/api/smile?symbol=NIFTY	Get volatility smile by expiry
GET	/api/surface?symbol=NIFTY	Get 3D volatility surface data
GET	/api/atm-term-structure?symbol=NIFTY	Get ATM term structure
GET	/api/skew-metrics?symbol=NIFTY	Get skew metrics by expiry
GET	/api/vol-regime?symbol=NIFTY	Get volatility regime analysis

Market Replay

Method	Endpoint	Description
POST	/api/replay/start?date_str=2024-01-05&speed=1.0	Start historical replay
POST	/api/replay/stop	Stop active replay
WS	/ws	WebSocket for streaming ticks

---

Project Structure

IndexVol/
├── backend/
│   ├── api/
│   │   └── main.py              # FastAPI app, all endpoints
│   ├── ingestion/
│   │   ├── nse_fetcher.py       # NSE data fetching
│   │   ├── nse_downloader.py    # Bhavcopy download
│   │   ├── normalizer.py        # Data normalization
│   │   ├── db_ingestion.py      # Database insertion
│   │   └── scheduler.py         # Pipeline orchestration
│   ├── cleaning/
│   │   └── cleaner.py           # Data quality filters
│   ├── analytics/
│   │   ├── iv_engine.py         # Black-Scholes IV solver
│   │   ├── smile.py             # Smile construction
│   │   ├── surface.py           # Surface modeling
│   │   └── risk_metrics.py      # Skew, regime detection
│   ├── replay_engine/
│   │   ├── replay_controller.py # Replay orchestration
│   │   └── websocket_simulator.py # WebSocket manager
│   ├── db/
│   │   └── models.py            # SQLAlchemy models
│   └── config/
│       └── settings.py          # App configuration
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Layout.jsx       # Main layout with sidebar
│   │   │   └── Calendar.jsx     # Date picker component
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx         # Overview page
│   │   │   ├── OptionChain.jsx       # Option chain table
│   │   │   ├── VolatilitySmile.jsx   # Smile charts
│   │   │   ├── VolatilitySurface.jsx # 3D surface/heatmap
│   │   │   ├── RiskAnalytics.jsx     # Risk metrics
│   │   │   ├── OfflineIngestion.jsx  # Data ingestion UI
│   │   │   └── ReplaySession.jsx     # Market replay
│   │   ├── context/
│   │   │   ├── InstrumentContext.jsx # Instrument state
│   │   │   └── DataContext.jsx       # Data date state
│   │   ├── services/
│   │   │   └── api.js           # API client functions
│   │   ├── App.jsx              # Router setup
│   │   └── index.css            # Tailwind + custom theme
│   ├── tailwind.config.js       # Tailwind configuration
│   └── vite.config.js           # Vite configuration
├── data/
│   ├── raw/                     # Downloaded Bhavcopy files
│   ├── extracted/               # Unzipped CSVs
│   └── clean/                   # Processed data
├── .env.example                 # Environment template
├── requirements.txt             # Python dependencies
├── docker-compose.yml           # Docker setup
└── README.md

---

Data Sources

NSE Official Files

The platform downloads official FO Bhavcopy files from NSE Archives containing:

• Settlement prices for all F&O contracts
• Open Interest data
• Volume information

Recommended Test Dates

Date	Description	Volatility Level
2024-01-05	Recommended first test	Normal
2024-01-24	Pre-expiry week	Elevated
2024-02-01	Union Budget day	High
2024-02-29	Monthly Expiry	Elevated

---

Configuration

Environment Variables (.env)

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/indexvol

# API Settings
API_HOST=0.0.0.0
API_PORT=8000

# CORS Origins
CORS_ORIGINS=["http://localhost:5173"]

Backend Settings (backend/config/settings.py)

# Market Parameters
risk_free_rate = 0.065      # RBI reference rate
trading_days_per_year = 252

# Data Cleaning Thresholds
max_bid_ask_spread_pct = 0.20
min_volume = 0
max_otm_pct = 0.30

# Lot Sizes (NSE Standard)
nifty_lot_size = 25
banknifty_lot_size = 15

---

Recent Updates

v0.3.0 (December 2024)

• Calendar Component: Custom date picker with visual calendar for ingestion
• Data Context: Automatic data date refresh after ingestion
• Status Indicator: Dynamic "OFFLINE MODE" / "LIVE REPLAY" badge
• Header Enhancement: Larger IndexVol branding with instrument dropdown
• UI Polish: Fixed Plotly toolbar alignment, improved card styling
• Risk Analytics: Enhanced regime cards with color-coded borders

v0.2.0 (December 2024)

• UI Redesign: Complete frontend overhaul with Bloomberg Terminal aesthetics
• Theme System: HSL-based theming with teal primary color
• Chart Improvements: Plotly.js integration with consistent styling
• Data Cleaning Fix: Historical data processing improvements
• Stability: Bug fixes for option chain and analytics pages

v0.1.0 (Initial Release)

• Core ingestion pipeline for NSE Bhavcopy
• Black-Scholes IV computation with Newton-Raphson
• Basic API endpoints
• PostgreSQL database schema

---

Docker Support

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

---

Contributing

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

---

🔧 Troubleshooting

Virtual Environment Issues

If you encounter errors related to python.exe not found or permission denied:

# Deactivate and remove existing venv
deactivate
Remove-Item -Recurse -Force venv

# Recreate virtual environment
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt

Port Conflicts

Issue	Solution
Backend fails to start	Ensure port 8000 is free: `netstat -ano
Frontend fails to start	Ensure port 5173 is free: `netstat -ano

Database Connection Issues

# Verify PostgreSQL is running
pg_isready -h localhost -p 5432

# Check connection string in .env
DATABASE_URL=postgresql://user:password@localhost:5432/indexvol

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• NSE India - Official derivatives data source
• Black-Scholes Model - Options pricing theory
• FastAPI & React Communities - Framework development
• Plotly.js - Interactive visualization library

---

Disclaimer: This platform is designed for educational and research purposes only. Always verify data accuracy before making trading decisions. Past performance does not guarantee future results.