Object: ggOptionChain

Overview

The ggOptionChain object contains the complete options chain for an underlying asset, providing access to 1-minute and 5-minute interval data. This object serves as a comprehensive container for options market data, including puts and calls across various strike prices and expiration dates.

Data Structure

The object follows a structured hierarchical format that organizes options data by:

Expiration dates
Strike prices
Option types (calls and puts)

Each option contract contains detailed pricing information, Greeks, and other relevant metrics that update at regular intervals based on market activity.

Schema

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "StockOptionsProfile",
  "description": "Describes stock options, including historical data organized by timestamps.",
  "type": "object",
  "properties": {
    "symbol": {
      "description": "Underlying stock's ticker symbol.",
      "type": "string"
    },
    "optionType": {
      "description": "Type of the option (call or put).",
      "type": "string",
      "enum": ["call", "put"]
    },
    "strikePrice": {
      "description": "Strike price of the option.",
      "type": "number"
    },
    "expirationDate": {
      "description": "Expiration date of the option.",
      "type": "string",
      "format": "date"
    },
    "historicalData": {
      "description": "Dictionary of historical data for the option, keyed by timestamps.",
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "oneMinute": {
            "description": "1-minute candle data.",
            "type": "object",
            "properties": {
              "open": { "type": "number" },
              "high": { "type": "number" },
              "low": { "type": "number" },
              "close": { "type": "number" },
              "volume": { "type": "integer", "minimum": 0 }
            },
            "required": ["open", "high", "low", "close", "volume"]
          },
          "fiveMinute": {
            "description": "Optional 5-minute candle data.",
            "type": "object",
            "properties": {
              "open": { "type": "number" },
              "high": { "type": "number" },
              "low": { "type": "number" },
              "close": { "type": "number" },
              "volume": { "type": "integer", "minimum": 0 }
            },
            "required": ["open", "high", "low", "close", "volume"]
          }
        },
        "required": ["oneMinute"]
      }
    }
  },
  "required": ["symbol", "optionType", "strikePrice", "expirationDate", "historicalData"]
}

YANG Schema

module stock-options-profile {
  namespace "http://example.com/stock-options-profile";
  prefix sop;

  organization "Example Organization";
  description "Describes the options for a stock, including historical data keyed by timestamps.";

