doc: Update docs for options trading (#410)

* doc: update docs for options trading * doc: update README.md
alpacahq · Feb 9, 2024 · 481331a · 481331a
1 parent 51ef66a
commit 481331a
Show file tree

Hide file tree

Showing 12 changed files with 645 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -114,18 +114,18 @@ Here is a rough example of what is possible.
 ```
 
 ### Many Clients <a name="many-clients"></a>
-Alpaca-py has a lot of client classes. There is a client for each API and even asset class specific clients (``StockHistoricalDataClient``, ``CryptoDataStream``). This requires you to pick and choose clients based on your needs.
+Alpaca-py has a lot of client classes. There is a client for each API and even asset class specific clients (``StockHistoricalDataClient``, ``CryptoDataStream``, ``OptionHistoricalDataClient``). This requires you to pick and choose clients based on your needs.
 
 **Broker API:** ``BrokerClient``
 
 **Trading API:** ``TradingClient``
 
-**Market Data API:**  ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``CryptoDataStream``, ``StockDataStream``
+**Market Data API:**  ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``OptionHistoricalDataClient``, ``CryptoDataStream``, ``StockDataStream``, ``OptionDataStream``
 
 ## API Keys <a name="api-keys"></a>
 
 ### Trading and Market Data API <a name="trading-api-keys"></a>
-In order to use Alpaca’s services you’ll need to sign up for an Alpaca account and retrieve your API keys. Signing up is completely free and takes only a few minutes. Sandbox environments are available to test out the API. To use the sandbox environment, you will need to provide sandbox/paper keys. API keys are passed into Alpaca-py through either ``TradingClient``, ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``StockDataStream``, or ``CryptoDataStream``.
+In order to use Alpaca’s services you’ll need to sign up for an Alpaca account and retrieve your API keys. Signing up is completely free and takes only a few minutes. Sandbox environments are available to test out the API. To use the sandbox environment, you will need to provide sandbox/paper keys. API keys are passed into Alpaca-py through either ``TradingClient``, ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``OptionHistoricalDataClient``. ``StockDataStream``, ``CryptoDataStream``, or ``OptionDataStream``.
 
 ### Broker API <a name="broker-api-keys"></a>
 To use the Broker API, you will need to sign up for a broker account and retrieve your Broker API keys. The API keys can be found on the dashboard once you’ve logged in. Alpaca also provides a sandbox environment to test out Broker API. To use the sandbox mode, provide your sandbox keys. Once you have your keys, you can pass them into ``BrokerClient`` to get started.
@@ -135,7 +135,7 @@ Alpaca’s APIs allow you to do everything from building algorithmic trading str
 
 To view full descriptions and examples view the [documentation page](https://docs.alpaca.markets/docs/getting-started-1).
 
-**Market Data API**: Access live and historical market data for 5000+ stocks and 20+ crypto.
+**Market Data API**: Access live and historical market data for 5000+ stocks, 20+ crypto, and options(beta).
 
 **Trading API**: Trade stock and crypto with lightning fast execution speeds.
 
@@ -220,3 +220,14 @@ bars = client.get_crypto_bars(request_params)
 bars.df
 
 ```
+
+### Options Trading (Beta) <a name="options-trading"></a>
+
+We're excited to support options trading! Use this section to read up on Alpaca's Beta trading capabilities.
+For more details, please refer to [our documentation page for options trading](https://docs.alpaca.markets/v1.1/docs/options-trading)
+
+> Options trading is in BETA. Only BETA users are able to access options endpoints. We will continue to update our documentation as we collect your valuable feedback.
+
+There is an example jupyter notebook to explain methods of alpaca-py for options trading.
+
+* [jupyter notebook: options trading basic example with alpaca-py](examples/options-trading-basic.ipynb)
diff --git a/docs/api_reference/data/option.rst b/docs/api_reference/data/option.rst
@@ -0,0 +1,10 @@
+==================
+Option Market Data
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   option/historical
+   option/live
+   option/requests
diff --git a/docs/api_reference/data/option/historical.rst b/docs/api_reference/data/option/historical.rst
@@ -0,0 +1,33 @@
+===============
+Historical Data
+===============
+
+OptionHistoricalDataClient
+--------------------------
+
+.. autoclass:: alpaca.data.historical.option.OptionHistoricalDataClient
+   :members: __init__
+
+
+Get Option Latest Quote
+-----------------------
+
+.. automethod:: alpaca.data.historical.option.OptionHistoricalDataClient.get_option_latest_quote
+
+
+Get Option Latest Trade
+-----------------------
+
+.. automethod:: alpaca.data.historical.option.OptionHistoricalDataClient.get_option_latest_trade
+
+
+Get Option Snapshot
+-------------------
+
+.. automethod:: alpaca.data.historical.option.OptionHistoricalDataClient.get_option_snapshot
+
+
+Get Option Chain
+----------------
+
+.. automethod:: alpaca.data.historical.option.OptionHistoricalDataClient.get_option_chain
diff --git a/docs/api_reference/data/option/live.rst b/docs/api_reference/data/option/live.rst
@@ -0,0 +1,11 @@
+==============
+Real-Time Data
+==============
+
+
+OptionDataStream
+----------------
+
+.. autoclass:: alpaca.data.live.option.OptionDataStream
+   :members:
+   :inherited-members:
diff --git a/docs/api_reference/data/option/requests.rst b/docs/api_reference/data/option/requests.rst
@@ -0,0 +1,27 @@
+========
+Requests
+========
+
+
+OptionLatestQuoteRequest
+------------------------
+
+.. autoclass:: alpaca.data.requests.OptionLatestQuoteRequest
+
+
+OptionLatestTradeRequest
+------------------------
+
+.. autoclass:: alpaca.data.requests.OptionLatestTradeRequest
+
+
+OptionSnapshotRequest
+---------------------
+
+.. autoclass:: alpaca.data.requests.OptionSnapshotRequest
+
+
+OptionChainRequest
+------------------
+
+.. autoclass:: alpaca.data.requests.OptionChainRequest
diff --git a/docs/api_reference/data_api.rst b/docs/api_reference/data_api.rst
@@ -7,6 +7,7 @@ Market Data Reference
 
    data/stock
    data/crypto
+   data/option
    data/timeframe
    data/models
    data/enums

diff --git a/docs/api_reference/trading/contracts.rst b/docs/api_reference/trading/contracts.rst
@@ -0,0 +1,18 @@
+=========
+Contracts
+=========
+
+The option contracts endpoints allow you to view the list of option contracts available on Alpaca for market data and trading.
+
+Get Option Contracts
+--------------------
+
+.. automethod:: alpaca.trading.client.TradingClient.get_option_contracts
+
+
+Get Option Contract
+-------------------
+
+.. automethod:: alpaca.trading.client.TradingClient.get_option_contract
+
+
diff --git a/docs/api_reference/trading_api.rst b/docs/api_reference/trading_api.rst
@@ -14,6 +14,7 @@ Contents
    trading/positions
    trading/orders
    trading/assets
+   trading/contracts
    trading/watchlists
    trading/calendar
    trading/clock

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -19,9 +19,9 @@ Alpaca's APIs allow you to do everything from building algorithmic trading strat
 a full brokerage experience for your own end users.
 Here are some things you can do with Alpaca-py.
 
-**Market Data API**: Access live and historical market data for 5000+ stocks and 20+ crypto.
+**Market Data API**: Access live and historical market data for 5000+ stocks, 20+ crypto, and options(beta).
 
-**Trading API**: Trade stock and crypto with lightning fast execution speeds.
+**Trading API**: Trade stock, crypto, and options(beta) with lightning fast execution speeds.
 
 **Broker API & Connect**: Build investment apps - from robo-advisors to brokerages.
 
@@ -131,14 +131,14 @@ Many Clients
 ^^^^^^^^^^^^
 
 Alpaca-py has a lot of client classes. There is a client for each API and even
-asset class specific clients (``StockHistoricalData``, ``CryptoDataStream``). This requires
+asset class specific clients (``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``OptionHistoricalData``). This requires
 you to pick and choose clients based on your needs.
 
 **Broker API:** ``BrokerClient``
 
 **Trading API:** ``TradingClient``
 
-**Market Data API:**  ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``CryptoDataStream``, ``StockDataStream``
+**Market Data API:**  ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``OptionHistoricalDataClient``, ``CryptoDataStream``, ``StockDataStream``, ``OptionDataStream``
 
 
 
@@ -150,7 +150,7 @@ Trading and Market Data API
 In order to use Alpaca's services you'll need to `sign up for an Alpaca account <https://app.alpaca.markets/signup>`_ and retrieve your API keys.
 Signing up is completely free and takes only a few minutes. Sandbox environments are available to test
 out the API. To use the sandbox environment, you will need to provide sandbox/paper keys. API keys are
-passed into Alpaca-py through either ``TradingClient``, ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``StockDataStream``,  or ``CryptoDataStream``.
+passed into Alpaca-py through either ``TradingClient``, ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, ``OptionHistoricalDataClient``, ``StockDataStream``,  ``CryptoDataStream``, or ``OptionDataStream``.
 
 Broker API
 ^^^^^^^^^^

diff --git a/docs/index.rst b/docs/index.rst
@@ -64,7 +64,7 @@ Market Data
 
 .. image:: images/icons/market-data.png
 
-The Market Data API gives you access to real time and historical data for equities and crypto.
+The Market Data API gives you access to real time and historical data for equities, crypto and options(beta).
 Learn more on the :ref:`market-data` page.
 
 

diff --git a/docs/market_data.rst b/docs/market_data.rst
@@ -4,7 +4,7 @@
 Market Data
 ===========
 
-The market data API allows you to access both live and historical data for equities and cryptocurrencies. 
+The market data API allows you to access both live and historical data for equities, cryptocurrencies, and options. 
 Over 5 years of historical data is available for thousands of equity and cryptocurrency symbols. 
 Various data types are available such as bars/candles (OHLCV), trade data (price and sales), and quote data. For
 crypto, there is also orderbook data. For more information on the data types available,
@@ -30,26 +30,27 @@ providing API keys. However, if you do provide API keys, your rate limit will be
 Historical Data
 ---------------
 
-There are 2 historical data clients: ``StockHistoricalDataClient`` and ``CryptoHistoricalDataClient``.
+There are 2 historical data clients: ``StockHistoricalDataClient``, ``CryptoHistoricalDataClient``, and ``OptionHistoricalDataClient``.
 The crypto data client does not require API keys to use.
 
 
 Clients
 ^^^^^^^
 
-Historical Data can be queried by using one of the two historical data clients: ``StockHistoricalDataClient``
-and ``CryptoHistoricalDataClient``. Historical data is available for Bar, Trade and Quote datatypes. For
-crypto, latest orderbook data is also available.
+Historical Data can be queried by using one of the two historical data clients: ``StockHistoricalDataClient``,
+``CryptoHistoricalDataClient``, and ``OptionHistoricalDataClient``. Historical data is available for Bar, Trade and Quote datatypes.
+For crypto, latest orderbook data is also available.
 
 .. code-block:: python
 
-    from alpaca.data import CryptoHistoricalDataClient, StockHistoricalDataClient
+    from alpaca.data import CryptoHistoricalDataClient, StockHistoricalDataClient, OptionHistoricalDataClient
 
     # no keys required.
     crypto_client = CryptoHistoricalDataClient()
 
     # keys required
     stock_client = StockHistoricalDataClient("api-key",  "secret-key")
+    option_client = OptionHistoricalDataClient("api-key",  "secret-key")
 
 
 Retrieving Latest Quote Data
@@ -150,7 +151,7 @@ Clients
 ^^^^^^^
 
 The data stream clients lets you subscribe to real-time data via WebSockets. There are clients
-for crypto data and stock data. These clients are different from the historical ones. They do not
+for crypto data, stock data and option data. These clients are different from the historical ones. They do not
 have methods which return data immediately. Instead, the methods in these clients allow you to assign
 methods to receive real-time data.
 
@@ -164,6 +165,7 @@ methods to receive real-time data.
 
     # keys required
     stock_stream = StockDataStream("api-key", "secret-key")
+    option_stream = OptionDataStream("api-key", "secret-key")
 
 
 Subscribing to Real-Time Quote Data