Vespera API Documentation

Welcome to the Vespera API documentation. Our REST API provides programmatic access to options data, analytics, and historical backtesting capabilities. This guide will help you get started with integrating Vespera's powerful quantitative options data into your trading applications and systems.

Current Version: v1 Base URL: https://api.vespera.com/v1

Quick Start

  1. Sign up for a Vespera account and obtain your API key
  2. Authenticate API requests using your API key in the request header
  3. Start making requests to the endpoints

Core Concepts

The Vespera API follows RESTful principles and returns data in JSON format. All API requests must be made over HTTPS.

Our API is designed to be intuitive for quants, algo traders, and developers building options-focused applications.

Authentication

The Vespera API uses API keys for authentication. Your API key should be included in all requests as a bearer token in the Authorization header.

HTTP Request Header 
Authorization: Bearer YOUR_API_KEY

Security Notice

Your API key grants access to your account and should be kept secure. Do not share your API key in publicly accessible areas or client-side code. All API requests should be made server-side.

API Endpoints

The Vespera API provides several endpoints for accessing different types of options data and analytics. Below are the core endpoints available in our API.

Options Data

GET /options

Retrieve current options chain data for a specified symbol.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol (e.g., SPY, AAPL)
expiration string No Expiration date in YYYY-MM-DD format
strike_min number No Minimum strike price to include
strike_max number No Maximum strike price to include
option_type string No Type of options to return: 'call', 'put', or 'both' (default)
moneyness string No Filter by moneyness: 'itm', 'otm', 'atm', or 'all' (default)
greeks boolean No Include option greeks in response (default: true)
format string No Response format: 'json' (default) or 'csv'
Example Request 
curl -X GET "https://api.vespera.com/v1/options?symbol=SPY&expiration=2025-06-20&strike_min=450&strike_max=500&option_type=call&greeks=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "underlying_price": 478.56,
  "timestamp": "2025-05-22T15:30:00Z",
  "expiration": "2025-06-20",
  "days_to_expiration": 29,
  "calls": [
    {
      "contract_symbol": "SPY250620C00450000",
      "strike": 450,
      "last": 42.15,
      "bid": 42.05,
      "ask": 42.25,
      "volume": 532,
      "open_interest": 8543,
      "implied_volatility": 0.21,
      "delta": 0.68,
      "gamma": 0.015,
      "theta": -0.032,
      "vega": 0.97,
      "rho": 0.058,
      "time_value": 13.59,
      "intrinsic_value": 28.56,
      "change": 0.87,
      "change_percent": 2.11,
      "mid": 42.15,
      "mark": 42.15,
      "itm": true
    },
    {
      "contract_symbol": "SPY250620C00455000",
      "strike": 455,
      "last": 38.75,
      "bid": 38.60,
      "ask": 38.90,
      "volume": 421,
      "open_interest": 6821,
      "implied_volatility": 0.22,
      "delta": 0.65,
      "gamma": 0.016,
      "theta": -0.034,
      "vega": 0.96,
      "rho": 0.055,
      "time_value": 14.19,
      "intrinsic_value": 23.56,
      "change": 0.65,
      "change_percent": 1.70,
      "mid": 38.75,
      "mark": 38.75,
      "itm": true
    }
  ]
}
GET /options/expirations

Retrieve available expiration dates for a specified symbol.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol (e.g., SPY, AAPL)
include_weeklys boolean No Include weekly expirations (default: true)
include_monthlys boolean No Include monthly expirations (default: true)
range string No Time range: 'short_term', 'medium_term', 'long_term', or 'all' (default)
Example Request 
curl -X GET "https://api.vespera.com/v1/options/expirations?symbol=SPY&include_weeklys=true&range=short_term" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "expirations": [
    {
      "date": "2025-05-23",
      "days_to_expiration": 1,
      "type": "weekly",
      "option_count": 648
    },
    {
      "date": "2025-05-30",
      "days_to_expiration": 8,
      "type": "weekly",
      "option_count": 725
    },
    {
      "date": "2025-06-06",
      "days_to_expiration": 15,
      "type": "weekly",
      "option_count": 689
    },
    {
      "date": "2025-06-20",
      "days_to_expiration": 29,
      "type": "monthly",
      "option_count": 896
    }
  ]
}
GET /options/strikes

Retrieve available strike prices for a specified symbol and expiration date.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol (e.g., SPY, AAPL)
expiration string Yes Expiration date in YYYY-MM-DD format
moneyness string No Filter by moneyness: 'itm', 'otm', 'atm', or 'all' (default)
Example Request 
curl -X GET "https://api.vespera.com/v1/options/strikes?symbol=SPY&expiration=2025-06-20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "expiration": "2025-06-20",
  "underlying_price": 478.56,
  "strike_increment": 5,
  "strikes": [
    400,
    405,
    410,
    415,
    420,
    425,
    430,
    435,
    440,
    445,
    450,
    455,
    460,
    465,
    470,
    475,
    480,
    485,
    490,
    495,
    500,
    505,
    510,
    515,
    520,
    525,
    530,
    535,
    540,
    545,
    550
  ],
  "atm_strike": 480
}

Historical Data

GET /historical/options

Retrieve historical options data for backtesting and analysis.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
contract_symbol string No Specific option contract symbol (e.g., SPY250620C00450000)
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
expiration string No Expiration date in YYYY-MM-DD format
strike number No Strike price for filtering
option_type string No Type of options to return: 'call', 'put', or 'both' (default)
moneyness string No Filter by moneyness: 'itm', 'otm', 'atm', or 'all' (default)
interval string No Data interval: 'daily' (default), 'hourly', or 'minute'
greeks boolean No Include calculated historical greeks (default: true)
format string No Response format: 'json' (default) or 'csv'

Note: Historical data access varies by subscription plan. Professional and Institutional plans include extended history.

Example Request 
curl -X GET "https://api.vespera.com/v1/historical/options?symbol=SPY&start_date=2025-01-01&end_date=2025-05-01&expiration=2025-06-20&strike=450&option_type=call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "contract_symbol": "SPY250620C00450000",
  "contract_details": {
    "strike": 450,
    "expiration": "2025-06-20",
    "option_type": "call"
  },
  "data": [
    {
      "date": "2025-01-02",
      "open": 35.21,
      "high": 36.45,
      "low": 34.87,
      "close": 36.12,
      "volume": 3421,
      "open_interest": 5873,
      "underlying_price": 458.92,
      "implied_volatility": 0.23,
      "delta": 0.59,
      "gamma": 0.019,
      "theta": -0.024,
      "vega": 1.24,
      "rho": 0.067
    },
    {
      "date": "2025-01-03",
      "open": 36.34,
      "high": 37.50,
      "low": 36.10,
      "close": 37.28,
      "volume": 2954,
      "open_interest": 6102,
      "underlying_price": 461.73,
      "implied_volatility": 0.22,
      "delta": 0.61,
      "gamma": 0.018,
      "theta": -0.025,
      "vega": 1.22,
      "rho": 0.069
    },
    // Additional historical data points...
  ]
}
GET /historical/volatility

