⚡ NullRisk (TradeLab)

Institutional Multi-Asset Paper Trading Terminal & Risk Engine

An ultra-low latency, high-density financial paper trading terminal built for equities (NSE / NASDAQ), crypto, forex, derivatives (BSM Options Greeks), and leveraged margin contracts with 3D WebGL risk visualization.

Explore Features • System Architecture • Options Greeks Engine • API Reference • Quickstart

📸 Terminal & Portfolio Interface

NullRisk Market Explorer & Interactive Candlestick Order Ticket

Figure 1: Full-screen interactive Lightweight Charts OHLC candlestick engine, instant execution ticket, and real-time AI analyst commentary.

NullRisk Asset Ledger, NAV Equity Curve & Performance Gauge

Figure 2: Real-time NAV equity curve, dual-axis performance risk gauge (-10% to +10%), and dynamic margin health tracker.

🌟 Executive Overview & Value Proposition

NullRisk is an institutional-grade simulation environment engineered for quantitative traders, finance students, and market enthusiasts who demand realistic market execution without capital exposure. Unlike conventional retail simulators with artificial delays and simplified mechanics, NullRisk incorporates:

Real-World Execution Dynamics: Instant fills or limit order queuing matching real-time market bid/ask spreads.
Atomic Balance & Position Deductions: Supabase PostgreSQL with strict Row Level Security (RLS) guaranteeing zero race conditions, negative balances, or double-spends.
Institutional Design Engineering: High-density 21st.dev aesthetic (Linear / Hyperliquid / Bloomberg inspired), calibrated Genjutsu spring physics (stiffness: 450, damping: 30), and an interactive Three.js 3D Risk & Liquidity Hologram.
Comprehensive Derivative Support: Native European Options pricing powered by the analytical Black-Scholes-Merton model with real-time Greek sensitivities ($\Delta, \Gamma, \Theta, \nu$) and dynamic implied moneyness.

🚀 Key Features

1. Multi-Asset Market Explorer & Trading Terminal

Equities (NSE India & US Global): Live streaming quotes across major tickers (RELIANCE.NS, TCS.NS, HDFCBANK.NS, AAPL, NVDA, TSLA, MSFT).
Cryptocurrency (24/7): High-frequency simple and spot price feeds (BTC, ETH, SOL, DOGE).
Forex (24/5 Interbank): Real-time currency exchange rates (USD/INR, EUR/USD, GBP/USD).
Interactive Candlestick Charts: High-performance TradingView-style Lightweight Charts (OHLC) with real-time responsive resizing.
AI Market Analyst: On-demand Claude / Gemini automated market trend breakdown and technical support/resistance analysis.

2. High-Density Portfolio Ledger & Risk Controls

NAV Area Equity Curve: Recharts gradient area visualization tracking total net worth and realized profits.
Active Spot Holdings Table: Real-time position mark-to-market valuations, average buy basis, and floating P&L readouts.
1-Click Position Liquidation: Direct navigation and immediate market sell execution with normalized symbol parsing.
Target Milestone Tracker: Automatic ₹10,00,000 liquid mock balance bonus unlock upon achieving +10.00% net portfolio return.

3. Leveraged Margin Contracts & Liquidation Protocol

Configurable Leverage Multipliers: Execute long/short leveraged positions from 2x up to 50x.
Dynamic Debt-to-Collateral Monitoring:
- HEALTHY (< 80% borrowed ratio): Nominal operational tier.
- MODERATE (80% - 150% borrowed ratio): Elevated risk caution.
- CRITICAL (> 150% borrowed ratio): Immediate liquidation protocol triggered.
Emergency Contract Liquidate: 1-click contract close to prevent catastrophic equity drawdowns.

4. Black-Scholes Options Greeks Terminal

Analytical BSM Pricing Engine: Full theoretical pricing for Call and Put options based on spot price ($S$), strike ($K$), time to expiry ($T$), risk-free rate ($r$), and implied volatility ($\sigma$).
Greeks Sensitivity Matrix:
- Delta ($\Delta$): Rate of change of option price per ₹1 move in the underlying asset.
- Gamma ($\Gamma$): Rate of change of Delta per ₹1 move.
- Theta ($\Theta$): Daily time decay loss.
- Vega ($\nu$): Sensitivity to a 1% shift in implied volatility.
Interactive Strike Ladder: Visual horizontal scrubber highlighting In-The-Money (ITM), At-The-Money (ATM), and Out-of-The-Money (OTM) contracts.

