Ivolatility API

https://www.ivolatility.com/api/docs
Admin
The Ivolatility API provides access to the world's longest continuous equity and futures derivatives...
Tokens:50,672
Snippets:244
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install the ivolatility library

Source: https://www.ivolatility.com/api/docs

Install the required package via pip.

```bash
pip install ivolatility
```

--------------------------------

### Example JSON Response

Source: https://www.ivolatility.com/api/docs

A sample successful response containing status information and historical volatility data points.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "symbol": "AAPL",
      "exchange": "NASDAQ",
      "date": "2021-12-16 00:00:00",
      "price": 172.26,
      "record_no": 1,
      "10d_hv": 0.400359,
      "20d_hv": 0.344236,
      "30d_hv": 0.294668,
      "60d_hv": 0.245196,
      "90d_hv": 0.236368,
      "120d_hv": 0.225542,
      "150d_hv": 0.215056,
      "180d_hv": 0.22135
}
]

}
```

--------------------------------

### Retrieve Nearest Option Tickers in Python

Source: https://www.ivolatility.com/api/docs

Examples showing how to query the nearest option tickers using either moneyness or delta parameters.

```python
getMarketData = ivol.setMethod('/equities/eod/nearest-option-tickers')
marketData = getMarketData(symbol='TQQQ', startingDate='2022-03-15', dte=100, moneyness=5, callPut='C')
marketData = getMarketData(symbol='TQQQ', dte=100, delta=-.9, callPut='P')
```

--------------------------------

### API Response Structure

Source: https://www.ivolatility.com/api/docs

Example of a successful 200 OK JSON response containing market data and status metadata.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "symbol": "SPXW 211223P03890000",
      "stockId": 9327,
      "expirationDate": "2021-12-23T00:00:00.0000-0500",
      "strike": 3890,
      "type": "P",
      "style": "E",
      "openInterest": 88,
      "bidPrice": 0,
      "askPrice": 0,
      "lastPrice": 0,
      "bidDate": 20211223000000,
      "askDate": 20211223000000,
      "lastDate": 20211227000000,
      "bidSize": 0,
      "askSize": 0,
      "impliedUnderlyingPrice": 4735.353,
      "iv": 0.207512,
      "delta": 0,
      "vega": 0,
      "gamma": 0,
      "theta": 0,
      "rho": 0,
      "preIv": -1,
      "theoPrice": 0,
      "forwardPrice": 0,
      "timestamp": "2021-12-27T05:27:49.2660-0500",
      "sentToESTimestamp": "2021-12-27T05:28:02.1170-0500"
}
]

}
```

--------------------------------

### Earnings Calendar JSON Response

Source: https://www.ivolatility.com/api/docs

Example of a successful 200 OK response containing earnings metadata and a list of records.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "earning_date": "2024-09-05",
      "stock_id": 25301,
      "market_cap": 4301367296,
      "estimate": 0.59,
      "stock_price": 45.97,
      "implied_move": 15.55
}
]

}
```

--------------------------------

### API Response Structure

Source: https://www.ivolatility.com/api/docs

Example of a successful JSON response containing status metadata and earnings data records.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "earning_date": "2024-09-05",
      "stock_id": 25301,
      "market_cap": 4301367296,
      "time_of_day_code": "TNS",
      "estimate": 0.59,
      "reported_earning": 0.02
}
]

}
```

--------------------------------

### JSON Response Structure for Equity Info

Source: https://www.ivolatility.com/api/docs

Example of a successful 200 response containing status metadata and equity data records.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "Status": "Active",
      "Stock ticker": "A",
      "Company name": "Agilent Technologies Inc",
      "Exchange MIC": "XNYS",
      "Exchange name": "New York Stock Exchange",
      "Start date": "11/17/1999",
      "End date": null,
      "Region": "USA",
      "Security type": "S",
      "ISIN": "US00846U1016",
      "FIGI": "BBG000C2V3D6",
      "Options": "YES",
      "Opt exchange MIC": "AMXO",
      "Opt exchange name": "NYSE Amex Options",
      "Start opt date": "05/22/2000",
      "End opt date": null,
      "Dividend Convention": "regular dividends",
      "StockID": 9483,
      "BLMB ticker": "A Equity"
}
]

}
```

--------------------------------

### GET /equities/rt/options-rawiv

Source: https://www.ivolatility.com/api/docs

Retrieves realtime options data for a list of symbols.

```APIDOC
## GET /equities/rt/options-rawiv