Retrieve historical implied volatility data for an underlying symbol.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
term integer No Days to expiration (e.g., 30, 60, 90)
moneyness string No Filter by moneyness: 'itm', 'otm', 'atm' (default)
calculation string No Calculation method: 'vwap' (default), 'close', 'average'
include_iv_rank boolean No Include IV rank and percentile (default: true)
Example Request 
curl -X GET "https://api.vespera.com/v1/historical/volatility?symbol=SPY&start_date=2024-01-01&end_date=2025-05-01&term=30&moneyness=atm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "term": 30,
  "moneyness": "atm",
  "calculation": "vwap",
  "current_iv": 0.18,
  "iv_rank": 42.5,
  "iv_percentile": 38.7,
  "historical_iv": [
    {
      "date": "2024-01-02",
      "iv": 0.19,
      "underlying_price": 432.57,
      "hv_20": 0.14,
      "iv_skew": 1.2
    },
    {
      "date": "2024-01-03",
      "iv": 0.18,
      "underlying_price": 434.89,
      "hv_20": 0.14,
      "iv_skew": 1.3
    },
    // Additional historical data points...
  ],
  "statistics": {
    "max_iv": 0.32,
    "min_iv": 0.12,
    "mean_iv": 0.19,
    "median_iv": 0.18,
    "std_dev": 0.04
  }
}
GET /historical/underlying

Retrieve historical price data for an underlying symbol.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
interval string No Data interval: 'daily' (default), 'weekly', 'monthly'
adjusted boolean No Provide dividend-adjusted prices (default: true)
Example Request 
curl -X GET "https://api.vespera.com/v1/historical/underlying?symbol=SPY&start_date=2025-01-01&end_date=2025-05-01&interval=daily" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "interval": "daily",
  "adjusted": true,
  "data": [
    {
      "date": "2025-01-02",
      "open": 458.92,
      "high": 460.34,
      "low": 457.89,
      "close": 459.76,
      "volume": 78543268,
      "change": 1.25,
      "change_percent": 0.27
    },
    {
      "date": "2025-01-03",
      "open": 461.73,
      "high": 463.28,
      "low": 460.15,
      "close": 462.51,
      "volume": 65328745,
      "change": 2.75,
      "change_percent": 0.60
    },
    // Additional historical data points...
  ]
}

Market Data

GET /market/quotes

Retrieve real-time market quotes for a list of symbols.

Parameters

Parameter Type Required Description
symbols string Yes Comma-separated list of symbols (e.g., SPY,AAPL,MSFT)
include_extended boolean No Include extended hours data (default: false)
Example Request 
curl -X GET "https://api.vespera.com/v1/market/quotes?symbols=SPY,AAPL,MSFT" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "quotes": [
    {
      "symbol": "SPY",
      "price": 478.56,
      "change": 2.35,
      "change_percent": 0.49,
      "volume": 28654321,
      "prev_close": 476.21,
      "open": 477.13,
      "high": 479.42,
      "low": 476.84,
      "bid": 478.55,
      "ask": 478.57,
      "timestamp": "2025-05-22T15:59:00Z",
      "market_cap": 435672543210,
      "exchange": "NYSE"
    },
    {
      "symbol": "AAPL",
      "price": 189.35,
      "change": -0.87,
      "change_percent": -0.46,
      "volume": 54321876,
      "prev_close": 190.22,
      "open": 190.78,
      "high": 191.24,
      "low": 188.97,
      "bid": 189.34,
      "ask": 189.36,
      "timestamp": "2025-05-22T15:59:00Z",
      "market_cap": 2987654321000,
      "exchange": "NASDAQ"
    },
    {
      "symbol": "MSFT",
      "price": 412.78,
      "change": 3.65,
      "change_percent": 0.89,
      "volume": 19876543,
      "prev_close": 409.13,
      "open": 410.25,
      "high": 413.89,
      "low": 409.86,
      "bid": 412.77,
      "ask": 412.79,
      "timestamp": "2025-05-22T15:59:00Z",
      "market_cap": 3156789012000,
      "exchange": "NASDAQ"
    }
  ]
}
GET /market/earnings

Retrieve upcoming earnings announcements for market symbols.

Parameters

Parameter Type Required Description
symbols string No Comma-separated list of symbols
days integer No Number of days to look ahead (default: 30, max: 90)
Example Request 
curl -X GET "https://api.vespera.com/v1/market/earnings?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "earnings": [
    {
      "symbol": "AAPL",
      "company_name": "Apple Inc.",
      "announcement_date": "2025-07-28",
      "time": "after_market",
      "fiscal_quarter": "Q3",
      "fiscal_year": 2025,
      "consensus_eps": 1.87,
      "previous_eps": 1.72,
      "implied_volatility": 0.32
    },
    {
      "symbol": "MSFT",
      "company_name": "Microsoft Corporation",
      "announcement_date": "2025-07-23",
      "time": "after_market",
      "fiscal_quarter": "Q4",
      "fiscal_year": 2025,
      "consensus_eps": 2.35,
      "previous_eps": 2.21,
      "implied_volatility": 0.28
    },
    {
      "symbol": "NVDA",
      "company_name": "NVIDIA Corporation",
      "announcement_date": "2025-06-15",
      "time": "after_market",
      "fiscal_quarter": "Q2",
      "fiscal_year": 2025,
      "consensus_eps": 0.83,
      "previous_eps": 0.68,
      "implied_volatility": 0.49
    }
  ]
}
GET /market/dividends

Retrieve upcoming dividend events for market symbols.

Parameters

Parameter Type Required Description
symbols string No Comma-separated list of symbols
days integer No Number of days to look ahead (default: 30, max: 90)
Example Request 
curl -X GET "https://api.vespera.com/v1/market/dividends?symbols=SPY,AAPL,MSFT" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "dividends": [
    {
      "symbol": "AAPL",
      "company_name": "Apple Inc.",
      "ex_dividend_date": "2025-06-10",
      "record_date": "2025-06-12",
      "payment_date": "2025-06-19",
      "amount": 0.25,
      "frequency": "quarterly",
      "annual_yield": 0.53,
      "dividend_type": "regular"
    },
    {
      "symbol": "MSFT",
      "company_name": "Microsoft Corporation",
      "ex_dividend_date": "2025-05-30",
      "record_date": "2025-06-02",
      "payment_date": "2025-06-10",
      "amount": 0.78,
      "frequency": "quarterly",
      "annual_yield": 0.76,
      "dividend_type": "regular"
    },
    {
      "symbol": "SPY",
      "company_name": "SPDR S&P 500 ETF Trust",
      "ex_dividend_date": "2025-06-20",
      "record_date": "2025-06-23",
      "payment_date": "2025-06-30",
      "amount": 1.68,
      "frequency": "quarterly",
      "annual_yield": 1.40,
      "dividend_type": "regular"
    }
  ]
}

Option Strategies

GET /strategies/search