5. Interactive 3D Risk & Liquidity Hologram (`3dviz-pro-max`)

Built with Three.js WebGL:
- Procedural 650-point Fibonacci particle sphere with inner geodesic wireframe lattice.
- 3 asynchronous orbital liquidity rings representing global capital flow.
- Dynamic P&L Reactive Shaders: Radiant Emerald/Cyan matrix glow when profitable, calibrated Rose/Amber cautionary pulse during drawdowns.
- GPU-accelerated BufferGeometry running at a locked 60fps with damped mouse parallax interaction.

6. Global Exchange Feed Monitor & Telemetry

Interactive Topbar Status: Real-time operational status for NSE India (09:15 - 15:30 IST), NASDAQ / NYSE (09:30 - 16:00 EDT), Crypto 24/7, and Forex Interbank.
Low-Latency Telemetry: Live ping latency indicators (~12ms) and TLS 1.3 execution bridge health checks.

7. Notification Center & Competitive Leaderboard

Unread Badge & Live Beacon: Dynamic notification popover categorizing order fills, margin alerts, and milestone updates.
Global Trader Leaderboard: Weekly and all-time leaderboard rankings with metallic podium highlights (🥇 Gold, 🥈 Silver, 🥉 Bronze) and 1-click Portfolio Replication.

📐 System Architecture

flowchart TD
    subgraph Client["Presentation Layer (Next.js 16 + React 19)"]
        UI["High-Density Bento Terminal"]
        ThreeCanvas["Three.js 3D Risk Hologram"]
        Charts["Lightweight Charts (OHLC)"]
        Nav["Topbar & Sidebar (Genjutsu Springs)"]
    end

    subgraph APIRoutes["Next.js Route Handlers (Edge & Node.js)"]
        TradeAPI["/api/trade/execute"]
        MarginAPI["/api/margin/open & close"]
        OptionsAPI["/api/options/price & buy"]
        SummaryAPI["/api/portfolio/summary"]
        MarketAPI["/api/market/quote & ohlc"]
    end

    subgraph MarketData["Live External Data Providers"]
        Finnhub["Finnhub API (Equities & News)"]
        CoinGecko["CoinGecko (Crypto Quotes)"]
        TwelveData["Twelve Data (OHLC Candlesticks)"]
        ExchangeRate["ExchangeRate-API (Forex FX)"]
    end

    subgraph Database["Supabase PostgreSQL (Enterprise Tier)"]
        Profiles[("profiles (Balance & Net Worth)")]
        Holdings[("holdings (Spot Assets)")]
        Margin[("margin_positions (Leveraged Contracts)")]
        Options[("option_positions (BSM Contracts)")]
        Transactions[("transactions (Ledger Audit Log)")]
        RLS["Row Level Security (RLS Policies)"]
    end

    UI --> Nav
    UI --> ThreeCanvas
    UI --> Charts
    UI --> APIRoutes

    APIRoutes --> MarketData
    APIRoutes --> RLS
    RLS --> Database

🔬 Black-Scholes Options Greeks Engine

NullRisk implements the standard analytical solution for European options pricing:

$$\begin{aligned} d_1 &= \frac{\ln(S / K) + (r + \frac{\sigma^2}{2}) T}{\sigma \sqrt{T}} \\ d_2 &= d_1 - \sigma \sqrt{T} \end{aligned}$$

Theoretical Option Values

$$\begin{aligned} C(S, T) &= S \cdot \Phi(d_1) - K e^{-rT} \cdot \Phi(d_2) \\ P(S, T) &= K e^{-rT} \cdot \Phi(-d_2) - S \cdot \Phi(-d_1) \end{aligned}$$

Greek Sensitivities

