examples/options-trading-basic.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Alpaca-py options trading basic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/alpacahq/alpaca-py/blob/master/examples/options-trading-basic.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- This notebook shows how to use alpaca-py with options trading API endpoints\n",
    "- Please use ``paper account``. Please ``DO NOT`` use this notebook with live account. In this notebook, we place orders for options as an example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Please change the following to your own PAPER api key and secret\n",
    "# You can get them from https://alpaca.markets/\n",
    "\n",
    "api_key = \"<YOUR PAPER API KEY>\"\n",
    "secret_key = \"<YOUR PAPER API SECRET>\"\n",
    "\n",
    "\n",
    "#### We use paper environment for this example ####\n",
    "paper = True # Please do not modify this. This example is for paper trading only.\n",
    "####\n",
    "\n",
    "# Below are the variables for development this documents\n",
    "# Please do not change these variables\n",
    "\n",
    "trade_api_url = None\n",
    "trade_api_wss = None\n",
    "data_api_url = None\n",
    "option_stream_data_wss = None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# install alpaca-py\n",
    "! python3 -m pip install alpaca-py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "from datetime import datetime, timedelta\n",
    "from zoneinfo import ZoneInfo\n",
    "\n",
    "import alpaca\n",
    "from alpaca.trading.client import TradingClient\n",
    "from alpaca.data.timeframe import TimeFrame, TimeFrameUnit\n",
    "from alpaca.data.historical.option import OptionHistoricalDataClient\n",
    "from alpaca.trading.stream import TradingStream\n",
    "from alpaca.data.live.option import OptionDataStream\n",
    "\n",
    "from alpaca.data.requests import (\n",
    "    OptionBarsRequest,\n",
    "    OptionTradesRequest,\n",
    "    OptionLatestQuoteRequest,\n",
    "    OptionLatestTradeRequest,\n",
    "    OptionSnapshotRequest,\n",
    "    OptionChainRequest    \n",
    ")\n",
    "from alpaca.trading.requests import (\n",
    "    GetOptionContractsRequest,\n",
    "    GetAssetsRequest,\n",
    "    MarketOrderRequest,\n",
    "    GetOrdersRequest,\n",
    "    ClosePositionRequest\n",
    ")\n",
    "from alpaca.trading.enums import (\n",
    "    AssetStatus,\n",
    "    ExerciseStyle,\n",
    "    OrderSide,\n",
    "    OrderType,\n",
    "    TimeInForce,\n",
    "    QueryOrderStatus \n",
    ")\n",
    "from alpaca.common.exceptions import APIError"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# to run async code in jupyter notebook\n",
    "import nest_asyncio\n",
    "nest_asyncio.apply()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check version of alpaca-py\n",
    "alpaca.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Trading Client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# setup clients\n",
    "trade_client = TradingClient(api_key=api_key, secret_key=secret_key, paper=paper, url_override=trade_api_url)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check trading account\n",
    "# There are trhee new columns in the account object:\n",
    "# - options_buying_power\n",
    "# - options_approved_level\n",
    "# - options_trading_level\n",
    "acct = trade_client.get_account()\n",
    "acct"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check account configuration\n",
    "# - we have new field `max_options_trading_level`\n",
    "acct_config = trade_client.get_account_configurations()\n",
    "acct_config"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get list of assets which are options enabled\n",
    "# - we can filter assets by `options_enabled` attribute\n",
    "# - asset object has `options_enabled` attribute if it is options enabled\n",
    "req = GetAssetsRequest(\n",
    "  attributes = \"options_enabled\"  \n",
    ")\n",
    "assets = trade_client.get_all_assets(req)\n",
    "assets[:2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get list of options contracts for the given underlying symbol (e.g. SPY,AAPL)\n",
    "# - get_option_contracts() is a new method to get list of options contracts\n",
    "# - in this example, we get 2 options contracts for SPY,AAPL\n",
    "# - you can continue to fetch options contracts by specifying page_token from next_page_token of response\n",
    "underlying_symbols = [\"SPY\", \"AAPL\"]\n",
    "req = GetOptionContractsRequest(\n",
    "    underlying_symbols = underlying_symbols,               # specify underlying symbols\n",
    "    status = AssetStatus.ACTIVE,                           # specify asset status: active (default)\n",
    "    expiration_date = None,                                # specify expiration date (specified date + 1 day range)\n",
    "    expiration_date_gte = None,                            # we can pass date object\n",
    "    expiration_date_lte = None,                            # or string (YYYY-MM-DD)\n",
    "    root_symbol = None,                                    # specify root symbol\n",
    "    type = None,                                           # specify option type (ContractType.CALL or ContractType.PUT)\n",
    "    style = None,                                          # specify option style (ContractStyle.AMERICAN or ContractStyle.EUROPEAN)\n",
    "    strike_price_gte = None,                               # specify strike price range\n",
    "    strike_price_lte = None,                               # specify strike price range\n",
    "    limit = 2,                                             # specify limit\n",
    "    page_token = None,                                     # specify page token\n",
    ")\n",
    "res = trade_client.get_option_contracts(req)\n",
    "res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# continue to fetch option contracts if there is next_page_token in response\n",
    "if res.next_page_token is not None:\n",
    "    req = GetOptionContractsRequest(\n",
    "        underlying_symbols = underlying_symbols,               # specify underlying symbols\n",
    "        status = AssetStatus.ACTIVE,                           # specify asset status: active (default)\n",
    "        expiration_date = None,                                # specify expiration date (specified date + 1 day range)\n",
    "        expiration_date_gte = None,                            # we can pass date object\n",
    "        expiration_date_lte = None,                            # or string (YYYY-MM-DD)\n",
    "        root_symbol = None,                                    # specify root symbol\n",
    "        type = None,                                           # specify option type (ContractType.CALL or ContractType.PUT)\n",
    "        style = None,                                          # specify option style (ContractStyle.AMERICAN or ContractStyle.EUROPEAN)\n",
    "        strike_price_gte = None,                               # specify strike price range\n",
    "        strike_price_lte = None,                               # specify strike price range\n",
    "        limit = 2,                                             # specify limit\n",
    "        page_token = res.next_page_token,                      # specify page token\n",
    "    )\n",
    "    res = trade_client.get_option_contracts(req)\n",
    "    display(res)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get options contract by symbol\n",
    "# - get_option_contract() is a new method to get options contract by symbol or id\n",
    "symbol = res.option_contracts[0].symbol\n",
    "contract = trade_client.get_option_contract(symbol)\n",
    "contract"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get options contract by id\n",
    "id = res.option_contracts[0].id\n",
    "contract = trade_client.get_option_contract(symbol_or_id=id)\n",
    "contract"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get put options contracts\n",
    "underlying_symbols = [\"SPY\"]\n",
    "\n",
    "# specify expiration date range\n",
    "now = datetime.now(tz = ZoneInfo(\"America/New_York\"))\n",
    "day1 = now + timedelta(days = 1)\n",
    "day60 = now + timedelta(days = 60)\n",
    "\n",
    "req = GetOptionContractsRequest(\n",
    "    underlying_symbols = underlying_symbols,                     # specify underlying symbols\n",
    "    status = AssetStatus.ACTIVE,                                 # specify asset status: active (default)\n",
    "    expiration_date = None,                                      # specify expiration date (specified date + 1 day range)\n",
    "    expiration_date_gte = day1.date(),                           # we can pass date object\n",
    "    expiration_date_lte = day60.strftime(format = \"%Y-%m-%d\"),   # or string\n",
    "    root_symbol = None,                                          # specify root symbol\n",
    "    type = \"put\",                                                # specify option type: put\n",
    "    style = ExerciseStyle.AMERICAN,                              # specify option style: american\n",
    "    strike_price_gte = None,                                     # specify strike price range\n",
    "    strike_price_lte = None,                                     # specify strike price range\n",
    "    limit = 100,                                                 # specify limit\n",
    "    page_token = None,                                           # specify page\n",
    ")\n",
    "res = trade_client.get_option_contracts(req)\n",
    "res.option_contracts[:2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get high open_interest contract\n",
    "open_interest = 0\n",
    "high_open_interest_contract = None\n",
    "for contract in res.option_contracts:\n",
    "    if (contract.open_interest is not None) and (int(contract.open_interest) > open_interest):\n",
    "        open_interest = int(contract.open_interest)\n",
    "        high_open_interest_contract = contract\n",
    "high_open_interest_contract"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# place buy put option order\n",
    "# - we can place buy put option order same as buy stock/crypto order\n",
    "req = MarketOrderRequest(\n",
    "    symbol = high_open_interest_contract.symbol,\n",
    "    qty = 1,\n",
    "    side = OrderSide.BUY,\n",
    "    type = OrderType.MARKET,\n",
    "    time_in_force = TimeInForce.DAY,\n",
    ")\n",
    "res = trade_client.submit_order(req)\n",
    "res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get list of orders by specifying option contract symbol\n",
    "req = GetOrdersRequest(\n",
    "    status = QueryOrderStatus.ALL,\n",
    "    symbols = [high_open_interest_contract.symbol],\n",
    "    limit = 2,\n",
    ")\n",
    "orders = trade_client.get_orders(req)\n",
    "orders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# below cells should be done after market open otherwise there is no position for the option contract\n",
    "\n",
    "# get positions filtered by option contract symbol\n",
    "# if you do this example outside of market hours, you will see empty list\n",
    "# because we have no position in this option contract\n",
    "# please wait market open and run this example again\n",
    "positions = trade_client.get_all_positions()\n",
    "[pos for pos in positions if pos.symbol == high_open_interest_contract.symbol]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get positions by symbol\n",
    "trade_client.get_open_position(symbol_or_asset_id=high_open_interest_contract.symbol)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get positions by contract id\n",
    "trade_client.get_open_position(symbol_or_asset_id = high_open_interest_contract.id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# close the option position\n",
    "trade_client.close_position(\n",
    "    symbol_or_asset_id = high_open_interest_contract.symbol,\n",
    "    close_options = ClosePositionRequest(qty = \"1\")\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# exercise the options position\n",
    "# - this method does not return anything\n",
    "trade_client.exercise_options_position(\n",
    "    symbol_or_contract_id = high_open_interest_contract.symbol\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Trade Update (Stream)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With TradingStream client, you can get updates about trades\n",
    "\n",
    "fyi. you can open this notebook in another window and run below cell to check trade updates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# subscribe trade updates\n",
    "trade_stream_client = TradingStream(api_key, secret_key, paper=paper, url_override = trade_api_wss)\n",
    "\n",
    "async def trade_updates_handler(data):\n",
    "    print(data)\n",
    "\n",
    "trade_stream_client.subscribe_trade_updates(trade_updates_handler)\n",
    "trade_stream_client.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Market Data (Historical)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# setup option historical data client\n",
    "option_historical_data_client = OptionHistoricalDataClient(api_key, secret_key, url_override = data_api_url)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get options historical bars by symbol\n",
    "req = OptionBarsRequest(\n",
    "    symbol_or_symbols = high_open_interest_contract.symbol,\n",
    "    timeframe = TimeFrame(amount = 1, unit = TimeFrameUnit.Hour),   # specify timeframe\n",
    "    start = now - timedelta(days = 5),                              # specify start datetime, default=the beginning of the current day.\n",
    "    # end_date=None,                                                # specify end datetime, default=now\n",
    "    limit = 2,                                                      # specify limit\n",
    ")\n",
    "option_historical_data_client.get_option_bars(req).df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get options historical trades by symbol\n",
    "req = OptionTradesRequest(\n",
    "    symbol_or_symbols = high_open_interest_contract.symbol,\n",
    "    start = now - timedelta(days = 5),                              # specify start datetime, default=the beginning of the current day.\n",
    "    # end=None,                                                     # specify end datetime, default=now\n",
    "    limit = 2,                                                      # specify limit\n",
    ")\n",
    "option_historical_data_client.get_option_trades(req).df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get options exchange codes\n",
    "option_historical_data_client.get_option_exchange_codes()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get option latest quote by symbol\n",
    "req = OptionLatestQuoteRequest(\n",
    "    symbol_or_symbols = [high_open_interest_contract.symbol],\n",
    ")\n",
    "option_historical_data_client.get_option_latest_quote(req)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get option latest trade by symbol\n",
    "req = OptionLatestTradeRequest(\n",
    "    symbol_or_symbols = [high_open_interest_contract.symbol],\n",
    ")\n",
    "option_historical_data_client.get_option_latest_trade(req)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get option snapshot by symbol\n",
    "req = OptionSnapshotRequest(\n",
    "    symbol_or_symbols = [high_open_interest_contract.symbol],\n",
    ")\n",
    "option_historical_data_client.get_option_snapshot(req)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get option chain by underlying_symbol\n",
    "req = OptionChainRequest(\n",
    "    underlying_symbol = high_open_interest_contract.underlying_symbol,\n",
    ")\n",
    "option_historical_data_client.get_option_chain(req)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Market Data (Stream)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "option_data_stream_client = OptionDataStream(api_key, secret_key, url_override = option_stream_data_wss)\n",
    "\n",
    "async def option_data_stream_handler(data):\n",
    "    print(data)\n",
    "\n",
    "symbols = [\n",
    "    high_open_interest_contract.symbol,\n",
    "]\n",
    "\n",
    "option_data_stream_client.subscribe_quotes(option_data_stream_handler, *symbols) \n",
    "option_data_stream_client.subscribe_trades(option_data_stream_handler, *symbols)\n",
    "\n",
    "option_data_stream_client.run()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}