### Description
Retrieves realtime options data, including National Best Bid and Offer (NBBO), open interest (OI), implied volatility (IV), and greeks. The NBBO is sourced from all exchanges.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/rt/options-rawiv

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **symbols** (Array of strings) - Required - Comma-separated list of options tickers (e.g., SPX 251219C04100000,SPX 251219P04100000)

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request identification details
- **data** (array) - List of options data records

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "symbol": "SPXW 211223P03890000",
      "iv": 0.207512,
      "timestamp": "2021-12-27T05:27:49.2660-0500"
    }
  ]
}
```

--------------------------------

### Import the ivolatility library

Source: https://www.ivolatility.com/api/docs

Import the library to begin using its functions.

```python
import ivolatility as ivol
```

--------------------------------

### Build a Black-Scholes-Merton options pricing engine

Source: https://www.ivolatility.com/api/docs

Requires the ivolatility library and QuantLib. Ensure API credentials are set before fetching market data.

```python
import pandas as pd 
import datetime
import QuantLib as ql
import matplotlib.pyplot as plt
from statistics import mean
import ivolatility as ivol

ivol.setLoginParams(apiKey={your_api_key})
# OR:
ivol.setLoginParams(username={your_IVol_username}, password={your_IVol_password})
period = 360
OTMpct = 20
optType = 'C'
date_str = '2022-06-30'
date = datetime.datetime.strptime(date_str, '%Y-%m-%d')

option_type = ql.Option.Call
calculation_date = ql.Date(date.day, date.month, date.year)
maturity_date = calculation_date + period

getMarketData = ivol.setMethod('/equities/eod/stock-prices')
spot_price = getMarketData(symbol='AAPL', from_=date_str, to=date_str).at[0, 'close']

getMarketData = ivol.setMethod('/equities/eod/ivs')
marketData = getMarketData(symbol='AAPL', from_=date_str, to=date_str)
marketData['period'] = pd.to_numeric(marketData['period'])
marketData = marketData.loc[(marketData['call/put'] == optType) & (marketData['out-of-the-money_%'] == OTMpct) & (marketData['period'] == period)]

strike_price = marketData['strike'].values[0]
volatility = marketData['iv'].values[0]
dividend_rate =  0.023
risk_free_rate = 0.001
day_count = ql.Actual365Fixed()
calendar = ql.UnitedStates()
ql.Settings.instance().evaluationDate = calculation_date
payoff = ql.PlainVanillaPayoff(option_type, strike_price)
settlement = calculation_date
am_exercise = ql.AmericanExercise(settlement, maturity_date)
american_option = ql.VanillaOption(payoff, am_exercise)
eu_exercise = ql.EuropeanExercise(maturity_date)
european_option = ql.VanillaOption(payoff, eu_exercise)
spot_handle = ql.QuoteHandle( ql.SimpleQuote(spot_price) )
flat_ts = ql.YieldTermStructureHandle( ql.FlatForward(calculation_date, risk_free_rate, day_count) )
dividend_yield = ql.YieldTermStructureHandle( ql.FlatForward(calculation_date, dividend_rate, day_count) )
flat_vol_ts = ql.BlackVolTermStructureHandle( ql.BlackConstantVol(calculation_date, calendar, volatility, day_count) )
bsm_process = ql.BlackScholesMertonProcess(spot_handle, dividend_yield, flat_ts, flat_vol_ts)

def binomial_price(option, process, steps):
  binomial_engine = ql.BinomialVanillaEngine(process, 'crr', steps)
  option.setPricingEngine(binomial_engine)
  return option.NPV()

steps = range(5, 200, 1)
eu_prices = [binomial_price(european_option, bsm_process, step) for step in steps]
am_prices = [binomial_price(american_option, bsm_process, step) for step in steps]

#theoretical European option price 
european_option.setPricingEngine(ql.AnalyticEuropeanEngine(bsm_process))
bsm_price = european_option.NPV()

print('BSM price:', bsm_price)
print('European option:', mean(eu_prices))
print('American option:', mean(am_prices))