Search for optimal option strategies based on your market outlook and criteria.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
outlook string Yes Market outlook: 'bullish', 'bearish', 'neutral', 'volatile'
max_risk number No Maximum risk per contract ($)
min_profit number No Minimum potential profit ($)
min_probability number No Minimum probability of profit (0-1)
expiration_min integer No Minimum days to expiration
expiration_max integer No Maximum days to expiration
strategy_types string No Comma-separated list of strategy types to include
Example Request 
curl -X GET "https://api.vespera.com/v1/strategies/search?symbol=SPY&outlook=bullish&max_risk=1000&min_probability=0.6&expiration_min=14&expiration_max=45" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "underlying_price": 478.56,
  "strategies": [
    {
      "strategy": "bull_call_spread",
      "rank": 1,
      "score": 8.7,
      "outlook": "bullish",
      "max_profit": 320.00,
      "max_loss": 680.00,
      "profit_probability": 0.64,
      "risk_reward_ratio": 0.47,
      "expected_value": 43.20,
      "details": {
        "expiration": "2025-06-20",
        "days_to_expiration": 29,
        "legs": [
          {
            "option_type": "call",
            "strike": 480,
            "action": "buy",
            "premium": 10.80
          },
          {
            "option_type": "call",
            "strike": 490,
            "action": "sell",
            "premium": 4.00
          }
        ],
        "width": 10,
        "net_debit": 6.80,
        "breakeven": 486.80
      }
    },
    {
      "strategy": "risk_reversal",
      "rank": 2,
      "score": 8.2,
      "outlook": "bullish",
      "max_profit": "undefined",
      "max_loss": 864.00,
      "profit_probability": 0.67,
      "risk_reward_ratio": "undefined",
      "expected_value": 56.80,
      "details": {
        "expiration": "2025-06-20",
        "days_to_expiration": 29,
        "legs": [
          {
            "option_type": "call",
            "strike": 485,
            "action": "buy",
            "premium": 7.65
          },
          {
            "option_type": "put",
            "strike": 465,
            "action": "sell",
            "premium": 6.01
          }
        ],
        "net_debit": 1.64,
        "breakeven": 486.64
      }
    },
    {
      "strategy": "broken_wing_butterfly",
      "rank": 3,
      "score": 7.8,
      "outlook": "bullish",
      "max_profit": 235.00,
      "max_loss": 265.00,
      "profit_probability": 0.58,
      "risk_reward_ratio": 0.89,
      "expected_value": 29.10,
      "details": {
        "expiration": "2025-06-06",
        "days_to_expiration": 15,
        "legs": [
          {
            "option_type": "call",
            "strike": 475,
            "action": "buy",
            "premium": 12.80,
            "quantity": 1
          },
          {
            "option_type": "call",
            "strike": 485,
            "action": "sell",
            "premium": 7.65,
            "quantity": 2
          },
          {
            "option_type": "call",
            "strike": 500,
            "action": "buy",
            "premium": 3.00,
            "quantity": 1
          }
        ],
        "net_debit": 2.65,
        "max_profit_price": 485
      }
    }
  ]
}
POST /strategies/analyze

Analyze a custom option strategy or position for risk/reward metrics.

Request Body

Parameter Type Required Description
positions array Yes Array of option position objects
underlying_price number No Override the current underlying price
price_range number No Price range for analysis as percentage (default: 15)
price_steps integer No Number of price steps in analysis (default: 21)
time_steps integer No Number of time steps in analysis (default: 5)
Example Request 
curl -X POST "https://api.vespera.com/v1/strategies/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "symbol": "SPY",
        "option_type": "call",
        "strike": 480,
        "expiration": "2025-06-20",
        "action": "buy",
        "quantity": 1,
        "price": 10.80
      },
      {
        "symbol": "SPY",
        "option_type": "call",
        "strike": 490,
        "expiration": "2025-06-20",
        "action": "sell",
        "quantity": 1,
        "price": 4.00
      }
    ],
    "price_range": 10,
    "price_steps": 11
  }'
Example Response 
{
  "strategy_summary": {
    "strategy_type": "bull_call_spread",
    "net_premium": -680.00,
    "max_profit": 320.00,
    "max_loss": 680.00,
    "breakeven": 486.80,
    "profit_probability": 0.64,
    "risk_reward_ratio": 0.47,
    "expected_value": 43.20
  },
  "aggregate_greeks": {
    "delta": 0.48,
    "gamma": 0.021,
    "theta": -3.45,
    "vega": 9.82,
    "rho": 2.18
  },
  "profit_loss_by_price": [
    {
      "price": 430.70,
      "pnl": -680.00
    },
    {
      "price": 440.63,
      "pnl": -680.00
    },
    {
      "price": 450.56,
      "pnl": -680.00
    },
    {
      "price": 460.49,
      "pnl": -680.00
    },
    {
      "price": 470.42,
      "pnl": -680.00
    },
    {
      "price": 480.35,
      "pnl": -680.00
    },
    {
      "price": 490.28,
      "pnl": 320.00
    },
    {
      "price": 500.21,
      "pnl": 320.00
    },
    {
      "price": 510.14,
      "pnl": 320.00
    },
    {
      "price": 520.07,
      "pnl": 320.00
    },
    {
      "price": 530.00,
      "pnl": 320.00
    }
  ],
  "profit_loss_by_time": [
    {
      "days_remaining": 29,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -570.00},
        {"price": 480.35, "pnl": -385.00},
        {"price": 490.28, "pnl": -140.00}
      ]
    },
    {
      "days_remaining": 22,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -520.00},
        {"price": 480.35, "pnl": -295.00},
        {"price": 490.28, "pnl": -25.00}
      ]
    },
    {
      "days_remaining": 15,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -480.00},
        {"price": 480.35, "pnl": -198.00},
        {"price": 490.28, "pnl": 120.00}
      ]
    },
    {
      "days_remaining": 7,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -450.00},
        {"price": 480.35, "pnl": -98.00},
        {"price": 490.28, "pnl": 220.00}
      ]
    },
    {
      "days_remaining": 0,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -680.00},
        {"price": 480.35, "pnl": -680.00},
        {"price": 490.28, "pnl": 320.00}
      ]
    }
  ],
  "risk_metrics": {
    "delta_exposure": 230.40,
    "gamma_exposure": 100.80,
    "vega_exposure": 471.36,
    "theta_decay_daily": -16.56,
    "optimal_price": 500.00,
    "optimal_days": 0
  }
}

Option Screener

GET /screener/options

Screen for options based on various criteria and metrics.

Parameters

Parameter Type Required Description
symbols string No Comma-separated list of symbols to screen
option_type string No Type of options to return: 'call', 'put', or 'both' (default)
min_days integer No Minimum days to expiration
max_days integer No Maximum days to expiration
min_delta number No Minimum absolute delta value (0-1)
max_delta number No Maximum absolute delta value (0-1)
min_volume integer No Minimum trading volume
min_open_interest integer No Minimum open interest
min_iv number No Minimum implied volatility as decimal (e.g., 0.2)
max_iv number No Maximum implied volatility as decimal (e.g., 0.5)
min_iv_percentile number No Minimum IV percentile (0-100)
min_bid_ask_spread number No Minimum bid-ask spread in percentage
min_theta number No Minimum absolute theta value
limit integer No Maximum number of results to return (default: 50, max: 200)
sort_by string No Field to sort by (e.g., 'volume', 'open_interest', 'iv')
sort_order string No Sort order: 'asc' or 'desc' (default)
Example Request 
curl -X GET "https://api.vespera.com/v1/screener/options?option_type=call&min_days=10&max_days=45&min_delta=0.3&max_delta=0.7&min_volume=500&min_iv=0.2&sort_by=volume&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "count": 3,
  "page": 1,
  "total_pages": 1,
  "results": [
    {
      "symbol": "SPY",
      "underlying_price": 478.56,
      "contract_symbol": "SPY250620C00480000",
      "option_type": "call",
      "strike": 480,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 10.75,
      "ask": 10.85,
      "last": 10.80,
      "volume": 8754,
      "open_interest": 42587,
      "implied_volatility": 0.22,
      "delta": 0.48,
      "gamma": 0.042,
      "theta": -0.12,
      "vega": 0.37,
      "rho": 0.15,
      "time_value": 10.80,
      "intrinsic_value": 0.00,
      "iv_percentile": 38.5,
      "bid_ask_spread_percent": 0.93
    },
    {
      "symbol": "AAPL",
      "underlying_price": 189.35,
      "contract_symbol": "AAPL250620C00190000",
      "option_type": "call",
      "strike": 190,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 8.80,
      "ask": 8.95,
      "last": 8.90,
      "volume": 6321,
      "open_interest": 28976,
      "implied_volatility": 0.28,
      "delta": 0.47,
      "gamma": 0.053,
      "theta": -0.14,
      "vega": 0.33,
      "rho": 0.12,
      "time_value": 8.90,
      "intrinsic_value": 0.00,
      "iv_percentile": 42.3,
      "bid_ask_spread_percent": 1.70
    },
    {
      "symbol": "MSFT",
      "underlying_price": 412.78,
      "contract_symbol": "MSFT250620C00410000",
      "option_type": "call",
      "strike": 410,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 19.50,
      "ask": 19.80,
      "last": 19.65,
      "volume": 3542,
      "open_interest": 15843,
      "implied_volatility": 0.24,
      "delta": 0.51,
      "gamma": 0.038,
      "theta": -0.18,
      "vega": 0.42,
      "rho": 0.20,
      "time_value": 16.87,
      "intrinsic_value": 2.78,
      "iv_percentile": 36.8,
      "bid_ask_spread_percent": 1.54
    }
  ]
}
GET /screener/unusual

