add options chain endpoint (#352)

* add options chain endpoint

* fixed response

* changed to pagination

* doc changes

Author: antdjohns

polygon/rest/snapshot.py

@@ -1,5 +1,5 @@
 from .base import BaseClient
-from typing import Optional, Any, Dict, List, Union
+from typing import Optional, Any, Dict, List, Union, Iterator
 from .models import (
     TickerSnapshot,
     Direction,
@@ -137,6 +137,29 @@ def get_snapshot_option(
             options=options,
         )
 
+    def list_snapshot_options_chain(
+        self,
+        underlying_asset: str,
+        params: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+        options: Optional[RequestOptionBuilder] = None,
+    ) -> Union[Iterator[OptionContractSnapshot], HTTPResponse]:
+        """
+        Get the snapshot of all options contracts for an underlying ticker.
+
+        :param underlying_asset: The underlying ticker symbol of the option contract.
+        :return: List of Snapshots
+        """
+        url = f"/v3/snapshot/options/{underlying_asset}"
+        return self._paginate(
+            path=url,
+            params=self._get_params(self.list_snapshot_options_chain, locals()),
+            result_key="results",
+            deserializer=OptionContractSnapshot.from_dict,
+            raw=raw,
+            options=options,
+        )
+
     def get_snapshot_crypto_book(
         self,
         ticker: str,

test_rest/mocks/v3/snapshot/options/AAPL.json

@@ -0,0 +1,52 @@
+
+  {
+  "request_id": "104d9b901d0c9e81d284cb8b41c5cdd3",
+  "results": [{
+    "break_even_price": 179.075,
+    "day": {
+      "change": -2.3999999999999986,
+      "change_percent": -7.643312101910824,
+      "close": 29,
+      "high": 32.25,
+      "last_updated": 1651204800000000000,
+      "low": 29,
+      "open": 29.99,
+      "previous_close": 31.4,
+      "volume": 8,
+      "vwap": 30.7738
+    },
+    "details": {
+      "contract_type": "call",
+      "exercise_style": "american",
+      "expiration_date": "2023-06-16",
+      "shares_per_contract": 100,
+      "strike_price": 150,
+      "ticker": "O:AAPL230616C00150000"
+    },
+    "greeks": {
+      "delta": 0.6436614934293701,
+      "gamma": 0.0061735291012820675,
+      "theta": -0.028227189324641973,
+      "vega": 0.6381159723175714
+    },
+    "implied_volatility": 0.3570277203465058,
+    "last_quote": {
+      "ask": 29.25,
+      "ask_size": 209,
+      "bid": 28.9,
+      "bid_size": 294,
+      "last_updated": 1651254260800059648,
+      "midpoint": 29.075,
+      "timeframe": "REAL-TIME"
+    },
+    "open_interest": 8133,
+    "underlying_asset": {
+      "change_to_break_even": 19.11439999999999,
+      "last_updated": 1651254263172073152,
+      "price": 159.9606,
+      "ticker": "AAPL",
+      "timeframe": "REAL-TIME"
+    }
+  }],
+  "status": "OK"
+}

test_rest/test_snapshots.py

@@ -210,6 +210,59 @@ def test_get_snapshot_option(self):
         )
         self.assertEqual(snapshots, expected)
 
+    def test_list_snapshot_options_chain(self):
+        snapshots = [s for s in self.c.list_snapshot_options_chain("AAPL")]
+        expected = [
+            OptionContractSnapshot(
+                break_even_price=179.075,
+                day=DayOptionContractSnapshot(
+                    change=-2.3999999999999986,
+                    change_percent=-7.643312101910824,
+                    close=29,
+                    high=32.25,
+                    last_updated=1651204800000000000,
+                    low=29,
+                    open=29.99,
+                    previous_close=31.4,
+                    volume=8,
+                    vwap=30.7738,
+                ),
+                details=OptionDetails(
+                    contract_type="call",
+                    exercise_style="american",
+                    expiration_date="2023-06-16",
+                    shares_per_contract=100,
+                    strike_price=150,
+                    ticker="O:AAPL230616C00150000",
+                ),
+                greeks=Greeks(
+                    delta=0.6436614934293701,
+                    gamma=0.0061735291012820675,
+                    theta=-0.028227189324641973,
+                    vega=0.6381159723175714,
+                ),
+                implied_volatility=0.3570277203465058,
+                last_quote=LastQuoteOptionContractSnapshot(
+                    ask=29.25,
+                    ask_size=209,
+                    bid=28.9,
+                    bid_size=294,
+                    last_updated=1651254260800059648,
+                    midpoint=29.075,
+                    timeframe="REAL-TIME",
+                ),
+                open_interest=8133,
+                underlying_asset=UnderlyingAsset(
+                    change_to_break_even=19.11439999999999,
+                    last_updated=1651254263172073152,
+                    price=159.9606,
+                    ticker="AAPL",
+                    timeframe="REAL-TIME",
+                ),
+            )
+        ]
+        self.assertEqual(snapshots, expected)
+
     def test_get_snapshot_crypto_book(self):
         snapshots = self.c.get_snapshot_crypto_book("X:BTCUSD")
         expected = SnapshotTickerFullBook(