Haunt Paper Trading Platform - Implementation Plan

Executive Summary

This document outlines the comprehensive plan for implementing a full-featured paper trading platform within Haunt. The system will support portfolio management, synthetic trade execution, and multi-asset trading across crypto, stocks, ETFs, perpetual futures, options, and forex.

Starting Balance: $5,000,000 USD per portfolio Target: Professional-grade paper trading with realistic execution simulation

Feature Specifications

1. Order Types (Full Suite)

Order Type	Description	Priority
Market Order	Execute immediately at best available price	P1
Limit Order	Execute at specified price or better	P1
Stop Loss	Trigger sell when price drops to threshold	P1
Take Profit	Trigger sell when price reaches profit target	P1
Stop Limit	Stop loss that becomes a limit order when triggered	P1
Trailing Stop	Dynamic stop that follows price by fixed amount or %	P2
OCO (One-Cancels-Other)	Two linked orders; execution of one cancels the other	P2
Fill or Kill (FOK)	Execute entire order immediately or cancel completely	P2
Immediate or Cancel (IOC)	Fill available quantity immediately, cancel remainder	P2
Good Till Cancelled (GTC)	Order remains active until filled or manually cancelled	P1
Good Till Date (GTD)	Order expires at specified date/time	P2
Bracket Order	Entry order + take profit + stop loss as single unit	P2

Implementation Notes:

Orders stored in SQLite with status tracking
Real-time order monitoring via background tasks
Price triggers evaluated against aggregated price feed
Partial fill support for realistic execution

2. Asset Classes

Asset Type	Support Level	Data Sources	Leverage
Crypto Spot	Full	Binance, Coinbase, Kraken, CoinGecko, CMC	Up to 10x margin
Stocks	Full	Alpaca, Finnhub, Yahoo Finance	Up to 4x (Reg-T)
ETFs	Full	Alpaca, Finnhub, Yahoo Finance	Up to 4x
Perpetual Futures	Full	Binance, OKX, Hyperliquid	Up to 100x
Options	Full	Alpaca, Finnhub (chains)	Premium-based
Forex (Majors)	Full	Alpha Vantage, Finnhub, Twelve Data, FCS API	Up to 50x

Forex Pairs (Major):

EUR/USD, GBP/USD, USD/JPY, USD/CHF
AUD/USD, USD/CAD, NZD/USD
Major crosses: EUR/GBP, EUR/JPY, GBP/JPY

3. Position Management

Long & Short Positions

Full support for both directions across all asset types
Short selling simulation with borrow fee calculation
Position flipping (long to short and vice versa)

Leverage & Margin

Asset Type	Max Leverage	Initial Margin	Maintenance Margin
Crypto Perps	100x	1%	0.5%
Crypto Spot	10x	10%	5%
Stocks	4x	25%	25%
ETFs	4x	25%	25%
Forex	50x	2%	1%
Options	N/A (premium)	100% premium	N/A

Margin Modes (Perps)

Isolated Margin: Each position has independent margin
Cross Margin: All positions share account margin
User-selectable per position

Position Features

Partial close support
Dollar-cost averaging (add to position)
Position sizing calculator (risk-based)
Cost basis tracking (FIFO, LIFO, Average Cost - user selectable)

4. Risk Management

Enforced Controls (System-Level)

Maximum leverage limits per asset type
Margin requirements and maintenance levels
Liquidation engine for underwater positions
Insurance fund deductions on liquidation

Advisory Controls (User-Configurable)

Control	Default	Range
Max position size	25% of portfolio	1-100%
Daily loss limit	10% of portfolio	1-50%
Max open positions	20	1-100
Risk per trade	2% of portfolio	0.1-10%
Portfolio stop (drawdown)	25%	5-50%
Correlation warning threshold	0.7	0.5-0.95

Liquidation System (Gradual)

Warning at 80% maintenance margin - alert sent
Warning at 90% maintenance margin - urgent alert
Warning at 95% maintenance margin - final warning
Partial liquidation begins at maintenance breach
ADL (Auto-Deleverage) for counterparty positions if needed
Insurance fund covers shortfalls