Identify unusual options activity based on volume, open interest, and other metrics.

Parameters

Parameter Type Required Description
symbols string No Comma-separated list of symbols to screen
option_type string No Type of options to return: 'call', 'put', or 'both' (default)
min_volume_oi_ratio number No Minimum volume to open interest ratio
min_volume integer No Minimum trading volume
min_premium number No Minimum option premium in dollars
limit integer No Maximum number of results to return (default: 50, max: 100)
Example Request 
curl -X GET "https://api.vespera.com/v1/screener/unusual?min_volume_oi_ratio=0.5&min_volume=1000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "count": 3,
  "results": [
    {
      "symbol": "NVDA",
      "underlying_price": 825.36,
      "contract_symbol": "NVDA250620C00850000",
      "option_type": "call",
      "strike": 850,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 80.25,
      "ask": 81.50,
      "last": 80.85,
      "volume": 12543,
      "open_interest": 5432,
      "volume_oi_ratio": 2.31,
      "implied_volatility": 0.48,
      "delta": 0.46,
      "unusual_score": 92,
      "premium_value": 8085000,
      "trade_type": "sweep",
      "sentiment": "bullish",
      "time_of_activity": "2025-05-22T14:35:28Z"
    },
    {
      "symbol": "AAPL",
      "underlying_price": 189.35,
      "contract_symbol": "AAPL250620P00175000",
      "option_type": "put",
      "strike": 175,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 4.25,
      "ask": 4.45,
      "last": 4.35,
      "volume": 8765,
      "open_interest": 12543,
      "volume_oi_ratio": 0.70,
      "implied_volatility": 0.32,
      "delta": -0.29,
      "unusual_score": 86,
      "premium_value": 3812775,
      "trade_type": "block",
      "sentiment": "bearish",
      "time_of_activity": "2025-05-22T13:47:15Z"
    },
    {
      "symbol": "SPY",
      "underlying_price": 478.56,
      "contract_symbol": "SPY250523P00460000",
      "option_type": "put",
      "strike": 460,
      "expiration": "2025-05-23",
      "days_to_expiration": 1,
      "bid": 0.45,
      "ask": 0.48,
      "last": 0.47,
      "volume": 34567,
      "open_interest": 12876,
      "volume_oi_ratio": 2.68,
      "implied_volatility": 0.26,
      "delta": -0.12,
      "unusual_score": 94,
      "premium_value": 1624649,
      "trade_type": "sweep",
      "sentiment": "bearish",
      "time_of_activity": "2025-05-22T15:12:42Z"
    }
  ]
}

Bulk Operations

POST /bulk/options

Retrieve options data for multiple symbols in a single request.

Request Body

Parameter Type Required Description
symbols array Yes Array of symbols to retrieve data for
expiration string No Expiration date in YYYY-MM-DD format
option_type string No Type of options to return: 'call', 'put', or 'both' (default)
moneyness string No Filter by moneyness: 'itm', 'otm', 'atm', or 'all' (default)
greeks boolean No Include option greeks in response (default: true)
Example Request 
curl -X POST "https://api.vespera.com/v1/bulk/options" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["SPY", "AAPL", "MSFT"],
    "expiration": "2025-06-20",
    "option_type": "call",
    "moneyness": "all"
  }'
Example Response 
{
  "results": [
    {
      "symbol": "SPY",
      "underlying_price": 478.56,
      "expiration": "2025-06-20",
      "calls": [
        {
          "contract_symbol": "SPY250620C00450000",
          "strike": 450,
          "last": 42.15,
          "bid": 42.05,
          "ask": 42.25,
          "volume": 532,
          "open_interest": 8543,
          "implied_volatility": 0.21,
          "delta": 0.68,
          "gamma": 0.015,
          "theta": -0.032,
          "vega": 0.97,
          "rho": 0.058,
          "time_value": 13.59,
          "intrinsic_value": 28.56,
          "itm": true
        },
        // Additional strikes...
      ]
    },
    {
      "symbol": "AAPL",
      "underlying_price": 189.35,
      "expiration": "2025-06-20",
      "calls": [
        {
          "contract_symbol": "AAPL250620C00170000",
          "strike": 170,
          "last": 25.65,
          "bid": 25.55,
          "ask": 25.75,
          "volume": 428,
          "open_interest": 6543,
          "implied_volatility": 0.28,
          "delta": 0.72,
          "gamma": 0.018,
          "theta": -0.035,
          "vega": 0.83,
          "rho": 0.053,
          "time_value": 6.30,
          "intrinsic_value": 19.35,
          "itm": true
        },
        // Additional strikes...
      ]
    },
    {
      "symbol": "MSFT",
      "underlying_price": 412.78,
      "expiration": "2025-06-20",
      "calls": [
        {
          "contract_symbol": "MSFT250620C00380000",
          "strike": 380,
          "last": 44.25,
          "bid": 44.15,
          "ask": 44.35,
          "volume": 315,
          "open_interest": 4892,
          "implied_volatility": 0.24,
          "delta": 0.70,
          "gamma": 0.016,
          "theta": -0.037,
          "vega": 0.92,
          "rho": 0.062,
          "time_value": 11.47,
          "intrinsic_value": 32.78,
          "itm": true
        },
        // Additional strikes...
      ]
    }
  ]
}
POST /bulk/quotes

Retrieve real-time quotes for specific option contracts in a single request.

Request Body

Parameter Type Required Description
contracts array Yes Array of option contract symbols or contract specifications
greeks boolean No Include option greeks in response (default: true)
Example Request 
curl -X POST "https://api.vespera.com/v1/bulk/quotes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contracts": [
      "SPY250620C00480000",
      "AAPL250620C00190000",
      {
        "symbol": "MSFT",
        "expiration": "2025-06-20",
        "strike": 410,
        "option_type": "call"
      }
    ],
    "greeks": true
  }'