plt.plot(steps, am_prices, label='American Option', lw=2, alpha=0.6)
plt.plot(steps, eu_prices, label='European Option', lw=2, alpha=0.6)
plt.plot([5,200],[bsm_price, bsm_price], 'r--', label='BlackScholesMerton', lw=2, alpha=0.6)
plt.xlabel('Steps')
plt.ylabel('Price')
plt.legend()
plt.show()
```

--------------------------------

### GET /equities/intraday/single-equity-optionsymbol-rawiv

Source: https://www.ivolatility.com/api/docs

Retrieves historical intraday data for a specific options contract.

```APIDOC
## GET /equities/intraday/single-equity-optionsymbol-rawiv

### Description
Retrieves 1-minute or n-minute interval historical data for the specified options contract, including NBBO, open interest, implied volatility, and greeks.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/intraday/single-equity-optionsymbol-rawiv

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **optionSymbol** (string) - Required - Example: SPY 211220P00235000
- **date** (string) - Required - Trading date (YYYY-MM-DD)
- **minuteType** (string) - Required - Enum: "MINUTE_1", "MINUTE_5", "MINUTE_15", "MINUTE_30", "HOUR", "CUSTOM"
- **minutes** (string) - Required (if minuteType is CUSTOM) - Comma-separated list of minutes within an hour (0–59)

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request tracking information
- **data** (array) - List of historical data points including timestamp, pricing, and greeks

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "timestamp": "2021-12-20 09:30:00",
      "optionSymbol": "SPY   211220P00235000",
      "optionIv": -1,
      "underlyingPrice": 454.63
    }
  ]
}
```

--------------------------------

### GET /equities/eod/ivs

Source: https://www.ivolatility.com/api/docs

Retrieves the Implied Volatility Surface for a specified underlying asset.

```APIDOC
## GET /equities/eod/ivs

### Description
Retrieves the Implied Volatility Surface (normalized by maturities and moneyness) for the underlying asset.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/eod/ivs

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **symbol** (string) - Optional - Equity ticker. One of `symbol` OR `stockID` is required.
- **stockID** (string) - Optional - Internal IVOL identifier. One of `symbol` OR `stockID` is required.
- **date** (string) - Optional - Trading Date. Parameters `from/to` OR `date` are required.
- **from** (string) - Optional - Trading Date. Parameters `from/to` OR `date` are required.
- **to** (string) - Optional - Trading Date. Parameters `from/to` OR `date` are required.
- **OTMFrom** (integer) - Optional - Lower OTM range limit.
- **OTMTo** (integer) - Optional - Upper OTM range limit.
- **periodFrom** (integer) - Optional - Lower tenor range limit.
- **periodTo** (integer) - Optional - Upper tenor range limit.
- **region** (string) - Optional - Default: "USA". Enum: "USA", "EUROPE", "ASIA", "CANADA", "RUSSIA", "CRYPTO", "LAT_AM"

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request identifier
- **data** (array) - List of volatility surface records

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "symbol": "AAPL",
      "exchange": "NASDAQ",
      "date": "2021-12-16 00:00:00",
      "period": 30,
      "strike": 172.26,
      "iv": 0.347413,
      "delta": 0.520221,
      "record_no": 1,
      "out-of-the-money_%": 0,
      "call/put": "C"
    }
  ]
}
```

--------------------------------

### Retrieve Equity Option Data via Python

Source: https://www.ivolatility.com/api/docs

Examples showing how to query the nearest option tickers using different parameter combinations like date ranges, moneyness, or delta.

```python
getMarketData = ivol.setMethod('/equities/eod/nearest-option-tickers-with-prices-nbbo')
marketData = getMarketData(symbol='TQQQ', startDate='2022-03-15', endDate='2022-03-30', dte=100, moneyness=5, cp='C')
marketData = getMarketData(symbol='TQQQ', from_='2022-03-15', to='2022-03-30', dte=100, moneyness=5, cp='C')
marketData = getMarketData(symbol='TQQQ', dte=100, delta=-.9, cp='P')
```

--------------------------------

### GET /equities/yield

Source: https://www.ivolatility.com/api/docs

Retrieves the 12-month average dividend yield of an equity index.

```APIDOC
## GET /equities/yield