5. Execution Simulation (Highly Realistic)

Order Book Integration

Use real-time order book data from top exchanges
Binance, Coinbase, Kraken for crypto
Alpaca, Finnhub for stocks

Slippage Simulation

slippage = base_slippage + (order_size / available_liquidity) * impact_factor

Where:
- base_slippage: 0.01% for liquid assets, 0.05% for illiquid
- available_liquidity: sum of order book depth at price levels
- impact_factor: 0.1 for crypto, 0.05 for stocks

Partial Fills

Large orders fill incrementally based on order book depth
Each fill level has different price (price improvement or slippage)
Fill notifications sent in real-time

Spread Simulation

Use real bid-ask spread from aggregated order book
Market buys execute at ask, sells at bid
Limit orders must cross spread to fill

Latency Modeling

Configurable simulated latency (default: 50-200ms random)
Affects time between order submission and execution
Can be disabled for instant fills

6. Perpetual Futures (Full Derivatives)

Funding Rate System

8-hour funding intervals (00:00, 08:00, 16:00 UTC)
Rate calculated from premium index
Longs pay shorts when positive, shorts pay longs when negative
Historical funding rate tracking

Mark Price

Used for liquidation calculations (not last price)
Calculated from index price + funding basis
Prevents manipulation-based liquidations

Margin Modes

Isolated: Margin isolated per position, max loss = position margin
Cross: Shared margin across all positions, higher capital efficiency

Position Limits

Tier	Position Size	Max Leverage
1	< $50,000	100x
2	< $250,000	50x
3	< $1,000,000	20x
4	< $5,000,000	10x
5	> $5,000,000	5x

ADL (Auto-Deleverage) System

Priority queue based on profit and leverage
Highest profit + highest leverage = first to be deleveraged
Triggered when insurance fund insufficient

Insurance Fund

Virtual fund that absorbs liquidation losses
Replenished by liquidation fees (0.5% of position)
Tracks fund balance over time

7. Options Trading (Full)

Option Types

American Style: Exercise any time before expiration
European Style: Exercise only at expiration
Auto-detection based on underlying asset

Greeks Calculation

Greek	Description	Update Frequency
Delta	Price sensitivity	Real-time
Gamma	Delta sensitivity	Real-time
Theta	Time decay	Hourly
Vega	Volatility sensitivity	Real-time
Rho	Interest rate sensitivity	Daily

Options Features

Options chains with strikes and expirations
Implied volatility calculation
Premium pricing (Black-Scholes for European, Binomial for American)

Multi-Leg Strategies

Spreads: Bull/Bear Call/Put Spread
Straddles and Strangles
Iron Condor, Iron Butterfly
Calendar Spreads
Custom multi-leg combinations

Expiration Handling

Automatic exercise of ITM options at expiration
OTM options expire worthless
Early exercise simulation for American options
Assignment simulation for short options

8. Portfolio Analytics (Comprehensive Suite)

Core Metrics

Metric	Calculation	Update Frequency
Unrealized P&L	(current_price - entry_price) * quantity	Real-time
Realized P&L	Sum of closed position profits/losses	On close
Total P&L	Unrealized + Realized	Real-time
Return %	(current_value - initial_value) / initial_value	Real-time

Time-Based Returns

Daily, Weekly, Monthly, Quarterly, YTD, All-Time
Rolling periods (last 7d, 30d, 90d, 365d)
Comparison to benchmarks (BTC, SPY, etc.)

Risk-Adjusted Metrics

Metric	Formula
Sharpe Ratio	(Return - Risk_Free) / Std_Dev
Sortino Ratio	(Return - Risk_Free) / Downside_Dev
Calmar Ratio	Annual_Return / Max_Drawdown
Information Ratio	(Return - Benchmark) / Tracking_Error

Drawdown Analysis

Current drawdown from peak
Maximum drawdown (all-time)
Drawdown duration (days underwater)
Recovery time from drawdowns

Trade Statistics