Example Response 
{
  "results": [
    {
      "symbol": "SPY",
      "underlying_price": 478.56,
      "contract_symbol": "SPY250620C00480000",
      "option_type": "call",
      "strike": 480,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 10.75,
      "ask": 10.85,
      "last": 10.80,
      "volume": 8754,
      "open_interest": 42587,
      "implied_volatility": 0.22,
      "delta": 0.48,
      "gamma": 0.042,
      "theta": -0.12,
      "vega": 0.37,
      "rho": 0.15,
      "time_value": 10.80,
      "intrinsic_value": 0.00,
      "change": 0.35,
      "change_percent": 3.35,
      "itm": false
    },
    {
      "symbol": "AAPL",
      "underlying_price": 189.35,
      "contract_symbol": "AAPL250620C00190000",
      "option_type": "call",
      "strike": 190,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 8.80,
      "ask": 8.95,
      "last": 8.90,
      "volume": 6321,
      "open_interest": 28976,
      "implied_volatility": 0.28,
      "delta": 0.47,
      "gamma": 0.053,
      "theta": -0.14,
      "vega": 0.33,
      "rho": 0.12,
      "time_value": 8.90,
      "intrinsic_value": 0.00,
      "change": -0.25,
      "change_percent": -2.73,
      "itm": false
    },
    {
      "symbol": "MSFT",
      "underlying_price": 412.78,
      "contract_symbol": "MSFT250620C00410000",
      "option_type": "call",
      "strike": 410,
      "expiration": "2025-06-20",
      "days_to_expiration": 29,
      "bid": 19.50,
      "ask": 19.80,
      "last": 19.65,
      "volume": 3542,
      "open_interest": 15843,
      "implied_volatility": 0.24,
      "delta": 0.51,
      "gamma": 0.038,
      "theta": -0.18,
      "vega": 0.42,
      "rho": 0.20,
      "time_value": 16.87,
      "intrinsic_value": 2.78,
      "change": 0.95,
      "change_percent": 5.08,
      "itm": true
    }
  ]
}

Analytics

GET /analytics/volatility

Retrieve volatility metrics and analysis for options.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
lookback integer No Lookback period in days (default: 252)
term_structure boolean No Include term structure analysis (default: true)
skew boolean No Include volatility skew analysis (default: true)
surface boolean No Include volatility surface data (default: false)
Example Request 
curl -X GET "https://api.vespera.com/v1/analytics/volatility?symbol=SPY&lookback=252&term_structure=true&skew=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "timestamp": "2025-05-22T15:30:00Z",
  "underlying_price": 478.56,
  "volatility_metrics": {
    "current_iv": 0.18,
    "iv_rank": 42.5,
    "iv_percentile": 38.7,
    "hv_20": 0.14,
    "hv_50": 0.15,
    "hv_100": 0.16,
    "hv_252": 0.17,
    "iv_hv_ratio": 1.13,
    "max_iv": 0.32,
    "min_iv": 0.12,
    "average_iv": 0.19
  },
  "term_structure": {
    "current": [
      {
        "days": 7,
        "iv": 0.17
      },
      {
        "days": 30,
        "iv": 0.18
      },
      {
        "days": 60,
        "iv": 0.19
      },
      {
        "days": 90,
        "iv": 0.20
      },
      {
        "days": 180,
        "iv": 0.21
      },
      {
        "days": 360,
        "iv": 0.22
      }
    ],
    "historical": [
      {
        "date": "2025-04-22",
        "term_structure": [
          {"days": 30, "iv": 0.19},
          {"days": 60, "iv": 0.20},
          {"days": 90, "iv": 0.21}
        ]
      },
      {
        "date": "2025-03-22",
        "term_structure": [
          {"days": 30, "iv": 0.20},
          {"days": 60, "iv": 0.21},
          {"days": 90, "iv": 0.22}
        ]
      }
    ]
  },
  "skew": {
    "current": [
      {
        "delta": 0.10,
        "iv": 0.24,
        "relative_iv": 1.33,
        "option_type": "put"
      },
      {
        "delta": 0.25,
        "iv": 0.21,
        "relative_iv": 1.17,
        "option_type": "put"
      },
      {
        "delta": 0.50,
        "iv": 0.18,
        "relative_iv": 1.00,
        "option_type": "both"
      },
      {
        "delta": 0.25,
        "iv": 0.17,
        "relative_iv": 0.94,
        "option_type": "call"
      },
      {
        "delta": 0.10,
        "iv": 0.19,
        "relative_iv": 1.06,
        "option_type": "call"
      }
    ],
    "skew_metrics": {
      "put_call_skew": 1.29,
      "wing_skew": 1.26,
      "skew_slope": -0.042
    }
  }
}

This endpoint provides IV rank, term structure, and volatility skew analysis for advanced options analytics.

GET /analytics/strategies

Access pre-built strategy analysis based on current market conditions.

Parameters

Parameter Type Required Description
symbol string Yes The underlying symbol
strategy_type string No Strategy type: 'all' (default), 'bullish', 'bearish', 'neutral', 'volatile'
expiration_range string No Expiration range: 'short_term', 'medium_term', 'long_term', or 'all' (default)
include_backtest boolean No Include historical backtest data (default: true)
Example Request 
curl -X GET "https://api.vespera.com/v1/analytics/strategies?symbol=SPY&strategy_type=neutral&expiration_range=medium_term" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Example Response 
{
  "symbol": "SPY",
  "timestamp": "2025-05-22T15:30:00Z",
  "underlying_price": 478.56,
  "market_conditions": {
    "iv_rank": 42.5,
    "hv_iv_ratio": 0.78,
    "trend": "neutral",
    "term_structure": "contango",
    "put_call_skew": 1.29
  },
  "recommended_strategies": [
    {
      "strategy": "iron_condor",
      "outlook": "neutral",
      "max_profit": 265.00,
      "max_loss": 735.00,
      "profit_probability": 0.68,
      "risk_reward_ratio": 0.36,
      "expected_value": 32.40,
      "details": {
        "expiration": "2025-06-20",
        "days_to_expiration": 29,
        "legs": [
          {
            "option_type": "call",
            "strike": 495,
            "action": "sell",
            "premium": 2.95
          },
          {
            "option_type": "call",
            "strike": 500,
            "action": "buy",
            "premium": 1.75
          },
          {
            "option_type": "put",
            "strike": 465,
            "action": "sell",
            "premium": 3.45
          },
          {
            "option_type": "put",
            "strike": 460,
            "action": "buy",
            "premium": 2.00
          }
        ],
        "width": 5,
        "net_credit": 2.65,
        "breakeven_lower": 462.35,
        "breakeven_upper": 497.65
      },
      "backtest": {
        "win_rate": 0.72,
        "average_return": 1.87,
        "sharpe_ratio": 1.28,
        "max_drawdown": -8.4,
        "performance_summary": "This strategy has performed well in similar market conditions over the past 12 months, with 72% of trades being profitable."
      }
    },
    {
      "strategy": "calendar_spread",
      "outlook": "neutral",
      "max_profit": "undefined",
      "max_loss": 245.00,
      "profit_probability": 0.63,
      "risk_reward_ratio": "undefined",
      "expected_value": 28.65,
      "details": {
        "short_leg": {
          "expiration": "2025-06-20",
          "strike": 480,
          "option_type": "call",
          "premium": 10.35
        },
        "long_leg": {
          "expiration": "2025-07-18",
          "strike": 480,
          "option_type": "call",
          "premium": 12.80
        },
        "debit": 2.45,
        "optimal_price": 480
      }
    }
  ]
}
GET /analytics/risk

Analyze risk metrics for specific option positions or strategies.

Parameters

