Optionix is an options and futures trading platform: a FastAPI backend that prices options, tracks portfolios and risk, and reads and writes to deployed smart contracts, paired with a React web dashboard and a React Native (Expo) mobile app. A small scikit-learn volatility model backs one live endpoint, with a statistical fallback when no trained model is present.
- Overview
- Project Structure
- Feature Status
- Technology Stack
- Architecture
- Installation and Setup
- Running the Stack
- API Surface
- Testing
- CI/CD Pipeline
- Documentation
- Contributing
- License
Optionix demonstrates an options trading workflow across a real, runnable codebase. The application tier (backend, smart contracts, and two clients) is wired and covered by tests, with the backend's blockchain service genuinely reading and writing to the deployed options and futures contracts through web3.py. A lightweight scikit-learn volatility model backs one live prediction endpoint; a separate TensorFlow training script exists for the same task but saves to a different file format than the one the live service loads, so it is not currently the model actually serving predictions.
Optionix/
├── code/
│ ├── backend/ # FastAPI service: API, auth, services, DB
│ │ ├── app/api/ # auth, market, trading, portfolio, analytics,
│ │ │ # risk, compliance, blockchain routers
│ │ ├── app/services/ # pricing_engine, risk_assessment, model_service,
│ │ │ # blockchain_service, compliance_service
│ │ ├── app/middleware/ # security, rate limiting, audit logging
│ │ └── tests/ # Backend test suite (pytest)
│ ├── blockchain/ # Hardhat project
│ │ ├── contracts/ # OptionsContract, FuturesContract (Chainlink price feeds)
│ │ └── test/ # Hardhat test suite
│ └── ai_models/
│ ├── create_model.py # scikit-learn model used by the live API
│ ├── generate_model_artifacts.py # Generates the .pkl (and optional .h5) artifacts
│ ├── training_scripts/ # TensorFlow LSTM training script (separate artifact)
│ └── quantitative/ # Black-Scholes and Monte Carlo reference implementations
├── web-frontend/ # React (Webpack) dashboard
├── mobile-frontend/ # React Native + Expo app
├── infrastructure/ # Docker, Kubernetes, Terraform, Ansible, monitoring
├── scripts/ # Setup, run, test, and lint scripts
├── docs/ # Documentation (this directory)
└── README.md
| Component | Details |
|---|---|
| API | FastAPI backend exposing endpoints for auth, market data, trading, portfolio, analytics, risk, compliance, and blockchain. There is no /api or /api/v1 prefix; routes sit directly under paths like /trading and /market. |
| Auth | bcrypt password hashing, JWT access and refresh tokens, and TOTP-based MFA (pyotp). The signing key must be at least 32 characters; the shipped default already satisfies that check, so unlike some sibling projects it is not rejected outright in production. |
| Pricing engine | Black-Scholes Greeks and a Monte Carlo European-option pricer, both run in-process. |
| Volatility model | A lightweight scikit-learn model (generated by a setup script, not committed to the repo) backs the /market/volatility endpoint, with a statistical fallback when no trained model file is present. |
| On-chain integration | A real web3.py service that reads and writes to deployed options and futures contracts: positions, margin deposits and withdrawals, option purchase and exercise, and transaction lookups. |
| Smart contracts | Hardhat-managed Solidity contracts for options and futures, each pulling prices through a genuine Chainlink AggregatorV3Interface feed. |
| Data layer | SQLAlchemy over MySQL, with Redis for caching and Alembic managing migrations. |
| Monitoring | Prometheus metrics (/metrics) and structured logging (structlog) are both genuinely wired into the running app, not just listed as dependencies. |
| Web dashboard | React app (plain JavaScript, not TypeScript) covering Home, Dashboard, Trading, Portfolio, Analytics, Risk, Compliance, Wallet, Settings, and authentication screens. |
| Mobile app | React Native (Expo) app covering the same functional areas through React Navigation, with WalletConnect for mobile wallet connections. |
| Component | Details |
|---|---|
| TensorFlow volatility model | An LSTM training script that saves a Keras .h5 file, a different artifact format than the .pkl the live model_service actually loads. |
| Black-Scholes / Monte Carlo reference module | A standalone quantitative module separate from the pricing engine the API calls, used for research and validation. |
| Area | Technology |
|---|---|
| Blockchain | Solidity, OpenZeppelin, Chainlink price feeds, Hardhat |
| Backend API | Python 3.11+, FastAPI, Uvicorn, Pydantic v2 |
| Auth | bcrypt (passlib), python-jose (JWT), pyotp (MFA) |
| Blockchain client | web3.py |
| Data layer | SQLAlchemy 2, Alembic, MySQL, Redis |
| ML / Quant | scikit-learn (live volatility model), TensorFlow (separate, disconnected training script) |
| Monitoring | prometheus-client, structlog |
| Web frontend | React 18, JavaScript, Webpack, styled-components, Chart.js, ethers.js 6 |
| Mobile frontend | React Native, Expo, React Navigation, React Native Paper, WalletConnect |
| Infrastructure | Docker, Docker Compose, Kubernetes, Terraform (AWS), Ansible |
| Monitoring stack (infra) | Prometheus, Grafana, MySQL and Redis exporters |
| CI/CD | GitHub Actions |
| Testing | pytest (backend), Hardhat (contracts), Jest (mobile); the web dashboard has Jest configured but no test files yet |
Clients
├── web-frontend (React, plain JS) ── HTTP/JSON ──┐
└── mobile-frontend (React Native) ── HTTP/JSON ──┤
▼
Backend (FastAPI, no /api prefix)
├── Routers auth, market, trading, portfolio, analytics,
│ risk, compliance, blockchain
├── Middleware security, rate limiting, audit logging (structlog)
├── Services pricing engine (Black-Scholes, Monte Carlo), volatility model
│ (scikit-learn, statistical fallback), blockchain (web3.py)
└── Data layer MySQL (SQLAlchemy + Alembic), Redis
└── /metrics Prometheus exposition endpoint
Blockchain (Hardhat / Solidity)
OptionsContract · FuturesContract, both priced via Chainlink AggregatorV3Interface feeds
Research scripts (code/ai_models)
TensorFlow LSTM training script (separate .h5 artifact, not loaded by the live API)
Black-Scholes / Monte Carlo reference module
See docs/architecture.md for detail.
Prerequisites: Python 3.11+ and Node.js 18+.
git clone https://github.com/quantsingularity/Optionix.git
cd Optionix
# Blockchain
cd code/blockchain
npm install
# Backend
cd ../backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Web frontend
cd ../../web-frontend
npm install
# Mobile frontend
cd ../mobile-frontend
npm installFor an automated setup:
git clone https://github.com/quantsingularity/Optionix.git
cd Optionix
./scripts/setup_optionix_env.sh
./scripts/run_optionix.shFull, environment-specific instructions are in docs/INSTALLATION.md.
# 1) Supporting services (from infrastructure/, Docker required)
docker compose up -d db redis
# 2) Local chain (from code/blockchain)
npx hardhat node # local chain at http://127.0.0.1:8545
# 3) Generate a volatility model artifact (from code/ai_models, optional but recommended)
python generate_model_artifacts.py
# 4) Backend (from code/backend, venv active)
uvicorn app.main:app --reload # serves http://0.0.0.0:8000, docs at /docs
# 5) Web dashboard (from web-frontend)
npm start # opens a Webpack dev server
# 6) Mobile app (from mobile-frontend)
npm start # press w for web, a for Android, i for iOSSee docs/USAGE.md and docs/CONFIGURATION.md.
Base URL http://localhost:8000. Interactive docs at /docs (Swagger) and /redoc. Metrics at /metrics.
| Group | Prefix | Highlights |
|---|---|---|
| Auth | /auth |
register, login, me, refresh |
| Market | /market |
volatility |
| Trading | /trading |
accounts, orders, positions, accounts/{id}/summary |
| Portfolio | /portfolio |
overview, allocation, performance, risk-metrics, positions/greeks-summary |
| Analytics | /analytics |
price, implied-volatility, volatility-surface, greeks/{symbol} |
| Risk | /risk |
var, stress-test, greeks/portfolio, greeks/heatmap, limits, circuit-breakers |
| Compliance | /compliance |
kyc/submit, sanctions/check, aml/alerts, gdpr/request, audit-logs |
| Blockchain | /blockchain |
wallet/{address}/balance, wallet/{address}/positions, margin/deposit, options/purchase, options/exercise |
Full request and response shapes are in docs/API.md.
# Smart contracts (from code/blockchain)
npx hardhat test
# Backend (from code/backend)
pytest
# Web (from web-frontend)
npm test
# Mobile (from mobile-frontend)
npm testThe backend suite (15 files) covers the API routers, pricing engine, and services. The Hardhat suite covers the options and futures contracts. The mobile app has real Jest tests for its auth context and formatting utilities. The web dashboard has Jest configured but no test files yet, so it is not currently exercised in CI.
GitHub Actions (.github/workflows/cicd.yml) runs four jobs on push, pull request, and manual dispatch:
| Job | Depends on | What it does |
|---|---|---|
| Code Quality Checks | - | Python formatter checks (autoflake, black) and a repository-wide Prettier check |
| Backend Tests | Code Quality Checks | Runs the pytest suite with coverage and uploads the coverage report as an artifact |
| Frontend Build | Code Quality Checks | Installs dependencies and produces the production web build (no test step) |
| Smart Contract Compile & Test | Code Quality Checks | Compiles the contracts with Hardhat and runs the contract test suite |
There is currently no CI job for the mobile app.
| Document | Contents |
|---|---|
| docs/README.md | Documentation index |
| docs/architecture.md | System architecture |
| docs/API.md | REST API reference |
| docs/INSTALLATION.md | Setup for all components |
| docs/CONFIGURATION.md | Environment variables and config |
| docs/USAGE.md | Running and using the platform |
| docs/CLI.md | Helper scripts reference |
| docs/FEATURE_MATRIX.md | Feature status, implemented vs planned |
| docs/TROUBLESHOOTING.md | Common issues and fixes |
| docs/CONTRIBUTING.md | Contribution guide |
| docs/examples/ | Worked examples |
See docs/CONTRIBUTING.md.
This project is licensed under the MIT License - see the LICENSE file for details.