  container stockOptionsProfile {
    leaf symbol {
      type string;
      description "Underlying stock's ticker symbol.";
    }

    leaf optionType {
      type enumeration {
        enum call {
          description "Call option.";
        }
        enum put {
          description "Put option.";
        }
      }
      description "Type of the option (call or put).";
    }

    leaf strikePrice {
      type decimal64 {
        fraction-digits 2;
      }
      description "Strike price of the option.";
    }

    leaf expirationDate {
      type string;
      description "Expiration date of the option.";
    }

    container historicalData {
      description "Dictionary of historical data for the option, keyed by timestamps.";

      list candleData {
        key "timestamp";
        leaf timestamp {
          type string;
          description "Timestamp marking the beginning of the historical data point.";
        }

        container oneMinute {
          description "1-minute candle data.";
          leaf open {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf high {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf low {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf close {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf volume {
            type uint64;
            description "Volume of options traded.";
          }
        }

        container fiveMinute {
          description "Optional 5-minute candle data.";
          leaf open {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf high {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf low {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf close {
            type decimal64 {
              fraction-digits 2;
            }
          }
          leaf volume {
            type uint64;
            description "Volume of options traded.";
          }
        }
      }
    }
  }
}

Key Properties

The ggOptionChain object includes the following key components:

Property	Description	Example
`symbol`	The underlying stock's ticker symbol	`"AAPL"`
`putExpDateMap`	A nested map of put options organized by expiration date and strike price	See example below
`callExpDateMap`	A nested map of call options organized by expiration date and strike price	See example below
`underlyingPrice`	The current price of the underlying asset	`153.8`
`volatility`	The implied volatility measure	`29.0`
`daysToExpiration`	Number of days until the option contract expires	`3`
`interestRate`	The current interest rate used in pricing models	`5.008`
`numberOfContracts`	Total number of contracts in the chain	`2202`

Example Data

Here's a portion of actual option chain data for Apple (AAPL):

{
  "symbol": "AAPL",
  "status": "SUCCESS",
  "underlying": null,
  "strategy": "SINGLE",
  "interval": 0.0,
  "isDelayed": false,
  "isIndex": false,
  "interestRate": 5.008,
  "underlyingPrice": 153.8,
  "volatility": 29.0,
  "daysToExpiration": 0.0,
  "numberOfContracts": 2202
}

Put Option Example

Here's an example of a specific put option from the chain (AAPL $150 Put expiring March 10, 2023):

{
  "putCall": "PUT",
  "symbol": "AAPL_031023P150",
  "description": "AAPL Mar 10 2023 150 Put (Weekly)",
  "exchangeName": "OPR",
  "bid": 0.6,
  "ask": 0.6,
  "last": 0.6,
  "mark": 0.6,
  "bidSize": 1,
  "askSize": 5,
  "bidAskSize": "1X5",
  "lastSize": 0,
  "highPrice": 0.62,
  "lowPrice": 0.6,
  "openPrice": 0.0,
  "closePrice": 0.6,
  "totalVolume": 42,
  "tradeDate": null,
  "tradeTimeInLong": 1678199401600,
  "quoteTimeInLong": 1678199403152,
  "netChange": 0.0,
  "volatility": 29.101,
  "delta": -0.206,
  "gamma": 0.056,
  "theta": -0.145,
  "vega": 0.05,
  "rho": -0.004,
  "openInterest": 32917,
  "timeValue": 0.6,
  "theoreticalOptionValue": 0.595,
  "theoreticalVolatility": 29.0,
  "strikePrice": 150.0,
  "expirationDate": 1678482000000,
  "daysToExpiration": 3,
  "expirationType": "S",
  "lastTradingDay": 1678496400000,
  "multiplier": 100.0,
  "inTheMoney": false
}

Call Option Example

Here's an example of a call option from the chain (AAPL $150 Call expiring March 10, 2023):

{
  "putCall": "CALL",
  "symbol": "AAPL_031023C150",
  "description": "AAPL Mar 10 2023 150 Call (Weekly)",
  "exchangeName": "OPR",
  "bid": 4.45,
  "ask": 4.55,
  "last": 4.35,
  "mark": 4.5,
  "bidSize": 89,
  "askSize": 109,
  "bidAskSize": "89X109",
  "lastSize": 0,
  "highPrice": 4.35,
  "lowPrice": 4.35,
  "openPrice": 0.0,
  "closePrice": 4.65,
  "totalVolume": 2,
  "tradeDate": null,
  "tradeTimeInLong": 1678199400115,
  "quoteTimeInLong": 1678199403163,
  "netChange": -0.3,
  "volatility": 29.101,
  "delta": 0.795,
  "gamma": 0.056,
  "theta": -0.189,
  "vega": 0.05,
  "rho": 0.015,
  "openInterest": 21434,
  "timeValue": 0.56,
  "theoreticalOptionValue": 4.628,
  "theoreticalVolatility": 29.0,
  "strikePrice": 150.0,
  "expirationDate": 1678482000000,
  "daysToExpiration": 3,
  "inTheMoney": true
}

Accessing Data

Options data can be accessed using the epoch timestamp as an index. The structure of the option chain follows this pattern:

OptionChain[epoch].putExpDateMap["{expiration}:{daysToExpiration}"]["{strikePrice}"][0]
OptionChain[epoch].callExpDateMap["{expiration}:{daysToExpiration}"]["{strikePrice}"][0]

For example, the chain contains expiration formats like "2023-03-10:3" and strike prices like "150.0".

Usage Example

import goldengoose
 
# Get the option chain for Apple
aapl_options = goldengoose.options.get("AAPL")
 
# Get current epoch
current_epoch = goldengoose.get_current_epoch()
 
# Access the current option chain data
current_chain = aapl_options[current_epoch]
 
# Access a specific put option (AAPL $150 Put expiring March 10, 2023)
march_10_150_put = current_chain.putExpDateMap["2023-03-10:3"]["150.0"][0]
 
# Get the option's delta and implied volatility
delta = march_10_150_put["delta"]      # -0.206
iv = march_10_150_put["volatility"]    # 29.101
 
# Print the bid and ask prices
print(f"Bid: ${march_10_150_put['bid']}")  # Bid: $0.6
print(f"Ask: ${march_10_150_put['ask']}")  # Ask: $0.6

Notes

The option chain is organized hierarchically by expiration date, then strike price
Expiration dates are formatted as "YYYY-MM-DD:DTE" where DTE is days to expiration
Strike prices are stored as string keys with decimal precision (e.g., "150.0")
Each strike price contains an array of option contracts (typically just one contract)
Greek values may appear as "NaN" when not available or calculable
The expirationType field indicates the option type: "S" for weekly options, "R" for regular options

Ggoption