Options Pricing Documentation

Comprehensive guide to using the Options Pricing Dashboard and understanding its features.

Getting Started

The Options Pricing Dashboard allows you to price options using various models and methodologies. This guide will help you navigate the application and understand how to use its features effectively.

Basic Workflow

Select an option style (European)
Choose a pricing model (Black-Scholes or Heston)
Select the underlying asset type
Enter the symbol to fetch market data (optional)
Input or auto-fill option parameters
Choose a solution method
Click "Calculate Option Price" or "Compare Methods"

Interface Overview

Interface screenshot would go here

The dashboard with various input sections and result display

Configuration Area

Contains all the inputs needed to specify your option pricing problem, organized in expandable sections.

Results Area

Displays the calculated option price, Greeks, and performance metrics. Also includes visual payoff diagrams.

Model Overview

The application supports the following pricing models, each with its own characteristics and applicable scenarios:

Model	Key Features	Best For	Limitations
Black-Scholes	Assumes constant volatility Underlying follows Geometric Brownian Motion Provides a closed-form solution Industry standard benchmark	European vanilla options on non-dividend or continuously-dividend paying stocks	Cannot capture volatility smiles or skews; assumes constant interest rates and volatility.
Heston (1993)	Models volatility as a stochastic process Variance follows a mean-reverting process (CIR) Allows correlation between asset and variance Semi-closed form solution via Characteristic Functions	Capturing volatility smiles/skews and term structures; pricing options where volatility dynamics are important.	More complex; requires calibration of 5 parameters; computationally more intensive than Black-Scholes.

For a more detailed mathematical treatment of each model, visit ourMethodology page.

Parameter Guide

Understanding the input parameters is crucial for accurate option pricing. Here's a guide to each parameter and its interpretation:

Common Parameters

Underlying Price (S)
The current market price of the underlying asset. For stocks, this is the current stock price.
Strike Price (K)
The price at which the option holder can buy (call) or sell (put) the underlying asset.
Time to Expiration (T)
The time remaining until the option expires, measured in years. For example, 3 months would be 0.25 years.
Risk-Free Rate (r)
The annualized interest rate for a risk-free investment over the option's lifetime. Often based on treasury yields.
Volatility (σ or Implied Volatility)
For Black-Scholes: A measure of the underlying asset's price variability (annualized standard deviation). For Heston: Used as the initial variance `v0 = σ²` if `v0` is not provided directly. Can be historical or implied from market prices.
Dividend Yield (q or div)
The annualized continuous dividend yield of the underlying asset. Enter 0 if the asset pays no dividends.
Option Type
Call (right to buy) or Put (right to sell) the underlying asset.

Heston Model Parameters

Initial Variance (v0)
The starting value for the variance process at time t=0. Often initialized as the square of the current implied volatility (`σ²`). Must be positive.
Mean Reversion Speed (κ - kappa)
Rate at which the variance `v(t)` reverts towards the long-term mean `θ`. Higher `κ` means faster reversion. Must be positive.
Long-term Variance (θ - theta)
The long-term average level that the variance process tends toward. Must be positive.
Volatility of Volatility (ξ - xi or volvol)
Measures the volatility of the variance process itself. Higher `ξ` means variance changes more rapidly. Must be positive.
Correlation (ρ - rho)
Correlation between the asset's returns (`dW^1_t`) and its variance process (`dW^2_t`). Typically negative for equities (leverage effect). Must be between -1 and 1.

Market Data

The application can fetch real-time market data for options to assist in your analysis. Here's how to use this feature:

Using Market Data

Enter a valid stock symbol (e.g., AAPL, MSFT, GOOGL)
Click "Fetch Market Data"
A table of available options contracts will appear
Click "Auto-Fill" on any contract to use its parameters

Data Sources

Our application connects to market data APIs to fetch current option prices and implied volatilities. This provides a realistic starting point for your analysis or model calibration.

Available Data

Stock price
Option strike prices
Expiration dates
Current premiums
Implied volatilities
Volume information

Limitations

Data may be delayed by 15-20 minutes
Not all assets have options data available
API rate limits may apply
Accuracy dependent on data provider

Solution Methods

Each pricing model offers different solution methods with varying trade-offs between accuracy, speed, and flexibility.

Closed-Form Solution

Analytical formulas providing exact answers (within model assumptions).

✓Extremely fast computation
✓Highly accurate (no numerical errors)
✗Limited to specific models and option types

Monte Carlo Simulation

Simulates thousands of random price paths for the underlying asset and its variance (for Heston) to estimate the option value.

✓Versatile: Works with complex models like Heston.
✓Can handle complex payoff structures
✗Computationally intensive and slower
✗Subject to simulation error

Characteristic Function (Fourier Transform)

Uses the model's characteristic function and numerical integration (often via FFT) to find the option price. Primary method for Heston.

✓Efficient and accurate for models like Heston.
✓Often faster than Monte Carlo for standard options.
✗Requires the characteristic function to be known.
✗Numerical integration needs careful implementation.

API Reference

For developers, the application provides several API endpoints that can be used programmatically.

Option Pricing Endpoint

POST /api/v1/price

Calculate the price of an option given the specified parameters.