Metric	Description
Win Rate	% of profitable trades
Loss Rate	% of losing trades
Avg Win	Average profit on winning trades
Avg Loss	Average loss on losing trades
Risk/Reward	Avg Win / Avg Loss
Profit Factor	Gross Profit / Gross Loss
Expectancy	(Win% * Avg Win) - (Loss% * Avg Loss)

Position Attribution

P&L breakdown by asset
P&L breakdown by asset class
P&L breakdown by strategy/tag
Contribution to portfolio return

Beta & Alpha

Portfolio beta vs benchmark (configurable)
Jensen's Alpha calculation
R-squared (correlation to benchmark)

9. Account Management

Multi-Portfolio Support

Unlimited portfolios per user
Each portfolio has independent:
- Balance and positions
- Risk settings
- Performance history
- Strategy tags/labels

Portfolio Operations

Operation	Description
Create	New portfolio with $5,000,000 starting balance
Reset	Wipe all positions and reset to starting balance
Top-up	Add virtual funds (tracked separately)
Archive	Soft-delete, preserve history
Clone	Copy settings to new portfolio

Portfolio Settings

Name and description
Base currency (USD, EUR, BTC, etc.)
Risk parameters (overrides defaults)
Cost basis method (FIFO, LIFO, Average)
Default leverage per asset type

10. Competition Platform

Competition Types

Type	Duration	Reset
Daily	24 hours	Daily at 00:00 UTC
Weekly	7 days	Monday 00:00 UTC
Monthly	Calendar month	1st of month
Custom	Admin-defined	Custom

Leaderboard Rankings

By Return % - Raw performance
By Sharpe Ratio - Risk-adjusted (featured)
By Profit Factor - Consistency
By Max Drawdown - Risk management

Competition Features

Separate competition portfolios (isolated from main)
Entry requirements (minimum trades, etc.)
Prizes: Leaderboard placement only (no monetary rewards)
Historical competition results

Social Features

Public/private portfolio visibility toggle
Follow traders (get notifications on their trades)
Copy trading (mirror positions automatically)
- Copy trading fees: Copiers pay a configurable fee to the trader they follow
- Default fee: 5% of profits (configurable 0-25% by copied trader)
- Fee only charged on profitable copied trades
Trader profiles with statistics

Achievements & Badges

Badge	Criteria
First Blood	Complete first trade
Centurion	100 trades completed
Sharp Shooter	70%+ win rate (min 50 trades)
Diamond Hands	Hold position 30+ days profitably
Risk Manager	Never exceed 5% daily loss (30 days)
Top 10	Finish in top 10 of competition
Champion	Win a competition

11. Signal Integration & Auto-Trading

Signal-to-Trade Rules

rule:
  name: "RSI Oversold Buy"
  conditions:
    - indicator: RSI
      operator: "<"
      value: 30
    - indicator: MACD
      signal: "bullish_cross"
  action:
    type: "market_buy"
    size: "2% of portfolio"
    stop_loss: "3%"
    take_profit: "6%"
  cooldown: "4h"
  max_positions: 3

Rule Builder Features

Visual rule builder UI
Condition combinations (AND, OR, NOT)
All 13 existing indicators supported
Price-based conditions
Time-based conditions (market hours, etc.)
Position-aware rules (only if no existing position)

Strategy Templates

Pre-built strategies users can clone
Community-shared strategies
Backtested performance shown

Backtesting Engine

Test strategies against historical data
Use existing chart store (up to 90 days)
Fetch additional historical data on-demand
Cache fetched data for reuse

Backtest Reports

Equity curve visualization
Trade-by-trade breakdown
Performance metrics (same as live)
Comparison to buy-and-hold
Monte Carlo simulation for robustness

12. Trade History & Reporting

Order History

Complete audit trail of all orders
Status tracking: Pending → Filled/Cancelled/Expired
Partial fill tracking
Order modification history

Position History

Entry and exit details
P&L per position
Holding duration
Tags and notes

Export Formats

CSV (Excel-compatible)
JSON (programmatic access)
PDF reports (formatted summaries)

Tax Reporting

Realized gains/losses by tax year
Cost basis method applied (FIFO/LIFO/Average)
Short-term vs long-term classification
Export for tax software (TurboTax, etc.)

Trade Journal