Parameter Type Required Description
positions array Yes Array of option position objects
underlying_price number No Override the current underlying price
price_range number No Price range for analysis as percentage (default: 15)
include_greeks boolean No Include aggregated position greeks (default: true)
volatility_shock boolean No Include volatility shock scenarios (default: false)
Example Request 
curl -X POST "https://api.vespera.com/v1/analytics/risk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "symbol": "SPY",
        "contract_symbol": "SPY250620C00495000",
        "option_type": "call",
        "strike": 495,
        "expiration": "2025-06-20",
        "action": "sell",
        "quantity": 1,
        "price": 2.95
      },
      {
        "symbol": "SPY",
        "contract_symbol": "SPY250620C00500000",
        "option_type": "call",
        "strike": 500,
        "expiration": "2025-06-20",
        "action": "buy",
        "quantity": 1,
        "price": 1.75
      },
      {
        "symbol": "SPY",
        "contract_symbol": "SPY250620P00465000",
        "option_type": "put",
        "strike": 465,
        "expiration": "2025-06-20",
        "action": "sell",
        "quantity": 1,
        "price": 3.45
      },
      {
        "symbol": "SPY",
        "contract_symbol": "SPY250620P00460000",
        "option_type": "put",
        "strike": 460,
        "expiration": "2025-06-20",
        "action": "buy",
        "quantity": 1,
        "price": 2.00
      }
    ],
    "price_range": 10,
    "include_greeks": true
  }'
Example Response 
{
  "strategy_summary": {
    "strategy_type": "iron_condor",
    "net_premium": 265.00,
    "max_profit": 265.00,
    "max_loss": 735.00,
    "breakeven_lower": 462.35,
    "breakeven_upper": 497.65,
    "profit_probability": 0.68,
    "risk_reward_ratio": 0.36,
    "expected_value": 32.40
  },
  "aggregate_greeks": {
    "delta": -0.06,
    "gamma": -0.003,
    "theta": 4.78,
    "vega": -12.45,
    "rho": -1.35
  },
  "profit_loss_by_price": [
    {
      "price": 430.70,
      "pnl": -735.00
    },
    {
      "price": 440.63,
      "pnl": -735.00
    },
    {
      "price": 450.56,
      "pnl": -735.00
    },
    {
      "price": 460.49,
      "pnl": -56.00
    },
    {
      "price": 470.42,
      "pnl": 265.00
    },
    {
      "price": 480.35,
      "pnl": 265.00
    },
    {
      "price": 490.28,
      "pnl": 265.00
    },
    {
      "price": 500.21,
      "pnl": -84.00
    },
    {
      "price": 510.14,
      "pnl": -735.00
    },
    {
      "price": 520.07,
      "pnl": -735.00
    },
    {
      "price": 530.00,
      "pnl": -735.00
    }
  ],
  "profit_loss_by_time": [
    {
      "days_remaining": 29,
      "pnl_by_price": [
        {"price": 470.42, "pnl": 32.00},
        {"price": 480.35, "pnl": 58.00},
        {"price": 490.28, "pnl": 15.00}
      ]
    },
    {
      "days_remaining": 22,
      "pnl_by_price": [
        {"price": 470.42, "pnl": 78.00},
        {"price": 480.35, "pnl": 105.00},
        {"price": 490.28, "pnl": 65.00}
      ]
    },
    {
      "days_remaining": 15,
      "pnl_by_price": [
        {"price": 470.42, "pnl": 128.00},
        {"price": 480.35, "pnl": 165.00},
        {"price": 490.28, "pnl": 132.00}
      ]
    },
    {
      "days_remaining": 7,
      "pnl_by_price": [
        {"price": 470.42, "pnl": 189.00},
        {"price": 480.35, "pnl": 212.00},
        {"price": 490.28, "pnl": 187.00}
      ]
    },
    {
      "days_remaining": 0,
      "pnl_by_price": [
        {"price": 470.42, "pnl": 265.00},
        {"price": 480.35, "pnl": 265.00},
        {"price": 490.28, "pnl": 265.00}
      ]
    }
  ],
  "risk_metrics": {
    "delta_exposure": -28.74,
    "gamma_exposure": -143.55,
    "vega_exposure": -596.10,
    "theta_decay_daily": 22.87,
    "optimal_price": 480.35,
    "optimal_days": 29
  }
}

Rate Limits

API requests are subject to rate limiting to ensure fair usage. Rate limits vary by subscription tier:

Plan Requests per Minute Requests per Day
Starter 60 10,000
Professional 300 100,000
Institutional Unlimited Unlimited

Rate limit information is included in the response headers:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current period
  • X-RateLimit-Remaining: The number of requests remaining in the current period
  • X-RateLimit-Reset: The time when the current rate limit window resets (Unix timestamp)

Error Handling

The Vespera API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Description
200 - OK The request was successful
400 - Bad Request The request was invalid or missing required parameters
401 - Unauthorized Authentication failed or missing API key
403 - Forbidden Your API key does not have permission to access the requested resource
404 - Not Found The requested resource does not exist
429 - Too Many Requests Rate limit exceeded
500 - Server Error An error occurred on the server
Example Error Response 
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'symbol' is required",
    "status": 400
  }
}

SDKs & Libraries

We provide official client libraries to make integrating with the Vespera API easier in various programming languages.

Python

Our Python SDK is ideal for data scientists and quants.

View on GitHub

JavaScript

Node.js SDK for building trading applications.

View on GitHub

R

R package for statistical analysis and modeling.

View on GitHub

Webhooks

Vespera provides webhooks for real-time notifications about market events and changes to your tracked options.

Webhook Setup

Set up webhooks through the API or in your Vespera dashboard. You can configure multiple endpoints for different event types.

Webhook Endpoints

POST /webhooks

Create a new webhook endpoint.

Request Body

Parameter Type Required Description
url string Yes The URL to send webhook events to
event_types array Yes Array of event types to subscribe to
description string No Description of the webhook
headers object No Custom headers to include in webhook requests
Example Request 
curl -X POST "https://api.vespera.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "event_types": ["option.price_alert", "option.unusual_volume", "option.expiration"],
    "description": "Options alerts webhook",
    "headers": {
      "X-Custom-Auth": "your-custom-auth-token"
    }
  }'
Example Response 
{
  "id": "wh_12345",
  "url": "https://your-server.com/webhook",
  "event_types": ["option.price_alert", "option.unusual_volume", "option.expiration"],
  "description": "Options alerts webhook",
  "created_at": "2025-05-22T15:30:00Z",
  "status": "active",
  "secret": "whsec_87654321"
}

Available Event Types

Event Type Description
option.price_alert Triggered when an option price moves beyond specified thresholds
option.unusual_volume Triggered when an option experiences unusual trading volume
option.expiration Triggered as options approach expiration (configurable days before)
option.iv_change Triggered when implied volatility changes significantly
market.earnings Triggered when earnings announcements are approaching
market.dividend Triggered when ex-dividend dates are approaching
market.volatility Triggered when market volatility metrics cross thresholds

Example Webhook Payload

Example Webhook Payload 
{
  "id": "evt_123456",
  "event_type": "option.unusual_volume",
  "created_at": "2025-05-22T15:35:28Z",
  "data": {
    "symbol": "NVDA",
    "underlying_price": 825.36,
    "contract_symbol": "NVDA250620C00850000",
    "option_type": "call",
    "strike": 850,
    "expiration": "2025-06-20",
    "days_to_expiration": 29,
    "last_price": 80.85,
    "volume": 12543,
    "open_interest": 5432,
    "volume_oi_ratio": 2.31,
    "average_daily_volume": 2500,
    "volume_increase": 401.7,
    "implied_volatility": 0.48,
    "unusual_score": 92
  }
}

Security Best Practices

Always verify webhook signatures to ensure requests come from Vespera. The webhook secret provided when creating a webhook should be used to validate the X-Vespera-Signature header included in all webhook requests.

Response Schemas

Below are the detailed schema definitions for common response objects from the Vespera API.

Option Contract Object