Greek	Formula (Call)	Formula (Put)	Description
Delta ($\Delta$)	$\Phi(d_1)$	$\Phi(d_1) - 1$	First derivative w.r.t. spot price ($\frac{\partial V}{\partial S}$)
Gamma ($\Gamma$)	$\frac{\phi(d_1)}{S \sigma \sqrt{T}}$	$\frac{\phi(d_1)}{S \sigma \sqrt{T}}$	Second derivative w.r.t. spot price ($\frac{\partial^2 V}{\partial S^2}$)
Theta ($\Theta$)	$-\frac{S \phi(d_1) \sigma}{2\sqrt{T}} - r K e^{-rT} \Phi(d_2)$	$-\frac{S \phi(d_1) \sigma}{2\sqrt{T}} + r K e^{-rT} \Phi(-d_2)$	Rate of time decay per trading day ($\frac{\partial V}{\partial T}$)
Vega ($\nu$)	$S \sqrt{T} \phi(d_1) \cdot 0.01$	$S \sqrt{T} \phi(d_1) \cdot 0.01$	Sensitivity per 1% change in implied volatility ($\frac{\partial V}{\partial \sigma}$)

🛠️ Technology Stack

Domain	Technology	Description
Framework	Next.js 16.2.6 (Turbopack)	Modern App Router, Server Components & Dynamic Route Handlers
UI Library	React 19.2.4	Concurrent features, React Hooks & Server Actions
Styling	Tailwind CSS v4	High-performance CSS engine with modern `@theme inline`
Motion Physics	Framer Motion v12	Spring dynamics (`stiffness: 450, damping: 30`), `layoutId` shared pills
3D Visualization	Three.js (r174)	Procedural WebGL particle point cloud & orbital rings (`3dviz-pro-max`)
Financial Charts	TradingView Lightweight Charts	Institutional candlestick series & volume profiles
Database & Auth	Supabase PostgreSQL	Real-time subscriptions, Row Level Security, atomic balance locks
State Management	SWR v2.4 + Zustand	Optimistic mutations, background polling, and zero-cache stale views
Type Safety	TypeScript 5 + Zod 4	Strict compile-time typing and runtime validation

🔌 REST API Documentation

Market Feeds & Quotes

GET /api/market/quote?symbol={symbol}&assetType={stock|crypto|forex}

Response:

{
  "symbol": "BTC",
  "price": 7240000.50,
  "change": 3.82,
  "assetType": "crypto",
  "timestamp": 1774000000000
}

Trade Execution

POST /api/trade/execute
Content-Type: application/json

Request Body:

{
  "symbol": "BTC",
  "assetType": "crypto",
  "quantity": 0.5,
  "orderType": "buy",
  "orderClass": "market"
}

Response (200 OK):

{
  "success": true,
  "message": "Order executed successfully at ₹72,40,000.50",
  "fillPrice": 7240000.50,
  "status": "completed"
}

Margin Contracts

POST /api/margin/open
Content-Type: application/json

Request Body:

{
  "symbol": "AAPL",
  "assetType": "stock",
  "quantity": 10,
  "leverage": 5
}

Options Pricing Engine

GET /api/options/price?symbol={symbol}&strike={strike}&expiryDays={days}&type={call|put}

Response:

{
  "price": 142.50,
  "delta": 0.6124,
  "gamma": 0.0142,
  "theta": -3.85,
  "vega": 12.40,
  "impliedMoneyness": "ITM",
  "sigma": 32.5
}

Real-Time Market Tick Stream (Server-Sent Events)

GET /api/market/stream
Accept: text/event-stream

Stream Events:

event: snapshot
data: [{"symbol":"BTC","price":7241250.00,"change":3.82,"direction":"up"},...]

event: tick
data: {"symbol":"AAPL","price":228.45,"change":1.24,"direction":"up","timestamp":1774000000000}

Algorithmic Webhook Order Routing

POST /api/trade/webhook
Content-Type: application/json
x-webhook-secret: {WEBHOOK_SECRET}

Request Body:

{
  "action": "BUY",
  "symbol": "BTC",
  "asset_type": "crypto",
  "quantity": 0.25,
  "strategy": "Dual EMA Dynamic Trend Follower"
}

Response (200 OK):

{
  "success": true,
  "status": "executed",
  "order": {
    "id": "tx_...",
    "action": "BUY",
    "symbol": "BTC",
    "quantity": 0.25,
    "fill_price": 7241250.00,
    "strategy": "Dual EMA Dynamic Trend Follower"
  }
}