Add notes to any trade
Tag trades with strategies
Screenshot attachment support
Searchable and filterable

Retention Policy

Unlimited retention for all history
Archived portfolios preserved
Compliance-ready audit trail

13. Alerts & Notifications

Alert Types

Alert	Trigger	Channels
Order Filled	Order execution	WebSocket, Webhook
Order Cancelled	Order cancelled/expired	WebSocket, Webhook
Stop Loss Hit	Stop loss triggered	WebSocket, Webhook
Take Profit Hit	Take profit triggered	WebSocket, Webhook
Margin Warning	80%/90%/95% maintenance	WebSocket, Webhook
Liquidation	Position liquidated	WebSocket, Webhook
Price Alert	Price crosses threshold	WebSocket, Webhook
Signal Alert	Trading signal fired	WebSocket, Webhook
Portfolio Alert	Drawdown threshold	WebSocket, Webhook
Competition	Rank change, competition end	WebSocket, Webhook

Notification Channels

WebSocket: Real-time in-app (existing infrastructure)
Webhooks: HTTP POST to user-configured URLs
Future: Email, Push notifications (mobile)

Integration with Existing Signals

Extend current WebSocket SignalUpdate messages
Add portfolio context to signal alerts
Trigger auto-trade rules from signal alerts

14. API & Integration

REST API Endpoints

Portfolio Management

GET    /api/portfolio                    # List user portfolios
POST   /api/portfolio                    # Create portfolio
GET    /api/portfolio/:id                # Get portfolio details
PUT    /api/portfolio/:id                # Update portfolio settings
DELETE /api/portfolio/:id                # Archive portfolio
POST   /api/portfolio/:id/reset          # Reset portfolio
POST   /api/portfolio/:id/topup          # Add virtual funds

Orders

GET    /api/orders                       # List orders (filterable)
POST   /api/orders                       # Place order
GET    /api/orders/:id                   # Get order details
PUT    /api/orders/:id                   # Modify order
DELETE /api/orders/:id                   # Cancel order

Positions

GET    /api/positions                    # List open positions
GET    /api/positions/:id                # Get position details
PUT    /api/positions/:id                # Modify position (SL/TP)
DELETE /api/positions/:id                # Close position
POST   /api/positions/:id/close-partial  # Partial close

Analytics

GET    /api/analytics/performance        # Portfolio performance
GET    /api/analytics/metrics            # Risk metrics
GET    /api/analytics/attribution        # P&L attribution
GET    /api/analytics/trades             # Trade statistics

History

GET    /api/history/orders               # Order history
GET    /api/history/positions            # Closed positions
GET    /api/history/trades               # Trade log
GET    /api/history/export               # Export data

Strategies

GET    /api/strategies                   # List strategies
POST   /api/strategies                   # Create strategy
GET    /api/strategies/:id               # Get strategy
PUT    /api/strategies/:id               # Update strategy
DELETE /api/strategies/:id               # Delete strategy
POST   /api/strategies/:id/backtest      # Run backtest
POST   /api/strategies/:id/activate      # Activate auto-trading

Competitions

GET    /api/competitions                 # List competitions
GET    /api/competitions/:id             # Competition details
POST   /api/competitions/:id/join        # Join competition
GET    /api/competitions/:id/leaderboard # Get leaderboard

WebSocket Events

Outbound (Server → Client)

OrderUpdate        # Order status change
PositionUpdate     # Position P&L update
PortfolioUpdate    # Portfolio balance/metrics
MarginUpdate       # Margin level changes
LiquidationWarning # Approaching liquidation
TradeExecution     # Trade filled
CompetitionUpdate  # Rank/score changes

Inbound (Client → Server)

SubscribePortfolio   # Subscribe to portfolio updates
UnsubscribePortfolio # Unsubscribe
SubscribePositions   # Subscribe to position updates
SubscribeOrders      # Subscribe to order updates

Webhooks

User-configurable webhook URLs
Event filtering (select which events)
Retry logic with exponential backoff
Webhook signature verification (HMAC)

Technical Architecture

Data Models

Portfolio

struct Portfolio {
    id: Uuid,
    user_id: Uuid,
    name: String,
    description: Option<String>,
    base_currency: String,           // USD, EUR, BTC
    starting_balance: Decimal,       // 5,000,000
    current_balance: Decimal,
    margin_used: Decimal,
    margin_available: Decimal,
    unrealized_pnl: Decimal,
    realized_pnl: Decimal,
    cost_basis_method: CostBasisMethod,
    risk_settings: RiskSettings,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    is_competition: bool,
    competition_id: Option<Uuid>,
}

Order

struct Order {
    id: Uuid,
    portfolio_id: Uuid,
    symbol: String,
    asset_type: AssetType,
    side: OrderSide,                 // Buy, Sell
    order_type: OrderType,
    quantity: Decimal,
    filled_quantity: Decimal,
    price: Option<Decimal>,          // For limit orders
    stop_price: Option<Decimal>,     // For stop orders
    trail_amount: Option<Decimal>,   // For trailing stops
    trail_percent: Option<Decimal>,
    time_in_force: TimeInForce,
    status: OrderStatus,
    linked_order_id: Option<Uuid>,   // For OCO
    bracket_id: Option<Uuid>,        // For bracket orders
    fills: Vec<Fill>,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    expires_at: Option<DateTime<Utc>>,
}

Position

struct Position {
    id: Uuid,
    portfolio_id: Uuid,
    symbol: String,
    asset_type: AssetType,
    side: PositionSide,              // Long, Short
    quantity: Decimal,
    entry_price: Decimal,
    current_price: Decimal,
    unrealized_pnl: Decimal,
    realized_pnl: Decimal,
    margin_used: Decimal,
    leverage: Decimal,
    margin_mode: MarginMode,         // Isolated, Cross
    liquidation_price: Option<Decimal>,
    stop_loss: Option<Decimal>,
    take_profit: Option<Decimal>,
    cost_basis: Vec<CostBasisEntry>,
    funding_payments: Decimal,       // For perps
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
}

Trade

struct Trade {
    id: Uuid,
    order_id: Uuid,
    portfolio_id: Uuid,
    symbol: String,
    side: OrderSide,
    quantity: Decimal,
    price: Decimal,
    fee: Decimal,
    slippage: Decimal,
    executed_at: DateTime<Utc>,
}

Storage Architecture

SQLite (Persistent)

Portfolios
Orders (all)
Positions (open and closed)
Trades
Strategies
Competition results
User achievements
Tax records

Redis (Hot Data)

Open orders (for fast matching)
Real-time P&L calculations
Margin levels
Position summaries
Leaderboard rankings
Session data

In-Memory (DashMap)

Active price triggers
Order book cache
WebSocket subscriptions
Rate limiting

Implementation Phases

Phase 1: Core Foundation (Weeks 1-4)

Deliverables:

Portfolio data models and storage
Basic order types (Market, Limit, Stop Loss, Take Profit)
Spot trading (Crypto, Stocks, ETFs)
Position tracking and P&L calculation
Basic REST API endpoints
WebSocket position/order updates

Database Schema:

portfolios table
orders table
positions table
trades table

API Endpoints:

Portfolio CRUD
Order placement and management
Position queries

Testing:

Unit tests for order matching
Integration tests for order flow
API endpoint tests

Phase 2: Advanced Orders & Perps (Weeks 5-8)

Deliverables:

Advanced order types (Trailing Stop, OCO, FOK, IOC, GTD, Bracket)
Perpetual futures support
Leverage and margin system
Liquidation engine
Funding rate calculation
Cross/Isolated margin modes

New Tables:

funding_payments
liquidations
margin_history

New Services:

MarginService
LiquidationEngine
FundingRateService

Testing:

Margin calculation tests
Liquidation scenario tests
Funding rate tests

Phase 3: Options & Auto-Trading (Weeks 9-12)

Deliverables:

Options trading support
Greeks calculation
Options chains integration
Multi-leg strategies
Signal-to-trade rule engine
Strategy builder
Backtesting engine

New Tables:

options_positions
strategies
strategy_rules
backtest_results

New Services:

OptionsService
GreeksCalculator
StrategyEngine
BacktestRunner

Testing:

Options pricing tests
Greeks accuracy tests
Strategy execution tests
Backtest validation

Phase 4: Social & Analytics (Weeks 13-16)

Deliverables:

Competition platform
Leaderboards
Social features (follow, copy trading)
Achievements system
Comprehensive analytics
Tax reporting
Forex support

New Tables:

competitions
competition_entries
achievements
user_follows
copy_trades

New Services:

CompetitionService
LeaderboardService
CopyTradingService
AnalyticsService
TaxReportService

Testing:

Competition logic tests
Leaderboard ranking tests
Copy trading tests
Analytics accuracy tests

API Documentation Requirements

Each endpoint must include:

Description: What the endpoint does
Authentication: Required auth level
Request: Parameters, body schema
Response: Success and error responses
Examples: curl examples and response samples
Rate Limits: Applicable limits

Documentation format: OpenAPI 3.0 specification Documentation hosting: Extend existing /docs with Docsify

Testing Strategy

Unit Tests

Order matching logic
P&L calculations
Margin calculations
Greeks calculations
Risk limit enforcement

Integration Tests

Full order lifecycle
Position management
Liquidation scenarios
Funding payments
Competition scoring

End-to-End Tests

User signup → portfolio creation → trading → analytics
Competition participation flow
Auto-trading activation

Performance Tests

Order throughput (target: 1000 orders/second)
WebSocket update latency (target: <100ms)
Backtest execution time

Success Metrics

Metric	Target
Order execution latency	< 100ms
P&L calculation accuracy	99.99%
System uptime	99.9%
API response time (p95)	< 200ms
WebSocket message latency	< 50ms

Dependencies

Existing (Leverage)

Authentication system
Price aggregation pipeline
Order book data
Trading signals (13 indicators)
WebSocket infrastructure
SQLite + Redis storage

New Requirements

Options data source (Alpaca options API)
Historical data for backtesting (extend CryptoCompare, Alpha Vantage)

Forex Data Sources (Multi-Provider, Free-First)

Provider	Free Tier	Priority	Notes
Alpha Vantage	25 req/day	Primary	Already integrated, extend for forex
Finnhub	60 req/min	Primary	Already integrated, good forex coverage
Twelve Data	800 req/day	Secondary	WebSocket support, 140+ currencies
FCS API	500 req/day	Tertiary	2000+ forex pairs, real-time
Fixer.io	100 req/mo	Fallback	170 currencies, rate-only fallback

Implementation Strategy:

Extend existing Alpha Vantage source (src/sources/alphavantage.rs) for forex pairs
Extend existing Finnhub source (src/sources/finnhub.rs) for forex data
Add new Twelve Data source for WebSocket streaming and higher limits
Add FCS API as additional fallback
Use same multi-source aggregation pattern as crypto/stocks

Risk Assessment

Risk	Likelihood	Impact	Mitigation
Complex margin calculation bugs	Medium	High	Extensive unit tests, shadow mode testing
Performance issues at scale	Medium	Medium	Load testing, Redis caching, query optimization
Data source reliability	Low	High	Multiple fallback sources, circuit breakers
Options pricing accuracy	Medium	Medium	Validate against real exchange prices

Resolved Decisions

Question	Decision
Forex data source	Multi-provider: Alpha Vantage + Finnhub (existing) + Twelve Data + FCS API (free-first)
Competition prizes	Leaderboard placement only - no monetary rewards
Copy trading fees	5% of profits default (configurable 0-25%), only on profitable trades
Options data	Alpaca options API for proof of concept, evaluate expansion later
Frontend/Mobile	Out of scope - backend API only

Open Questions

None - all major decisions resolved. Ready for implementation.

Appendix

A. Order Type Specifications

Market Order

Executes immediately at best available price
Uses order book for price discovery
Slippage applied based on order size vs liquidity

Limit Order

Placed in virtual order book
Fills when market price crosses limit
May partially fill

Stop Loss

Triggers when last price ≤ stop price (for longs)
Becomes market order when triggered
Slippage applied on execution

Take Profit