Option Contract Schema 
{
  "contract_symbol": "SPY250620C00480000",   // OCC option symbol format
  "symbol": "SPY",                       // Underlying symbol
  "option_type": "call",                 // "call" or "put"
  "strike": 480,                         // Strike price
  "expiration": "2025-06-20",            // Expiration date (YYYY-MM-DD)
  "days_to_expiration": 29,              // Days until expiration
  "last": 10.80,                         // Last traded price
  "bid": 10.75,                          // Current bid price
  "ask": 10.85,                          // Current ask price
  "mid": 10.80,                          // Mid-point between bid and ask
  "mark": 10.80,                         // Mark price (used for calculations)
  "volume": 8754,                        // Today's trading volume
  "open_interest": 42587,                // Open interest
  "implied_volatility": 0.22,            // Implied volatility as decimal
  "delta": 0.48,                         // Delta (0 to 1 for calls, -1 to 0 for puts)
  "gamma": 0.042,                        // Gamma
  "theta": -0.12,                        // Theta (daily time decay)
  "vega": 0.37,                          // Vega
  "rho": 0.15,                           // Rho
  "time_value": 10.80,                   // Time value component
  "intrinsic_value": 0.00,               // Intrinsic value component
  "change": 0.35,                        // Price change from previous day
  "change_percent": 3.35,                // Percent price change
  "bid_ask_spread": 0.10,                // Difference between bid and ask
  "bid_ask_spread_percent": 0.93,        // Bid-ask spread as percentage
  "itm": false,                          // Whether option is in the money
  "multiplier": 100                      // Contract multiplier (typically 100)
}

Options Chain Response

Options Chain Schema 
{
  "symbol": "SPY",                       // Underlying symbol
  "underlying_price": 478.56,            // Current price of underlying
  "timestamp": "2025-05-22T15:30:00Z",   // Timestamp of the data
  "expiration": "2025-06-20",            // Expiration date
  "days_to_expiration": 29,              // Days until expiration
  "calls": [                             // Array of call option contracts
    { /* Option Contract Object */ },
    { /* Option Contract Object */ },
    // Additional contracts...
  ],
  "puts": [                              // Array of put option contracts
    { /* Option Contract Object */ },
    { /* Option Contract Object */ },
    // Additional contracts...
  ]
}

Strategy Analysis Response

Strategy Analysis Schema 
{
  "strategy_summary": {
    "strategy_type": "bull_call_spread",  // Identified strategy type
    "net_premium": -680.00,              // Net premium paid/received
    "max_profit": 320.00,                // Maximum potential profit
    "max_loss": 680.00,                  // Maximum potential loss
    "breakeven": 486.80,                 // Breakeven price at expiration
    "profit_probability": 0.64,          // Probability of profit
    "risk_reward_ratio": 0.47,           // Risk/reward ratio
    "expected_value": 43.20              // Statistical expected value
  },
  "aggregate_greeks": {                  // Aggregate greeks for entire position
    "delta": 0.48,
    "gamma": 0.021,
    "theta": -3.45,
    "vega": 9.82,
    "rho": 2.18
  },
  "profit_loss_by_price": [              // P&L at different price points
    {
      "price": 430.70,
      "pnl": -680.00
    },
    // Additional price points...
  ],
  "profit_loss_by_time": [               // P&L at different points in time
    {
      "days_remaining": 29,
      "pnl_by_price": [
        {"price": 470.42, "pnl": -570.00},
        {"price": 480.35, "pnl": -385.00},
        {"price": 490.28, "pnl": -140.00}
      ]
    },
    // Additional time points...
  ],
  "risk_metrics": {                      // Additional risk analysis metrics
    "delta_exposure": 230.40,
    "gamma_exposure": 100.80,
    "vega_exposure": 471.36,
    "theta_decay_daily": -16.56,
    "optimal_price": 500.00,
    "optimal_days": 0
  }
}

Code Examples

Below are basic examples of how to use the Vespera API in different programming languages.

Python 
import requests
import pandas as pd
import json

# Authentication
API_KEY = 'your_api_key'
API_URL = 'https://api.vespera.com/v1/options'

# Request parameters
params = {
    'symbol': 'SPY',
    'expiration': '2025-06-20',
    'strike_min': 450,
    'strike_max': 500,
    'option_type': 'call',
    'greeks': True
}

# API request with authentication
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Get options data
response = requests.get(
    API_URL, 
    params=params,
    headers=headers
)

# Process response
if response.status_code == 200:
    options_data = response.json()
    
    # Example: Convert to pandas DataFrame for analysis
    calls_df = pd.DataFrame(options_data['calls'])
    
    # Calculate risk metrics
    calls_df['theta_delta_ratio'] = calls_df['theta'].abs() / calls_df['delta']
    calls_df['premium'] = calls_df['last'] * 100  # Convert to dollar amount per contract
    
    # Find optimal trades based on criteria
    optimal_trades = calls_df[
        (calls_df['delta'] > 0.3) & 
        (calls_df['delta'] < 0.7) & 
        (calls_df['implied_volatility'] > 0.2)
    ]
    
    # Display results
    print("Optimal option trades based on criteria:")
    print(optimal_trades[['strike', 'last', 'delta', 'implied_volatility', 'theta_delta_ratio']].sort_values('theta_delta_ratio'))
    
    # Save data for later use
    calls_df.to_csv(f"spy_options_{options_data['expiration']}.csv", index=False)
    
else:
    print(f"Error: {response.status_code}, {response.text}")
JavaScript 
const axios = require('axios');

// Authentication
const API_KEY = 'your_api_key';
const API_URL = 'https://api.vespera.com/v1/options';

// Request parameters
const params = {
    symbol: 'SPY',
    expiration: '2025-06-20',
    strike_min: 450,
    strike_max: 500,
    option_type: 'call',
    greeks: true
};

// API request configuration
const config = {
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    },
    params: params
};

// Make the API request
async function fetchOptionsData() {
    try {
        const response = await axios.get(API_URL, config);
        
        // Process data for your trading model
        const optionsData = response.data;
        
        // Example: Filter options based on delta and implied volatility
        const filteredOptions = optionsData.calls.filter(option => {
            return option.delta > 0.3 && 
                   option.delta < 0.7 && 
                   option.implied_volatility > 0.2;
        });
        
        // Calculate additional metrics
        const enhancedOptions = filteredOptions.map(option => {
            return {
                ...option,
                thetaDeltaRatio: Math.abs(option.theta) / option.delta,
                premium: option.last * 100 // Dollar amount per contract
            };
        });
        
        // Sort by a specific metric
        const sortedOptions = enhancedOptions.sort((a, b) => a.thetaDeltaRatio - b.thetaDeltaRatio);
        
        console.log('Optimal options trades based on criteria:');
        sortedOptions.forEach(option => {
            console.log(`Strike: ${option.strike}, Price: $${option.last}, Delta: ${option.delta.toFixed(2)}, IV: ${(option.implied_volatility * 100).toFixed(1)}%, Theta/Delta: ${option.thetaDeltaRatio.toFixed(4)}`);
        });
        
        return sortedOptions;
    } catch (error) {
        console.error('API request failed:', error.response ? error.response.data : error.message);
    }
}

fetchOptionsData();
R 
library(httr)
library(jsonlite)
library(dplyr)
library(ggplot2)

# Authentication
api_key <- "your_api_key"
api_url <- "https://api.vespera.com/v1/options"

# Request parameters
params <- list(
  symbol = "SPY",
  expiration = "2025-06-20",
  strike_min = 450,
  strike_max = 500,
  option_type = "call",
  greeks = TRUE
)

# API request with authentication
headers <- c(
  "Authorization" = paste("Bearer", api_key),
  "Content-Type" = "application/json"
)