// Request
{
  "symbol": "AAPL",          // Optional: For context, not used in calculation
  "model_type": "heston",    // "blackScholes", "heston"
  "solution_type": "fourier",// "closedForm" (BS), "monteCarlo" (Heston), "fourier" (Heston)
  "option_type": "call",     // "call" or "put"
  "underlying_price": 175.0,
  "strike_price": 180.0,
  "yearsToExpiration": 0.25,
  "risk_free_rate": 0.05,
  "volatility": 0.25,        // Required for BS, used for v0 in Heston if v0 absent
  "dividend_yield": 0.01,    // Continuous dividend yield (use 0 if none)

  // --- Heston Specific (Required if model_type="heston") ---
  "kappa": 2.0,              // Mean reversion speed
  "theta": 0.0625,           // Long-term variance (0.25^2)
  "xi": 0.3,                 // Volatility of variance (volvol)
  "rho": -0.7,               // Correlation
  "v0": 0.0625,              // Initial variance (optional, defaults to volatility^2)

  // --- Monte Carlo Specific (Required if solution_type="monteCarlo") ---
  "monte_carlo_simulations": 10000, // Number of paths
  "n_steps": 100             // Number of time steps in simulation
}

// Response (Example for Heston Fourier)
{
  "price": 7.85,
  "methodology": "Heston Characteristic Function (Heston 1993)",
  "calculation_time": 15.3, // milliseconds
  // Greeks might be included depending on calculation method
  "delta": 0.55,
  "gamma": 0.015,
  "theta": -0.04,
  "vega": 0.28, // Note: Vega in Heston is complex, this might be simplified
  "rho": 0.45
  // Monte Carlo response would include "stderr"
}

Market Data Endpoint

GET /api/v1/market-data/{symbol}

Fetch available options contracts for a given symbol.

// Response
[
  {
    "symbol": "AAPL",
    "option_type": "call",
    "strike_price": 180,
    "expiration": "2023-12-15",
    "stock_price": 175.5,
    "market_price": 8.35,
    "implied_volatility": 0.25,
    "volume": 1250
  },
  // More option contracts...
]

Calibration Endpoint

POST /api/v1/calibrate

Calibrate Heston model parameters to market option prices for a specific symbol and expiration date.

// Request
{
  "symbol": "AAPL",            // Ticker symbol
  "expiration": "2023-12-15",  // Expiration date (YYYY-MM-DD)
  "underlying_price": 175.5,   // Current underlying price
  "risk_free_rate": 0.05,      // Annualized risk-free rate
  "dividend_yield": 0.01       // Optional: Annualized dividend yield (default 0)
}

// Response (Success Example)
{
  "success": true,
  "kappa": 1.85,
  "theta": 0.058,
  "volvol": 0.32, // xi (Volatility of Variance)
  "rho": -0.68,
  "var0": 0.061,  // Initial Variance
  "div": 0.01,    // Dividend yield used
  "calibration_metrics": {
    "MSE": 0.00025,
    "RMSE": 0.0158,
    "MAE": 0.0115,
    "max_abs_error": 0.045,
    "mean_rel_error_pct": 3.2,
    "median_rel_error_pct": 2.5,
    "n_options_used": 45,
    "original_n_options": 120,
    "optimizer_iterations": 85,
    "calibration_time_seconds": 25.6
  },
  "market_data_used": [ // Array of market data points used in calibration
    { "strike": 170, "mid_price": 10.5, "maturity": 0.25, ... },
    ...
  ]
}

// Response (Failure Example)
{
  "success": false,
  "error": "No valid market data available for calibration",
  "error_details": "Traceback...", // Optional traceback
  "kappa": 0.0,
  "theta": 0.0,
  "volvol": 0.0,
  "rho": 0.0,
  "var0": 0.0,
  "div": 0.01,
  "calibration_time_seconds": 1.2
}

Troubleshooting

If you encounter issues while using the options pricing dashboard, here are some common problems and their solutions:

Market data not loading: Check that you entered a valid ticker symbol
Verify your internet connection
The symbol may not have options available
API rate limits may have been reached - try again later
Unexpected pricing results: Double-check your input parameters
Ensure volatility is entered as a percentage (e.g., 20 for 20%)
Verify the time to expiration is in years
For near-zero time to expiration, use intrinsic value
Heston calibration fails or gives poor results: Ensure sufficient liquid market data (bid/ask spreads, volume) across various strikes and the specific expiration. Calibration needs rich data.
Market data quality is crucial. Outliers or stale prices can heavily skew results.
The optimizer might get stuck in local minima. The backend tries multiple initial guesses, but complex market conditions can still be challenging.
Check the reported calibration metrics (RMSE, MAE). High errors indicate a poor fit.
Consider if the Heston model is appropriate for the current market regime.
Calibration is time-limited; complex scenarios might require more time than allocated.
Monte Carlo simulation is slow: Reduce the number of simulations for faster results
More simulations increase accuracy but take longer
Consider using closed-form solutions when available
Complex models like Heston take longer to simulate
Parameter constraints: Volatility (`σ`) must be positive.
Time to expiration (`T`) must be positive.
Strike price (`K`) must be positive.
For Heston: `kappa (κ)`, `theta (θ)`, `xi (ξ)`, and `v0` must be positive.
For Heston: `rho (ρ)` must be between -1 and 1 (typically -0.99 to 0 for calibration stability).
The Feller condition (`2κθ < ξ²`) ensures variance stays positive, though it's not strictly enforced in all pricing implementations. Violating it can sometimes lead to instability.

Explore More

Methodology•GitHub Repository

Try the Pricing Dashboard

Contents