Triggers when last price ≥ target price (for longs)
Becomes market order when triggered

Stop Limit

Triggers when last price crosses stop price
Becomes limit order (not market) when triggered
May not fill if price moves past limit

Trailing Stop

Stop price trails market by fixed amount or %
Only moves in favorable direction
Triggers like normal stop when hit

OCO (One-Cancels-Other)

Two orders linked together
When one fills or triggers, other is cancelled
Common: Stop Loss + Take Profit

Fill or Kill

Must fill entire quantity immediately
If not possible, entire order cancelled
No partial fills

Immediate or Cancel

Fill whatever quantity available immediately
Cancel any unfilled remainder
Partial fills allowed

Bracket Order

Entry order + Stop Loss + Take Profit as package
SL and TP activate when entry fills
SL and TP are OCO linked

B. Margin Calculation Formulas

Initial Margin = Position Size / Leverage
Maintenance Margin = Position Size * Maintenance Rate

Margin Level = (Equity / Used Margin) * 100%
Equity = Balance + Unrealized P&L

Liquidation Price (Long) = Entry Price * (1 - Initial Margin + Maintenance Margin)
Liquidation Price (Short) = Entry Price * (1 + Initial Margin - Maintenance Margin)

C. Greeks Formulas (Black-Scholes)

Delta (Call) = N(d1)
Delta (Put) = N(d1) - 1

Gamma = N'(d1) / (S * σ * √T)

Theta (Call) = -(S * N'(d1) * σ) / (2√T) - r * K * e^(-rT) * N(d2)
Theta (Put) = -(S * N'(d1) * σ) / (2√T) + r * K * e^(-rT) * N(-d2)

Vega = S * √T * N'(d1)

Where:
d1 = (ln(S/K) + (r + σ²/2)T) / (σ√T)
d2 = d1 - σ√T
N(x) = Standard normal CDF
N'(x) = Standard normal PDF
S = Spot price
K = Strike price
T = Time to expiration
r = Risk-free rate
σ = Volatility

Implementation Progress Checklist

Phase 1: Core Foundation

Data Models (`src/types/trading.rs`)

Database Schema (`src/services/sqlite_store.rs`)

Trading Service (`src/services/trading.rs`)

REST API (`src/api/trading.rs`)

WebSocket Updates (`src/types/ws.rs`, `src/websocket/`)

Integration

AppState includes TradingService
TradingService integrated with RoomManager
API router includes trading routes
All tests passing (648 total)

Phase 2: Advanced Orders & Perps

Advanced Order Types (`src/services/trading.rs`)

Trailing Stop execution logic (update_trailing_stops)
OCO (One-Cancels-Other) linked orders (cancel_linked_order, place_oco_order)
Fill or Kill (FOK) validation (validate_fok_order)
Immediate or Cancel (IOC) partial fills (execute_ioc_order)
Good Till Date (GTD) expiration (expire_gtd_orders)
Bracket Order (Entry + SL + TP package) (place_bracket_order, activate_bracket_orders)
Order modification API

Perpetual Futures Types (`src/types/trading.rs`)

FundingRate struct with payment calculation
FundingPayment struct for tracking payments
LeverageTier struct with position-based limits
Position perp methods (apply_funding, leverage_tier, margin_level, warning_level)
Position leverage validation (validate_leverage)
Mark price support in Position
Isolated/Cross margin mode enum
funding_payments table (src/services/sqlite_store.rs)

Liquidation Engine Types (`src/types/trading.rs`)

LiquidationWarningLevel enum (80%, 90%, 95%, liquidation)
Liquidation struct with loss/fee tracking
MarginHistory struct for audit trail
MarginChangeType enum
InsuranceFund struct with contribution/payout tracking
AdlEntry struct with score calculation
liquidations table (src/services/sqlite_store.rs)
margin_history table (src/services/sqlite_store.rs)
insurance_fund table (src/services/sqlite_store.rs)

Services (`src/services/`)

Phase 3: Options & Auto-Trading

Options Trading Types (`src/types/trading.rs`)

OptionType enum (Call, Put)
OptionStyle enum (American, European)
Greeks struct (delta, gamma, theta, vega, rho)
OptionContract struct with pricing fields
OptionsChain struct for chain data
OptionPosition struct with Greeks tracking
OptionStrategyType enum (single, spreads, condors, etc.)
OptionStrategy struct for multi-leg strategies
Contract symbol generation

Options Service (`src/services/options.rs`)

Black-Scholes pricing for European options
Binomial tree pricing for American options
Greeks calculation (Delta, Gamma, Theta, Vega, Rho)
Implied volatility calculation (Newton-Raphson with bisection fallback)
Cumulative normal distribution functions
Position update with real-time Greeks

Options Database (`src/services/sqlite_store.rs`)

options_positions table with full schema
CRUD operations for option positions
Query by underlying symbol
Query expiring positions
Greeks JSON serialization
Unit tests for options position CRUD (4 tests)

Options Integration (Remaining)

Auto-Trading Types (`src/types/trading.rs`)

Auto-Trading Database (`src/services/sqlite_store.rs`)

strategies table with rules JSON storage
CRUD operations for strategies
Query active strategies
Soft delete support
Unit tests for strategy CRUD (2 tests)

Auto-Trading Service (Completed)

StrategyEngine service for evaluating rules (src/services/strategy_engine.rs)
- IndicatorSnapshot for tracking all 13 indicators
- Cross detection (CrossesAbove/CrossesBelow) with previous value comparison
- Rule condition evaluation with AND/OR operators
- Signal-to-order conversion
- Position count tracking per portfolio/symbol
- Unit tests for condition evaluation (11 tests)
Signal-to-trade execution (signal_to_order_request method)
Real-time indicator value integration (IndicatorSnapshot)

Backtesting (Completed)

BacktestRunner service (src/services/backtester.rs)
- Historical price simulation with configurable intervals
- Commission and slippage simulation
- Position sizing (FixedAmount, PortfolioPercent, RiskPercent, FixedUnits)
- Unit tests (10 tests)
Historical data fetching (get_chart_data, synthetic data generation)
Equity curve generation (EquityPoint with sampling)
Trade-by-trade breakdown (BacktestTrade with excursion tracking)
Comparison to buy-and-hold (BuyAndHoldComparison)
Monte Carlo simulation (shuffled trade sequences, percentile analysis)
backtest_results table in SQLite

Backtest Types (`src/types/trading.rs`)

BacktestStatus enum (Pending, Running, Completed, Failed, Cancelled)
BacktestConfig with all configuration options
BacktestTrade for individual trade records
EquityPoint for equity curve
BacktestMetrics (30+ performance metrics)
BuyAndHoldComparison
MonteCarloResults
BacktestResult comprehensive result struct

Services (Status)

OptionsService (src/services/options.rs)
GreeksCalculator (Black-Scholes, binomial)
StrategyEngine (src/services/strategy_engine.rs)
BacktestRunner (src/services/backtester.rs)

Phase 4: Social & Analytics

Competition Platform

Social Features

Achievements

Achievement definitions
Badge awarding logic
Achievement display
achievements table

Analytics

Comprehensive AnalyticsService
Time-based returns (daily, weekly, monthly, etc.)
Risk-adjusted metrics (Sharpe, Sortino, Calmar)
Drawdown analysis
Trade statistics (win rate, profit factor, etc.)
Position attribution
Beta & Alpha calculation

Forex Support

Tax Reporting

Export & Reporting

Testing Status

Test Suite	Tests	Status
Trading Types	78	✅ Passing
SQLite Trading	15	✅ Passing
Trading Service	9	✅ Passing
WebSocket Trading	12	✅ Passing
API Trading	2	✅ Passing
Liquidation Engine	3	✅ Passing
Options Service	6	✅ Passing
Options Position DB	4	✅ Passing
Strategy Types	12	✅ Passing
Strategy DB	2	✅ Passing
Total Binary Tests	705	✅ All Passing
Total Library Tests	262	✅ All Passing

Build Status

✅ Build successful with only expected unused code warnings
✅ No compilation errors
✅ All tests passing (967 total)

Last Updated: 2026-02-03