⚡ Quickstart & Installation

Prerequisites

Node.js: v20.x or higher
npm, pnpm, or bun
Supabase Account: (Self-hosted or Cloud project)

1. Clone the Repository

git clone https://github.com/chiragchanchal/NullRisk.git
cd NullRisk/tradelab

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env.local file in the tradelab root:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Financial Market Data APIs
FINNHUB_API_KEY=your-finnhub-key
TWELVE_DATA_API_KEY=your-twelve-data-key
EXCHANGE_RATE_API_KEY=your-exchangerate-key

# AI Analyst (Optional)
ANTHROPIC_API_KEY=your-anthropic-key

4. Database Setup & Migrations

Execute the hardened schema and atomic triggers in your Supabase SQL Editor:

Non-negative mock balance constraints (mock_balance >= 0).
Automated profile creation on auth.users insert.
Performance indexes on holdings, transactions, and margin_positions.

5. Run the Local Development Server

npm run dev

Open http://localhost:3000 to access the NullRisk trading terminal.

6. Production Build & Lint Verification

npm run lint    # 0 errors, 0 warnings
npm run build   # Compile all 29 routes with Turbopack
npm run start   # Run production server

🔒 Security & Concurrency Design

Race-Condition Prevention: Balance deductions and position sales execute with atomic Postgres checks (gte('mock_balance', total)).
Deterministic RLS: Strict Row Level Security ensures users can only read and mutate their own portfolio positions.
Double-Spend & Over-Selling Guards: Quantities are validated server-side using cryptographic verification against live market marks.
Symbol Normalization Pipeline: Redundant category pathing is dynamically sanitized to prevent ticker truncation or route injection attacks.

🗺️ Roadmap & Milestones

Phase 1: Core spot simulation engine, Supabase RLS security hardening, and Google OAuth loop resolution.
Phase 2: High-density 21st.dev terminal redesign, dual-axis performance risk gauge, and BSM Options Greeks matrix.
Phase 3: Genjutsu motion design integration, spring layout tabs (layoutId), and tactile feedback micro-interactions.
Phase 4: Interactive topbar telemetry (NSE/NASDAQ pulse modal, notification center) and Three.js 3D Risk Hologram (3dviz-pro-max).
Phase 5: Real-time WebSockets / SSE integration for sub-second tick streaming (/api/market/stream).
Phase 6: Algorithmic webhook order routing API (/api/trade/webhook) and Quantitative Backtesting Playground (/backtest).

📄 License & Attribution

Distributed under the MIT License. See LICENSE for more information.

Developed with precision for high-performance financial engineering. Built by Chirag Chanchal and contributors.

Name		Name	Last commit message	Last commit date
app		app
components		components
lib		lib
public		public
supabase		supabase
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

⚡ NullRisk (TradeLab)

Institutional Multi-Asset Paper Trading Terminal & Risk Engine

📸 Terminal & Portfolio Interface

🌟 Executive Overview & Value Proposition

🚀 Key Features

1. Multi-Asset Market Explorer & Trading Terminal

2. High-Density Portfolio Ledger & Risk Controls

3. Leveraged Margin Contracts & Liquidation Protocol

4. Black-Scholes Options Greeks Terminal

5. Interactive 3D Risk & Liquidity Hologram (3dviz-pro-max)

6. Global Exchange Feed Monitor & Telemetry

7. Notification Center & Competitive Leaderboard

📐 System Architecture

🔬 Black-Scholes Options Greeks Engine

Theoretical Option Values

Greek Sensitivities

🛠️ Technology Stack

🔌 REST API Documentation

Market Feeds & Quotes

Trade Execution

Margin Contracts

Options Pricing Engine

Real-Time Market Tick Stream (Server-Sent Events)

Algorithmic Webhook Order Routing

⚡ Quickstart & Installation

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Database Setup & Migrations

5. Run the Local Development Server

6. Production Build & Lint Verification

🔒 Security & Concurrency Design

🗺️ Roadmap & Milestones

📄 License & Attribution

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

5. Interactive 3D Risk & Liquidity Hologram (`3dviz-pro-max`)