# Get options data
response <- GET(
  url = api_url,
  query = params,
  add_headers(headers)
)

# Process response
if (status_code(response) == 200) {
  options_data <- content(response, "parsed")
  
  # Convert to data frame for analysis
  calls_df <- as.data.frame(do.call(rbind, lapply(options_data$calls, as.data.frame)))
  
  # Calculate risk metrics
  calls_df <- calls_df %>%
    mutate(
      theta_delta_ratio = abs(theta) / delta,
      premium = last * 100  # Convert to dollar amount per contract
    )
  
  # Find optimal trades based on criteria
  optimal_trades <- calls_df %>%
    filter(
      delta > 0.3,
      delta < 0.7,
      implied_volatility > 0.2
    ) %>%
    arrange(theta_delta_ratio)
  
  # Display results
  print("Optimal option trades based on criteria:")
  print(optimal_trades %>% select(strike, last, delta, implied_volatility, theta_delta_ratio))
  
  # Create visualization
  ggplot(calls_df, aes(x = delta, y = implied_volatility, size = open_interest, color = theta)) +
    geom_point(alpha = 0.7) +
    scale_color_gradient(low = "green", high = "red") +
    labs(
      title = paste("SPY Options Chain -", options_data$expiration),
      x = "Delta",
      y = "Implied Volatility",
      size = "Open Interest",
      color = "Theta"
    ) +
    theme_minimal()
  
} else {
  print(paste("Error:", status_code(response), content(response, "text")))
}
Java 
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class VesperaApiExample {

    private static final String API_KEY = "your_api_key";
    private static final String API_URL = "https://api.vespera.com/v1/options";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        ObjectMapper mapper = new ObjectMapper();

        // Build URL with query parameters
        HttpUrl.Builder urlBuilder = HttpUrl.parse(API_URL).newBuilder();
        urlBuilder.addQueryParameter("symbol", "SPY");
        urlBuilder.addQueryParameter("expiration", "2025-06-20");
        urlBuilder.addQueryParameter("strike_min", "450");
        urlBuilder.addQueryParameter("strike_max", "500");
        urlBuilder.addQueryParameter("option_type", "call");
        urlBuilder.addQueryParameter("greeks", "true");

        // Build request with authentication
        Request request = new Request.Builder()
                .url(urlBuilder.build())
                .addHeader("Authorization", "Bearer " + API_KEY)
                .addHeader("Content-Type", "application/json")
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                // Parse JSON response
                Map optionsData = mapper.readValue(response.body().string(), Map.class);
                List> calls = (List>) optionsData.get("calls");

                // Filter options based on criteria
                List> filteredCalls = calls.stream()
                        .filter(option -> {
                            double delta = Double.parseDouble(option.get("delta").toString());
                            double iv = Double.parseDouble(option.get("implied_volatility").toString());
                            return delta > 0.3 && delta < 0.7 && iv > 0.2;
                        })
                        .collect(Collectors.toList());

                // Calculate additional metrics and sort
                List> enhancedCalls = new ArrayList<>();
                for (Map option : filteredCalls) {
                    double delta = Double.parseDouble(option.get("delta").toString());
                    double theta = Math.abs(Double.parseDouble(option.get("theta").toString()));
                    double thetaDeltaRatio = theta / delta;
                    double premium = Double.parseDouble(option.get("last").toString()) * 100;

                    option.put("theta_delta_ratio", thetaDeltaRatio);
                    option.put("premium", premium);
                    enhancedCalls.add(option);
                }

                // Sort by theta/delta ratio
                enhancedCalls.sort((a, b) -> {
                    double ratioA = (double) a.get("theta_delta_ratio");
                    double ratioB = (double) b.get("theta_delta_ratio");
                    return Double.compare(ratioA, ratioB);
                });

                // Display results
                System.out.println("Optimal option trades based on criteria:");
                for (Map option : enhancedCalls) {
                    System.out.printf("Strike: %.1f, Price: $%.2f, Delta: %.2f, IV: %.1f%%, Theta/Delta: %.4f%n",
                            option.get("strike"),
                            option.get("last"),
                            option.get("delta"),
                            (double) option.get("implied_volatility") * 100,
                            option.get("theta_delta_ratio"));
                }

            } else {
                System.out.println("Error: " + response.code() + ", " + response.message());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
C# 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

namespace VesperaApiExample
{
    class Program
    {
        private static readonly string API_KEY = "your_api_key";
        private static readonly string API_URL = "https://api.vespera.com/v1/options";

        static async Task Main(string[] args)
        {
            using (var client = new HttpClient())
            {
                // Set up authentication headers
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

                // Set up query parameters
                var queryParams = new Dictionary
                {
                    { "symbol", "SPY" },
                    { "expiration", "2025-06-20" },
                    { "strike_min", "450" },
                    { "strike_max", "500" },
                    { "option_type", "call" },
                    { "greeks", "true" }
                };

                // Build query string
                var queryString = string.Join("&", queryParams.Select(p => $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));
                var requestUrl = $"{API_URL}?{queryString}";

                try
                {
                    var response = await client.GetAsync(requestUrl);
                    response.EnsureSuccessStatusCode();

                    var content = await response.Content.ReadAsStringAsync();
                    using (JsonDocument doc = JsonDocument.Parse(content))
                    {
                        var root = doc.RootElement;
                        var calls = root.GetProperty("calls");

                        // Create a list to store filtered options
                        var filteredOptions = new List>();

                        // Process each option in the calls array
                        foreach (var option in calls.EnumerateArray())
                        {
                            double delta = option.GetProperty("delta").GetDouble();
                            double iv = option.GetProperty("implied_volatility").GetDouble();

                            // Filter based on criteria
                            if (delta > 0.3 && delta < 0.7 && iv > 0.2)
                            {
                                var optionData = new Dictionary
                                {
                                    { "strike", option.GetProperty("strike").GetDouble() },
                                    { "last", option.GetProperty("last").GetDouble() },
                                    { "delta", delta },
                                    { "implied_volatility", iv },
                                    { "theta", option.GetProperty("theta").GetDouble() }
                                };

                                // Calculate additional metrics
                                double theta = Math.Abs(option.GetProperty("theta").GetDouble());
                                double thetaDeltaRatio = theta / delta;
                                double premium = option.GetProperty("last").GetDouble() * 100;

                                optionData.Add("theta_delta_ratio", thetaDeltaRatio);
                                optionData.Add("premium", premium);

                                filteredOptions.Add(optionData);
                            }
                        }

                        // Sort options by theta/delta ratio
                        var sortedOptions = filteredOptions.OrderBy(o => (double)o["theta_delta_ratio"]).ToList();

                        // Display results
                        Console.WriteLine("Optimal option trades based on criteria:");
                        foreach (var option in sortedOptions)
                        {
                            Console.WriteLine($"Strike: {option["strike"]}, Price: ${option["last"]}, Delta: {option["delta"]:F2}, IV: {(double)option["implied_volatility"] * 100:F1}%, Theta/Delta: {option["theta_delta_ratio"]:F4}");
                        }
                    }
                }
                catch (HttpRequestException e)
                {
                    Console.WriteLine($"Error: {e.Message}");
                }
                catch (JsonException e)
                {
                    Console.WriteLine($"Error parsing JSON: {e.Message}");
                }
            }
        }
    }
}
cURL 
curl -X GET "https://api.vespera.com/v1/options?symbol=SPY&expiration=2025-06-20&strike_min=450&strike_max=500&option_type=call&greeks=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Support

If you need help with the API or have any questions, please contact our support team: