Skip to main content

​
Overview

The Calculations endpoint is the core engine of OptionStrat AI. It generates 2D profit/loss heatmaps by simulating your options strategy across different underlying prices and time horizons using Black-Scholes modeling.

​
Generate Heatmap

curl -X POST http://localhost:8000/api/calculations/heatmap \
  -H "Content-Type: application/json" \
  -d '{
    "underlying_price": 175.43,
    "volatility_shock": 0.0,
    "days_to_simulate": 30,
    "ticker": "AAPL",
    "legs": [
      {
        "type": "call",
        "action": "sell",
        "strike": 180.0,
        "expiration": "2024-12-20",
        "qty": 1,
        "premium": 3.50
      },
      {
        "type": "call",
        "action": "buy",
        "strike": 185.0,
        "expiration": "2024-12-20",
        "qty": 1,
        "premium": 1.75
      }
    ]
  }'

​
Request Body (StrategyState)

​
underlying_price
float
required
Current or simulated price of the underlying asset. Must be greater than 0.
​
volatility_shock
float
Volatility shock to simulate (e.g., 0.05 for +5% IV increase, -0.10 for -10% IV decrease)
​
days_to_simulate
integer
default:30
Number of days forward to simulate in the heatmap. Range: 1-365.
​
ticker
string
Stock ticker symbol (e.g., “AAPL”). Optional but recommended for context.
​
legs
array
required
Array of option legs (positions). Minimum 1 leg required.
​
market_context
object
Optional pre-fetched market data and sentiment information

​
Response

​
status
string
Status of the calculation: "success" or "error"
​
max_profit
float
Maximum potential profit across all simulated scenarios
​
max_loss
float
Maximum potential loss across all simulated scenarios
​
heatmap_grid
array
2D grid containing P&L calculations for different price/time combinations. Each element contains:
  • Price point
  • Time point (days forward)
  • P&L value at that coordinate

​
Example Response

{
  "status": "success",
  "max_profit": 175.00,
  "max_loss": -325.00,
  "heatmap_grid": [
    {
      "price": 170.0,
      "day": 0,
      "pnl": 175.00
    },
    {
      "price": 170.0,
      "day": 15,
      "pnl": 150.25
    },
    {
      "price": 175.0,
      "day": 0,
      "pnl": 175.00
    },
    {
      "price": 180.0,
      "day": 0,
      "pnl": 175.00
    },
    {
      "price": 185.0,
      "day": 15,
      "pnl": -250.00
    },
    {
      "price": 190.0,
      "day": 30,
      "pnl": -325.00
    }
  ]
}

​
Error Response

{
  "status": "error",
  "heatmap_grid": []
}

​
Strategy Examples

{
  "underlying_price": 175.43,
  "days_to_simulate": 30,
  "legs": [
    {
      "type": "call",
      "action": "buy",
      "strike": 175.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 5.00
    },
    {
      "type": "call",
      "action": "sell",
      "strike": 180.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 3.00
    }
  ]
}

{
  "underlying_price": 175.43,
  "days_to_simulate": 45,
  "legs": [
    {
      "type": "put",
      "action": "buy",
      "strike": 165.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 1.00
    },
    {
      "type": "put",
      "action": "sell",
      "strike": 170.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 2.50
    },
    {
      "type": "call",
      "action": "sell",
      "strike": 180.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 2.50
    },
    {
      "type": "call",
      "action": "buy",
      "strike": 185.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 1.00
    }
  ]
}

{
  "underlying_price": 175.43,
  "days_to_simulate": 30,
  "legs": [
    {
      "type": "stock",
      "action": "buy",
      "strike": 175.43,
      "expiration": "2099-12-31",
      "qty": 1,
      "premium": 175.43
    },
    {
      "type": "call",
      "action": "sell",
      "strike": 180.0,
      "expiration": "2024-12-20",
      "qty": 1,
      "premium": 3.50
    }
  ]
}

​
Implementation Details

Calculation Engine: The heatmap uses Black-Scholes-Merton model to price options at different:
  • Price points: Creates a grid of underlying prices (typically ±20% from current price)
  • Time points: Simulates P&L from today through days_to_simulate
  • Volatility: Applies volatility_shock to implied volatility
Performance: Complex strategies with many legs may take longer to calculate. The endpoint typically responds in 1-3 seconds for standard strategies.

​
Use Cases

  • Visual Strategy Analysis: Generate data for P&L heatmap visualizations
  • Risk Assessment: Identify max profit and max loss scenarios
  • What-If Analysis: Test different volatility scenarios with volatility_shock
  • Time Decay Modeling: See how strategy P&L evolves over time
  • Price Target Planning: Visualize profit zones across price ranges

Build docs developers (and LLMs) love

Get started for freeTalk to us