### Description
Retrieves the 12-month average dividend yield of an equity index. This calculation is used in indexes' implied volatility calculations.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/yield

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **symbol** (string) - Required - Ticker symbol (e.g., SPXIndex)
- **region** (string) - Optional - Default: "USA". Enum: "USA", "EUROPE", "ASIA", "CANADA", "RUSSIA", "CRYPTO", "LAT_AM"

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request identification details
- **data** (array) - List of yield records containing calc_date, stock_id, t_date, and yield

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "calc_date": "2011-04-29",
      "stock_id": 9327,
      "t_date": "1989-12-29",
      "yield": 0.033718
    }
  ]
}
```

--------------------------------

### Retrieve Historical Earnings Data in Python

Source: https://www.ivolatility.com/api/docs

Demonstrates how to initialize the method and query the endpoint using different parameter combinations for dates and identifiers.

```python
getMarketData = ivol.setMethod('/equities/eod/history-earnings-calendar')
marketData = getMarketData(startDate='2022-08-10',endDate='2025-11-18',stockID='1350')
#OR:
marketData = getMarketData(from_='2022-08-10',to='2025-11-18',stockID='1350')
#OR:
marketData = getMarketData(startDate='2022-08-10',endDate='2025-11-18',symbols='META,AAPL')
#OR:
marketData = getMarketData(from_='2022-08-10',to='2025-11-18',symbols='META,AAPL')
```

--------------------------------

### GET /equities/rt/ivs

Source: https://www.ivolatility.com/api/docs

Retrieves the Implied Volatility Surface for the underlying asset in Live mode.

```APIDOC
## GET /equities/rt/ivs

### Description
Retrieves the Implied Volatility Surface (normalized by maturities and moneyness) for the underlying asset in Live mode.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/rt/ivs

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **symbols** (Array of strings) - Required - Equity tickers. Parameters `symbols` OR `stockGroup` are required.
- **stockGroup** (any) - Optional - Enum: "ALL_ETFS", "ALL_US_INDEXES", "ALL_US_STOCKS", "ALL_USA", "B3_STOCKS", "CAC_STOCKS", "CANADIAN_STOCKS", "DAX_STOCKS", "DJIA_STOCKS", "DJX", "EUROPIAN_STOCKS", "MSH_STOCKS", "NASDAQ_100_STOCKS", "NSE_STOCKS", "OEX_STOCKS", "OSX_STOCKS", "RUSSELL_2000_STOCKS", "SOX_STOCKS", "SP500_STOCKS", "SX5E", "TOP200_OPTIONS_OPEN_INTEREST", "TOP200_OPTIONS_VOLUME", "TX60", "USA_WEEKLIES". Parameters `symbols` OR `stockGroup` are required.
- **terms** (any) - Optional - Enum: "T7", "T14", "T21", "T30", "T60", "T90", "T120", "T150", "T180", "T270", "T360", "T720", "T1080"
- **otms** (any) - Optional - Enum: "V0", "V5", "V10", "V15", "V20", "V25", "V30", "V35", "V40", "V45", "V50", "V55", "V60"
- **callPut** (string) - Optional - Enum: "C", "P"
- **period** (string) - Optional - Enum: "MINUTES_1", "MINUTES_5", "MINUTES_15", "MINUTES_30", "HOURS_1", "HOURS_12", "DAYS_1", "DAYS_2", "DAYS_3". Data retrieval for a specified period to date.
- **from** (string) - Optional - Trading datetime.
- **to** (string) - Optional - Trading datetime.

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata.
- **query** (object) - Query request details.
- **data** (array) - List of volatility surface records.
```

--------------------------------

### Retrieve Nearest Option Tickers in Python

Source: https://www.ivolatility.com/api/docs

Examples showing how to query the endpoint using different parameter combinations for date ranges and filtering criteria.

```python
getMarketData = ivol.setMethod('/equities/eod/nearest-option-tickers-with-prices')
marketData = getMarketData(symbol='TQQQ', startDate='2022-03-15', endDate='2022-03-30', dte=100, moneyness=5, cp='C')
#OR:
marketData = getMarketData(symbol='TQQQ', from_='2022-03-15', to='2022-03-30', dte=100, moneyness=5, cp='C')
#OR:
marketData = getMarketData(symbol='BMW', dte=100, delta=-.9, cp='P', region='EUROPE')
```

--------------------------------

### GET /data/download/{ruid}

Source: https://www.ivolatility.com/api/docs

Downloads the GZIP-compressed CSV file for a completed export job.

```APIDOC
## GET /data/download/{ruid}

### Description
Downloads the generated GZIP-compressed CSV file. If the file is still compiling, the server returns HTTP 204 No Content.

### Method
GET

### Endpoint
/data/download/{ruid}

### Parameters
#### Path Parameters
- **ruid** (string) - Required - The unique request UUID for the export job.

### Response
#### Success Response (200)
- **Content-Type** (application/octet-stream) - The GZIP-compressed CSV file.

#### Error Response (204)
- **No Content** - The file is still being compiled; retry after a short delay.
```

--------------------------------

### Retrieve EOD Futures Options Data via Python SDK

Source: https://www.ivolatility.com/api/docs

Examples showing how to query market data using either moneyness or delta parameters. Note that delta takes precedence over moneyness if both are provided.

```python
getMarketData = ivol.setMethod('/futures/eod/fut-opts-by-param')
marketData = getMarketData(underlyingSymbol='MIX',tradeDate='2023-11-09',dteFrom=0,dteTo=30,moneynessFrom=-50,moneynessTo=-10,cp='P',region='EUROPE')
marketData = getMarketData(underlyingSymbol='ES',tradeDate='2023-11-09',dteFrom=0,dteTo=30,deltaFrom=0.5,deltaTo=0.8,cp='C')
```

--------------------------------

### Retrieve Equity Options Data via Python

Source: https://www.ivolatility.com/api/docs

Example of using the ivol library to fetch market data for a specific symbol and date range.

```python
getMarketData = ivol.setMethod('/equities/eod/stock-opts-by-param-1545')
marketData = getMarketData(symbol='AAPL',tradeDate='2021-12-16',dteFrom=0,dteTo=30,moneynessFrom=-10,moneynessTo=100,cp='C')
```

--------------------------------

### GET /equities/eod/nearest-option-tickers

Source: https://www.ivolatility.com/api/docs

Retrieves the two nearest results according to delta or moneyness for the selected date.

```APIDOC
## GET /equities/eod/nearest-option-tickers

### Description
Retrieves the two nearest results according to delta (or moneyness in % terms) options tickers and days to expiration for the selected date. These tickers can then be used to request option prices through other endpoints.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/eod/nearest-option-tickers

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **dte** (integer) - Required - Days to expiration, i.e. expiration_date - current_date
- **symbol** (string) - Required (if stockID not provided) - Equity ticker
- **stockID** (string) - Required (if symbol not provided) - Internal IVOL identifier
- **startingDate** (string) - Optional - Starting date from which to calculate the days to expiration (default: current date)
- **moneyness** (integer) - Optional - Equity option's moneyness
- **delta** (number) - Optional - Equity option's delta
- **callPut** (string) - Optional - Call (C) or Put (P)
- **region** (string) - Optional - Region (default: USA)

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request identifier
- **data** (array) - List of option results

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "option_id": 112114441,
      "option_symbol": "TQQQ  220617C00041250",
      "comment": "Stock split event on '20220113', factor = 2"
    }
  ]
}
```

--------------------------------

### Retrieve Market Data via Python SDK

Source: https://www.ivolatility.com/api/docs

Example usage of the Python client to fetch market data for a specific stock group and date range.

```python
getMarketData = ivol.setMethod('/equities/stock-market-data')
marketData = getMarketData(stockGroup='ALL_USA', from=2025-12-14, to=2025-12-15)
```

--------------------------------

### GET /equities/eod/earnings

Source: https://www.ivolatility.com/api/docs

Retrieves an earnings calendar with estimates and trading opportunities for specified US equities.

```APIDOC
## GET /equities/eod/earnings

### Description
Retrieves an earnings calendar with estimates of earnings and trading opportunities using various strategies (straddle, strangle, IVX) and probabilities of winning. Historical data for two quarters is also available.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/eod/earnings

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **symbols** (Array of strings) - Required (if stockGroup not provided) - Equity tickers separated by commas
- **from** (string) - Optional - Min earning date (e.g., 2024-08-20)
- **to** (string) - Optional - Max earning date (e.g., 2024-12-30)
- **quarter** (string) - Optional - Enum: "Q1", "Q2", "ALL". If not provided, historical data is not returned.
- **strategy** (string) - Optional - Enum: "STRADDLE", "STRANGLE_VOL", "STRANGLE_OI", "IVX". If not provided, all strategies are returned.
- **period** (string) - Optional - Enum: "D7", "D3", "D1". If not provided, all periods are returned.
- **stockGroup** (any) - Required (if symbols not provided) - Enum: "ALL_ETFS", "ALL_US_INDEXES", "ALL_US_STOCKS", "ALL_USA", "B3_STOCKS", "CAC_STOCKS", "CANADIAN_STOCKS", "DAX_STOCKS", "DJIA_STOCKS", "DJX", "EUROPIAN_STOCKS", "MSH_STOCKS", "NASDAQ_100_STOCKS", "NSE_STOCKS", "OEX_STOCKS", "OSX_STOCKS", "RUSSELL_2000_STOCKS", "SOX_STOCKS", "SP500_STOCKS", "SX5E", "TOP200_OPTIONS_OPEN_INTEREST", "TOP200_OPTIONS_VOLUME", "TX60", "USA_WEEKLIES"

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata
- **query** (object) - Request identifier
- **data** (array) - List of earnings and strategy data records

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "ticker": "FIZZ",
      "earning_date": "2024-09-05",
      "estimate": 0.59
    }
  ]
}
```

--------------------------------

### GET /equities/eod/stock-prices

Source: https://www.ivolatility.com/api/docs

Retrieves historical EOD price and volume data for a requested financial instrument.

```APIDOC
## GET /equities/eod/stock-prices

### Description
Retrieves historical EOD price and volume data for the requested financial instrument, such as a stock or ETF.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/eod/stock-prices

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **region** (string) - Optional - Default: "USA". Enum: "USA", "EUROPE", "ASIA", "CANADA", "RUSSIA", "CRYPTO", "LAT_AM"
- **symbol** (string) - Required (if stockID not provided) - Equity ticker
- **stockID** (string) - Required (if symbol not provided) - Internal IVOL identifier
- **date** (string) - Required (if from/to not provided) - Trading Date
- **from** (string) - Required (if date not provided) - Start date for range
- **to** (string) - Required (if date not provided) - End date for range

### Response
#### Success Response (200)
- **status** (object) - Execution metadata and status
- **query** (object) - Request identifier
- **data** (array) - List of price records

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "date": "2021-12-16 00:00:00",
      "symbol": "AAPL",
      "exchange": "NASDAQ",
      "open": 179.28,
      "high": 181.14,
      "low": 170.75,
      "close": 172.26,
      "volume": 149421718
    }
  ]
}
```

--------------------------------

### GET /equities/stock-market-data

Source: https://www.ivolatility.com/api/docs

Retrieves end-of-day market summary data for specified equities, groups, or IDs.

```APIDOC
## GET /equities/stock-market-data

### Description
Provides a complete snapshot of equity market conditions including stock prices, options metrics, volatility indicators (IVX, HV), Greeks, correlations, and fundamental data.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/stock-market-data

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **from** (string) - Required - Trading date (e.g., 2023-11-07)
- **to** (string) - Required - Trading date (e.g., 2023-11-08)
- **symbols** (Array of strings) - Required* - Equity tickers separated by commas.
- **stockID** (Array of strings) - Required* - Internal IVOL identifiers separated by commas.
- **stockGroup** (enum) - Required* - Group identifier (e.g., "ALL_USA", "SP500_STOCKS").
- **columns** (string) - Optional - Specific columns to return, separated by commas.

*Note: Parameters `symbols` OR `stockID` OR `stockGroup` are required.

### Response
#### Success Response (200)
- **status** (object) - Execution status and metadata.
- **query** (object) - Request identifier.
- **data** (array) - List of market data records.

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "tradeDate": "2023-11-09",
      "stockId": 7331,
      "symbol": "FIX",
      "companyName": "Comfort Systems USA Inc"
    }
  ]
}
```

--------------------------------

### Retrieve EOD Equities IV Surface in Python

Source: https://www.ivolatility.com/api/docs

Examples showing how to fetch market data using either a specific date or a date range.

```python
getMarketData = ivol.setMethod('/equities/eod/ivs')
marketData = getMarketData(symbol='AAPL', date='2021-12-16')
marketData = getMarketData(symbol='AAPL', from_='2021-12-10', to='2021-12-17')
```

--------------------------------

### GET /equities/trading-calendar

Source: https://www.ivolatility.com/api/docs

Retrieves US market trading calendar information for a specified date range.

```APIDOC
## GET /equities/trading-calendar

### Description
This endpoint returns US market trading calendar information. Use either 'from'/'to' or 'startDate'/'endDate' parameters, but do not combine them.

### Method
GET

### Endpoint
https://restapi.ivolatility.com/equities/trading-calendar

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - REST API apiKey
- **from** (string) - Required - Start date of the range (e.g., 2025-01-01)
- **to** (string) - Required - End date of the range (e.g., 2030-12-31)
- **startDate** (string) - Required - Start date of the range
- **endDate** (string) - Required - End date of the range

### Response
#### Success Response (200)
- **status** (object) - Contains executionTime, recordsFound, code, urlForDetails, and message
- **query** (object) - Contains requestUUID
- **data** (array) - List of calendar entries containing calendarDate, dayOfTheWeek, and dayType

#### Response Example
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found."
  },
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
  },
  "data": [
    {
      "calendarDate": "2024-11-08",
      "dayOfTheWeek": "Wednesday",
      "dayType": "USA - New Year's Day"
    }
  ]
}
```

--------------------------------

### GET /token/get

Source: https://www.ivolatility.com/api/docs

Retrieves a bearer token for API authentication. The session expires after 30 minutes.

```APIDOC
## GET /token/get

### Description
Retrieves a bearer token for API authentication. The session expires after 30 minutes, requiring a new token to be requested.

### Method
GET

### Endpoint
/token/get
```

--------------------------------

### Implement Countertrend Trading Strategy

Source: https://www.ivolatility.com/api/docs

Uses the IVolatility API to fetch historical daily stock prices and calculate PnL based on a simple countertrend logic. Requires the ivolatility library and valid API credentials.

```python
#Entry:  If the previous day's closing candle was positive, sell at the next day's open; 
#        and vice versa. If candle was unchanged, do nothing.
#Exit:   Place closing order at EOD.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import ivolatility as ivol

ivol.setLoginParams(apiKey={your_api_key})
# OR:
ivol.setLoginParams(username={your_IVol_username}, password={your_IVol_password})
#______________________________________________________________________________
#Test trading strategy on SPX's daily data for 1980-2021.

getMarketData = ivol.setMethod('/equities/eod/stock-prices')
marketData = getMarketData(symbol='SPX', from_='1980-01-01', to='2021-12-31')

marketData['date'] = pd.to_datetime(marketData['date'])
marketData = marketData.sort_values(by='date')

pnl_df = pd.DataFrame(columns=['date', 'day_pnl', 'total_pnl'])
date_col = marketData.columns.get_loc('date')
open_col = marketData.columns.get_loc('open')
close_col = marketData.columns.get_loc('close')

pnl = 0
loc = 0
for i in range(marketData.shape[0]-1):
  currentTrade = -np.sign(marketData.iat[i, close_col] - marketData.iat[i, open_col]) * marketData.iat[i+1, open_col]
  if currentTrade == 0:
    continue
  currentTrade = np.sign(currentTrade)*marketData.iat[i+1, close_col] - currentTrade
  pnl += currentTrade
  pnl_df.loc[loc] = [marketData.iat[i+1, date_col], currentTrade, pnl]
  loc += 1

pnl_df.plot(title='SPX', x='date', y='total_pnl', kind='line')
plt.show()
```

--------------------------------

### Example JSON Response

Source: https://www.ivolatility.com/api/docs

Sample structure of a successful API response. Note that large datasets may return a status code of PENDING with a download URL.

```json
{
  "status": {
    "executionTime": 1772,
    "recordsFound": 234,
    "code": "PENDING",
    "urlForDetails": "https://restapi.ivolatility.com/data/info/B2FC976D-7AB4-41B4-ADDD-89460B67E5C8",
    "message": "More than 500 records found. The full result is not returned inline — download it from the link in the 'urlForDetails' field."
},
  "query": {
    "requestUUID": "B2FC976D-7AB4-41B4-ADDD-89460B67E5C8"
},
  "data": [
    {
      "date": "2023-11-06",
      "symbol": "IS0R",
      "yield": 0.9786679,
      "stock_id": 25301,
      "expiration_date": "2023-11-17",
      "calc_date": "2023-11-06"
}
]

}
```
Tokens:
Raw