OpenBB/website/content/sdk/data-available/stocks/options-chains.md

title, description, keywords

title	description	keywords
Options Chains	A technical guide detailing how to load options chains data from six different sources into memory using openbb. Reviews how to properly filter, sort, and analyze this kind of data, and outlines the process for implementing various options strategies. This document is heavily focused on technical processes within a financial context.	Options Chains Data Option Strategies Financial Data Data Filtering Data Sorting Data Visualization

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

Overview

Options Data Object

Options chains data is loaded to memory by using the function, openbb.stocks.options.load_options_chains(), and is available from six sources:

• CBOE
• Intrinio (no free data)
• Nasdaq
• TMX
• Tradier (requires Sandbox developer key)
• YahooFinance

Every source will return the same object which has data and additional callable functions bound to the class. They are methods for filtering, sorting, and analyzing the data contained within.

from openbb_terminal.sdk import openbb
openbb.stocks.options.load_options_chains?

Parameters
----------
symbol: str
    The ticker symbol to load the data for.
source: str
    The source for the data. Defaults to "CBOE". ["CBOE", "Intrinio", "Nasdaq", "TMX", "Tradier", "YahooFinance"]
date: str
    The date for EOD chains data.  Only available for "Intrinio" and "TMX".
pydantic: bool
    Whether to return as a Pydantic Model or as a Pandas object.  Defaults to False.

Returns
------
OptionsChains
    chains: pd.DataFrame
        The complete options chain for the ticker. Returns as a dictionary if pydantic is True.
    expirations: list[str]
        List of unique expiration dates. (YYYY-MM-DD)
    strikes: list[float]
        List of unique strike prices.
    last_price: float
        The last price of the underlying asset.
    underlying_name: str
        The name of the underlying asset.
    underlying_price: pd.Series
        The price and recent performance of the underlying asset. Returns as a dictionary if pydantic is True.
    hasIV: bool
        Returns implied volatility.
    hasGreeks: bool
        Returns greeks data.
    symbol: str
        The symbol entered by the user.
    source: str
        The source of the data.
    date: str
        The date, when the chains data is historical EOD.
    SYMBOLS: pd.DataFrame
        The symbol directory for the source, when available. Returns as a dictionary if pydantic is True.

    Methods
    ------
    chart_skew: Callable
        Function to chart the implied volatility skew.
    chart_stats: Callable
        Function to chart a variety of volume and open interest statistics.
    chart_surface: Callable
        Function to chart the volatility as a 3-D surface.
    chart_volatility: Callable
        Function to chart the implied volatility smile.
    get_skew: Callable
        Function to calculate horizontal and vertical skewness.
    get_stats: Callable
        Function to return a table of summary statistics, by strike or by expiration.
    get_straddle: Callable
        Function to calculate straddles and the payoff profile.
    get_strangle: Callable
        Function to calculate strangles and the payoff profile.
    get_synthetic_long: Callable
        Function to calculate a synthetic long position.
    get_synthetic_short: Callable
        Function to calculate a synthetic short position.
    get_vertical_call_spread: Callable
        Function to calculate vertical call spreads.
    get_vertical_put_spreads: Callable
        Function to calculate vertical put spreads.
    get_strategies: Callable
        Function for calculating multiple straddles and strangles at different expirations and moneyness.

Loading Data

load_options_chains()

The default source to load data from is, CBOE. Use the command below to get started.

from openbb_terminal.sdk import openbb
spy = openbb.stocks.options.load_options_chains("SPY")

The result is returned as the object described in the previous section.

The object is still returned if an unsupported symbol is requested and a message will be printed.

In [4]: data = openbb.stocks.options.load_options_chains("spyyy")
The symbol, SPYYY, was not found in the CBOE directory.

In [5]: data.chains
Out[5]: pandas.core.frame.DataFrame

Where available, symbols are verified against a source-specific symbol directory. This is accessible from the Options data object as the attribute named, SYMBOLS.

data.SYMBOLS.filter(like = "SPY", axis = 0)

Symbol	Company Name	DPM Name	Post/Station
SPY	SPDR S&P 500 ETF TR TR UNIT	Morgan Stanley & Co. LLC	8/1
SPYG	SPDR SER TR PRTFLO S&P500 GW	Belvedere Trading LLC	6/1
SPYD	SPDR SER TR PRTFLO S&P500 HI	Citadel Securities LLC	6/1
SPYV	SPDR SER TR PRTFLO S&P500 VL	Belvedere Trading LLC	6/1
NSPY	UNIFIED SER TR NIGHTSHARES 500	Wolverine Trading, LLC	3/1

:::note A valid symbol will not always have listed options. :::

Key information for the underlying asset are stored in the object as last_price, underlying_name, and underlying_price. The information returned to underlying_price will vary by source, but all column headers and index names related to the raw data are formatted in camelCase.

CBOE:

In [7]: data.underlying_price
Out[7]:
type                                 stock
tick                                  down
bid                                 449.18
bidSize                                  1
askSize                                  5
ask                                  449.2
price                               449.28
open                                450.56
high                                451.36
low                                 448.49
close                               449.28
volume                            69772484
previousClose                       449.28
change                               -0.28
changePercent                      -0.0623
ivThirty                            10.947
ivThirtyChange                         0.0
lastTradeTimestamp     2023-07-14T16:00:00
ivThirtyOneYearHigh              30.646999
hvThirtyOneYearHigh              30.648199
ivThirtyOneYearLow                  10.692
hvThirtyOneYearLow                 10.0721
ivSixtyOneYearHigh               28.674999
hvSixtyOneYearHigh                 29.5842
ivSixtyOneYearLow                   11.245
hvsixtyOneYearLow                   11.833
ivNinetyOneYearHigh                 27.862
hvNinetyOneYearHigh              26.808901
ivNinetyOneYearLow                  11.827
hvNinetyOneYearLow                 13.3855
Name: SPY, dtype: object

TMX:

In [8]: data = openbb.stocks.options.load_options_chains("XIU", "TMX")

In [9]: data.underlying_price
Out[9]:
time                15:59:56.910
previousClose              30.86
transactions                 393
volume                     50751
value                    1567628
valueCAD                 1567628
open                       30.97
price                      30.85
change                     -0.01
changePercent              -0.03
tick                        0.01
low                       30.835
high                       30.97
vwap                       30.89
fiftyTwoWeekHigh           31.86
fiftyTwoWeekLow           27.375
Name: XIU, dtype: object

Not every source will return implied volatility or Greeks data. The two object attributes, hasGreeks and hasIV, act as validators for downstream functions.

In [10]: data.hasIV
Out[10]: False

In [11]: data.get_skew()
Options data object does not have Implied Volatility and is required for this function.

Historical EOD Chains

Historical EOD chains data is currently available from Intrinio or TMX. The amount of historical data will depend on the subscription status with Intrinio, but is available from the beginning of 2009 from TMX. Add the date argument when loading the data. The price data of the underlying asset will reflect the closing price on the date entered.

In [12]: data = openbb.stocks.options.load_options_chains("CCO", "TMX", date = "2016-06-29")

In [13]: data.underlying_price
Out[13]:
date             2016-06-29
bid                   13.99
ask                   14.01
bidSize                  29
askSize                  20
price                  14.0
volume               801176
previousClose         13.73
change                 0.27
open                  13.88
high                  14.09
low                    13.8
valueCAD           11198995
transactions           3283
symbol                  CCO
Name: Cameco Corporation, dtype: object

Additional Class Methods

The class methods work with the Options data object to query the loaded chains data in different ways. Column headers at this stage are cleaned and presentable for view. There are two types of operations, get and chart, with the latter being a subset of the former. The docstring (data? - and as shown in a section above) lists them all, as Methods, with a short description. The nuances of the functions are explained within the docstrings of each. Variations to the combinations of parameters will yield over thirty unique charts and provide nearly infinite ways to query to data stored in the object.

:::note

All chart_ methods have boolean arguments for raw and external_axes. These return an interactive table in the PyWry window or the Plotly figure object, respectively. In a Jupyter Notebook, they will be displayed inline.

Returning the command to a variable provides the ability to style and customize charts as desired.

fig = data.chart_volatility(expirations=data.expirations[1], external_axes = True)

:::

get_stats()

Parameters
----------
by: str
    Whether to calculate by strike or expiration.  Default is expiration.
query: DataFrame
    Entry point to perform DataFrame operations on self.chains at the input stage.

Returns
-------
pd.DataFrame
    Pandas DataFrame with the calculated statistics.

Ratios are defined as Put/Call.

data = openbb.stocks.options.load_options_chains("VIX")
data.get_stats().iloc[1]

	2023-07-26
Puts OI	2018
Calls OI	45875
Total OI	47893
OI Ratio	0.04
Puts OTM	873
Calls OTM	45747
Puts ITM	1145
Calls ITM	128
OTM Ratio	0.02
ITM Percent	2.66
Puts Volume	264
Calls Volume	2156
Total Volume	2420
Volume Ratio	0.12
Vol-OI Ratio	0.05

The query parameter provides an entry point for DataFrame operations to take place prior to calculating. For example, filtering for only the options which traded during the last session.

data.get_stats(query = data.chains[vix.chains["lastTradeTimestamp"] > "2023-07-14"])

Expiration	Puts OI	Calls OI	Total OI	OI Ratio	Puts Volume	Calls Volume	Total Volume	Volume Ratio	Vol-OI Ratio
2023-07-19	1569778	3323396	4893174	0.47	113460	130416	243876	0.87	0.05
2023-07-26	1855	29273	31128	0.06	264	2156	2420	0.12	0.08
2023-08-02	1154	2498	3652	0.46	12	786	798	0.02	0.22
2023-08-09	330	961	1291	0.34	43	354	397	0.12	0.31
2023-08-16	907980	2246707	3154687	0.4	48668	197148	245816	0.25	0.08
2023-08-23	0	49	49	0	7	145	152	0.05	3.1
2023-09-20	614369	2097742	2712111	0.29	20750	19260	40010	1.08	0.01
2023-10-18	165239	1099858	1265097	0.15	3304	14912	18216	0.22	0.01
2023-11-15	70142	742698	812840	0.09	82	514	596	0.16	0
2023-12-20	44580	259815	304395	0.17	10797	12471	23268	0.87	0.08
2024-01-17	20860	43733	64593	0.48	23574	23690	47264	1	0.73
2024-02-14	1347	6567	7914	0.21	67	203	270	0.33	0.03
2024-03-20	63	1861	1924	0.03	8	219	227	0.04	0.12

chart_stats()

The volume and open interest metrics can be visualized in a number of ways. In general, they are bucketed as volume and open interest by strike or expiration.

data.chart_stats()

data.chart_stats(by="strike", oi=True)

data.chart_stats(by="strike", oi=True, percent=False)

data.chart_stats(ratios=True)

Options Strategies

These methods calculate common, single-leg, strategies and return one result. The target expiry date is expressed as the number of days until expiration, and the closest expiry to supplied value will be returned. There are six types of strategies currently supported:

• get_straddle()
• get_strangle()
• get_synthetic_long()
• get_synthetic_short()
• get_vertical_call_spread()
• get_vertical_put_spread()

:::note

Looking for a place to get started as a contributor, and enjoy trading options? Strategies are an excellent starting point!

:::

All strategies share a common default setting, days=30. Vertical spreads require two strike prices, and they are entered as sold, bought. A bull call or put spread is entered with a bought price lower than the sold price.

data.get_vertical_call_spread(30,13,12.50)

	Bull Call Spread
Symbol	VIX
Underlying Price	13.34
Expiration	2023-08-16
DTE	31
Strike 1	13.0
Strike 2	12.5
Strike 1 Premium	2.9
Strike 2 Premium	3.4
Cost	0.5
Cost Percent	3.7481
Breakeven Lower	13.0
Breakeven Lower Percent	-2.5487
Breakeven Upper	nan
Breakeven Upper Percent	nan
Max Profit	0.0
Max Loss	-0.5
Payoff Ratio	0.0

data.get_vertical_put_spread(30,13,12.5)

	Bull Put Spread
Symbol	VIX
Underlying Price	13.34
Expiration	2023-08-16
DTE	31
Strike 1	13.0
Strike 2	12.5
Strike 1 Premium	-0.17
Strike 2 Premium	0.12
Cost	-0.05
Cost Percent	0.3748
Breakeven Lower	nan
Breakeven Lower Percent	nan
Breakeven Upper	12.95
Breakeven Upper Percent	2.92
Max Profit	0.05
Max Loss	-0.45
Payoff Ratio	0.1111

get_strategies()

This takes all of the individual strategies and combines them into a single endpoint that can iterate over all expiry dates.

data.get_strategies(days = 30, straddle_strike = data.last_price, strangle_moneyness = 30, vertical_calls = [20,15], vertical_puts = [12,15], synthetic_longs = 16, synthetic_shrots = 14)

	2023-08-16	2023-08-16	2023-08-16	2023-08-16	2023-08-16	2023-08-16
DTE	31	31	31	31	31	31
Strategy	Long Straddle	Long Strangle	Synthetic Long	Synthetic Short	Bull Call Spread	Bear Put Spread
Underlying Price	13.34	13.34	13.34	13.34	13.34	13.34
Strike 1	13.5	17.0	14.0	16.0	20.0	12.0
Strike 2	13.5	10.0	14.0	16.0	15.0	15.0
Strike 1 Premium	2.62	1.28	2.31	-1.46	-0.83	-0.04
Strike 2 Premium	0.33	0.01	-0.49	1.74	1.83	1.04
Cost	2.95	1.29	1.82	0.28	1.0	1.0
Cost Percent	22.1139	9.6702	13.6432	2.099	7.4963	7.4963
Breakeven Upper	16.45	18.29	15.82	nan	nan	nan
Breakeven Upper Percent	23.3133	37.1064	18.5907	nan	nan	nan
Breakeven Lower	10.55	8.71	nan	15.72	16.0	14.0
Breakeven Lower Percent	-20.9145	-34.7076	nan	17.8411	19.94	17.5412
Max Profit	inf	inf	inf	15.72	4.0	2.0
Max Loss	-2.95	-1.29	-15.82	inf	-1.0	-1.0
Payoff Ratio	inf	inf	nan	nan	4.0	2.0

The default state of get_strategies() is to return all ATM straddles. This information can be useful for charting the term structure and expected move of the underlying asset.

Volatility

There are two types of views for volatility, smiles and surfaces.

chart_volatility()

As a default state, the put and call volatility smiles from the expiration in position 1, contained in the list data.expirations[1], are displayed.

data.chart_volatility()

The implied volatility can also be visualized as the forward curve at a specific strike or % moneyness.

data.chart_volatility(strike=20)

data.chart_volatility(moneyness=30)

chart_surface()

A portion, or the entire, volatility surface is presented as a 3-D chart. The data is arranged by types, selectable with the option_type parameter, choosing one of: otm, itm, calls, puts. The default state is otm. The X and Y axes can be narrowed to focus on a range of time and strike.

data.chart_surface(dte_range = [30,300], strike_range = [10,30])

Skew

Unlike volatility, there are both model and view components for the IV skew of the chain.

get_skew()

By default, this callable calculates the skew of every option. It can return either vertical or horizontal skew. Vertical skew can be narrowed to a specific expiry, and horizontal skew is determined by % OTM.

data.get_skew(data.expirations[1]).query("12 <= `Strike` <= 15")

	Expiration	Strike	Option Type	IV	ATM IV	Skew
116	2023-07-26	12	put	1.1136	0.9283	0.1853
117	2023-07-26	12.5	put	1.0246	0.9283	0.0963
118	2023-07-26	13	put	0.9666	0.9283	0.0383
119	2023-07-26	13.5	put	0.9283	0.9283	0
120	2023-07-26	14	call	0.4994	0.4994	0
121	2023-07-26	14	put	0.8702	0.9283	-0.0581
122	2023-07-26	14.5	call	0.6156	0.4994	0.1162
123	2023-07-26	14.5	put	0.8899	0.9283	-0.0384
124	2023-07-26	15	call	0.6245	0.4994	0.1251
125	2023-07-26	15	put	0.9002	0.9283	-0.0281

vix.get_skew(moneyness=20)

expiration	Call Strike	Call IV	Call ATM IV	Call Skew	Put Strike	Put IV	Put ATM IV	Put Skew	ATM Skew	IV Skew
2023-07-19	16	1.0996	0.599	0.5006	10.5	1.0505	0.6328	0.4177	-0.0338	0.0829
2023-07-26	16	0.8708	0.4994	0.3714	10.5	0.9101	0.9283	-0.0182	-0.4289	0.3896
2023-08-02	16	0.855	0.5026	0.3524	10.5	0.7438	0.6755	0.0683	-0.1729	0.2841
2023-08-09	16	0.7861	0.4926	0.2935	10.5	0.6712	0.6575	0.0137	-0.1649	0.2798
2023-08-16	16	0.8364	0.6284	0.208	10.5	0.6041	0.6117	-0.0076	0.0167	0.2156
2023-08-23	16	0.9273	0.8918	0.0355	10.5	0.5492	0.6356	-0.0864	0.2562	0.1219
2023-09-20	16	0.7023	0.5481	0.1542	10	0.5344	0.548	-0.0136	0.0001	0.1678
2023-10-18	16	0.6447	0.5183	0.1264	10	0.4751	0.5178	-0.0427	0.0005	0.1691
2023-11-15	16	0.6064	0.5069	0.0995	10	0.4548	0.4947	-0.0399	0.0122	0.1394
2023-12-20	16	0.5716	0.4754	0.0962	10	0.426	0.4734	-0.0474	0.002	0.1436
2024-01-17	16	0.5224	0.4248	0.0976	10	0.4372	0.4372	0	-0.0124	0.0976
2024-02-14	16	0.494	0.4228	0.0712	10	0.4136	0.4258	-0.0122	-0.003	0.0834
2024-03-20	16	0.4533	0.4008	0.0525	10	0.4665	0.4162	0.0503	-0.0154	0.0022

chart_skew()

As a default state, the put and call skew smiles from the expiration in position 1, contained in the list data.expirations[1], are displayed.

data.chart_skew()

Multiple expirations can be displayed by entering a list to the expirations parameter.

data.chart_skew(expirations=[data.expirations[6],data.expirations[10]])

The forward curve is also callable by strike.

data.chart_skew(strike = 20)