margin-estimator 0.1__py3-none-any.whl

margin_estimator/__init__.py

@@ -0,0 +1,11 @@
+from .margin import calculate_margin
+from .models import ETFType, Option, OptionType, Underlying
+
+
+__all__ = [
+    "ETFType",
+    "Option",
+    "OptionType",
+    "Underlying",
+    "calculate_margin",
+]

margin_estimator/margin.py

@@ -0,0 +1,214 @@
+from datetime import date, timedelta
+from decimal import Decimal
+
+from .models import (
+    ETFType,
+    MarginRequirements,
+    Option,
+    OptionType,
+    Underlying,
+)
+
+ZERO = Decimal(0)
+
+
+def calculate_margin(legs: list[Option], underlying: Underlying) -> MarginRequirements:
+    """
+    Calculate margin for an arbitrary order according to CBOE's Margin Manual.
+    """
+    if len(legs) == 1:
+        if legs[0].quantity > 0:
+            return _calculate_margin_long_option(legs[0])
+        return _calculate_margin_short_option(legs[0], underlying)
+    if len(legs) == 2 and legs[0].quantity < 0 and legs[1].quantity < 0:
+        return _calculate_margin_short_strangle(legs, underlying)
+    if len(legs) == 2 and legs[0].expiration != legs[1].expiration:
+        short = legs[0] if legs[0].quantity < 0 else legs[1]
+        long = legs[1] if legs[1] != short else legs[0]
+        if short.expiration > long.expiration:
+            margin = _calculate_margin_short_option(short, underlying)
+            return margin + _calculate_margin_long_option(long)
+    calls = [leg for leg in legs if leg.type == OptionType.CALL]
+    puts = [leg for leg in legs if leg.type == OptionType.PUT]
+    extra_puts = sum(c.quantity for c in calls)
+    extra_calls = sum(p.quantity for p in puts)
+    if extra_puts or extra_calls:
+        raise Exception(
+            "Ratio spreads/complex orders not supported! Try splitting your order into "
+            "smaller components and summing the results."
+        )
+    return _calculate_margin_spread(legs)
+
+
+def _calculate_margin_long_option(option: Option) -> MarginRequirements:
+    """
+    Calculate margin for a single long option.
+    Source: CBOE Margin Manual
+    """
+    if option.expiration < date.today() + timedelta(days=90):
+        return MarginRequirements(
+            # Pay for each put or call in full.
+            cash_requirement=option.price * 100 * option.quantity,
+            # Pay for each put or call in full.
+            margin_requirement=option.price * 100 * option.quantity,
+        )
+    reduced_requirement = round(option.price * 3 / 4, 2)
+    return MarginRequirements(
+        # Pay for each put or call in full.
+        cash_requirement=option.price * 100 * option.quantity,
+        # Listed: 75% of the total cost of the option.
+        margin_requirement=reduced_requirement * 100 * option.quantity,
+    )
+
+
+def _calculate_margin_short_option(
+    option: Option, underlying: Underlying
+) -> MarginRequirements:
+    """
+    Calculate margin for a single short option.
+    Source: CBOE Margin Manual
+    """
+    if option.type == OptionType.PUT:
+        otm_distance = max(ZERO, underlying.price - option.strike)
+    else:
+        otm_distance = max(ZERO, option.strike - underlying.price)
+    # broad-based ETFs/indices
+    if underlying.etf_type == ETFType.BROAD:
+        if option.type == OptionType.PUT:
+            minimum = round(
+                option.price + option.strike / 10 * underlying.leverage_factor, 2
+            )
+            base = round(
+                option.price
+                + underlying.price * 3 / 20 * underlying.leverage_factor
+                - otm_distance,
+                2,
+            )
+            # 100% of option proceeds plus 15% of underlying index value less
+            # out-of-the money amount, if any, to a minimum for puts of option
+            # proceeds plus 10% of the put’s exercise price.
+            margin_requirement = max(minimum, base)
+            # Deposit cash or cash equivalents equal to aggregate exercise price
+            cash_requirement = (option.strike - option.price) * 100
+        else:  # OptionType.CALL
+            minimum = round(
+                option.price + underlying.price / 10 * underlying.leverage_factor, 2
+            )
+            base = round(
+                option.price
+                + underlying.price * 3 / 20 * underlying.leverage_factor
+                - otm_distance,
+                2,
+            )
+            # 100% of option proceeds plus 15% of underlying index value less
+            # out-of-the money amount, if any, to a minimum for calls of option
+            # proceeds plus 10% of the underlying index value.
+            margin_requirement = max(minimum, base)
+            # Deposit cash or cash equivalents equal to aggregate exercise price
+            cash_requirement = (option.strike - option.price) * 100
+    # narrow-based ETFs/indices, volatility indices, equities
+    else:
+        if option.type == OptionType.PUT:
+            minimum = round(
+                option.price + option.strike / 10 * underlying.leverage_factor, 2
+            )
+            base = round(
+                option.price
+                + underlying.price / 5 * underlying.leverage_factor
+                - otm_distance,
+                2,
+            )
+            # 100% of option proceeds plus 20% of underlying security / index value
+            # less out-of-the-money amount, if any, to a minimum for puts of option
+            # proceeds plus 10% of the put’s exercise price.
+            margin_requirement = max(minimum, base)
+            # Deposit cash or cash equivalents equal to aggregate exercise price.
+            cash_requirement = (option.strike - option.price) * 100
+        else:  # OptionType.CALL
+            minimum = round(
+                option.price + underlying.price / 10 * underlying.leverage_factor, 2
+            )
+            base = round(
+                option.price
+                + underlying.price / 5 * underlying.leverage_factor
+                - otm_distance,
+                2,
+            )
+            # 100% of option proceeds plus 20% of underlying security / index value
+            # less out-of-the-money amount, if any, to a minimum for puts of option
+            # proceeds plus 10% of the underlying security/index value.
+            margin_requirement = max(minimum, base)
+            # Deposit underlying security.
+            cash_requirement = (underlying.price - option.price) * 100
+    margin_requirement *= 100 * abs(option.quantity)
+    return MarginRequirements(
+        cash_requirement=cash_requirement,
+        margin_requirement=margin_requirement,
+    )
+
+
+def _calculate_margin_short_strangle(
+    legs: list[Option], underlying: Underlying
+) -> MarginRequirements:
+    """
+    Calculate margin for a short strangle.
+    Source: CBOE Margin Manual
+    """
+    # Deposit an escrow agreement for each option.
+    margin1 = _calculate_margin_short_option(legs[0], underlying)
+    margin2 = _calculate_margin_short_option(legs[1], underlying)
+    # For the same underlying security, short put or short call requirement whichever
+    # is greater, plus the option proceeds of the other side.
+    if margin1.margin_requirement > margin2.margin_requirement:
+        margin_requirement = margin1.margin_requirement + legs[1].price * 100
+    else:
+        margin_requirement = margin2.margin_requirement + legs[0].price * 100
+    margin_requirement *= abs(legs[0].quantity)
+    return MarginRequirements(
+        cash_requirement=margin1.cash_requirement + margin2.cash_requirement,
+        margin_requirement=margin_requirement,
+    )
+
+
+def _calculate_loss_for(leg: Option, price: Decimal) -> Decimal:
+    """
+    Calculate value at expiration for option at given price.
+    """
+    if leg.type == OptionType.CALL:
+        itm_distance = max(ZERO, price - leg.strike)
+    else:
+        itm_distance = max(ZERO, leg.strike - price)
+    return itm_distance * leg.quantity * 100
+
+
+def _get_net_credit_or_debit(legs: list[Option]) -> Decimal:
+    """
+    Calculate total debit/credit paid/collected for the order.
+    """
+    total = ZERO
+    for leg in legs:
+        total += leg.quantity * leg.price * 100
+    return total
+
+
+def _calculate_margin_spread(legs: list[Option]) -> MarginRequirements:
+    """
+    Calculate margin for a credit spread.
+    Source: CBOE Margin Manual
+    """
+    strikes = set(leg.strike for leg in legs)
+    pnl = _get_net_credit_or_debit(legs)
+    losses = []
+    for strike in strikes:
+        points = [_calculate_loss_for(leg, strike) for leg in legs]
+        losses.append(sum(points))  # type: ignore
+    margin_requirement = abs(min(losses)) + pnl
+
+    return MarginRequirements(
+        # deposit and maintain cash or cash equivalents equal to the spread’s maximum
+        # potential loss
+        cash_requirement=margin_requirement,
+        # the lesser of the amount required for the short option(s), or the spread’s
+        # maximum potential loss
+        margin_requirement=margin_requirement,
+    )

margin_estimator/models.py

@@ -0,0 +1,41 @@
+from datetime import date
+from decimal import Decimal
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class ETFType(StrEnum):
+    BROAD = "broad-based"
+    NARROW = "narrow-based"
+    VOLATILITY = "volatility"
+
+
+class OptionType(StrEnum):
+    CALL = "C"
+    PUT = "P"
+
+
+class Option(BaseModel):
+    expiration: date
+    price: Decimal
+    quantity: int
+    strike: Decimal
+    type: OptionType
+
+
+class MarginRequirements(BaseModel):
+    cash_requirement: Decimal
+    margin_requirement: Decimal
+
+    def __add__(self, other: "MarginRequirements"):
+        return MarginRequirements(
+            cash_requirement=self.cash_requirement + other.cash_requirement,
+            margin_requirement=self.margin_requirement + other.margin_requirement,
+        )
+
+
+class Underlying(BaseModel):
+    etf_type: ETFType | None = None
+    leverage_factor: Decimal = Decimal(1)
+    price: Decimal

margin_estimator-0.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.3
+Name: margin-estimator
+Version: 0.1
+Summary: Calculate estimated margin requirements for equities, options, futures, and futures options. Based on CBOE and CME margining.
+Project-URL: Homepage, https://github.com/tastyware/margin-estimator
+Author-email: Graeme Holliday <graeme.holliday@pm.me>
+License: MIT License
+        
+        Copyright (c) 2024 tastyware
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.9.2
+Description-Content-Type: text/markdown
+
+# margin-estimator
+Calculate estimated margin requirements for equities, options, futures, and futures options. Based on CBOE and CME margining.
+
+> [!NOTE]
+> Not all features are available yet, pending further development.
+> Currently, equity/ETF/index options are supported, for any trade
+> type other than ratio spreads, box spreads, and jaze lizards.
+> Contributions welcome!
+
+## Installation
+
+```console
+$ pip install margin_estimator
+```
+
+## Usage
+
+Simply pass a list of legs to the `calculate_margin` function along with an `Underlying` object containing information on the underlying, and you'll get back margin requirement estimates for cash and margin accounts!
+
+```python
+from datetime import date
+from decimal import Decimal
+from margin_estimator import (
+    ETFType,
+    Option,
+    OptionType,
+    Underlying,
+    calculate_margin,
+)
+
+# a SPY iron condor
+# make sure to pass `ETFType.BROAD` for broad-based indices
+underlying = Underlying(price=Decimal("587.88"), etf_type=ETFType.BROAD)
+expiration = date(2024, 12, 20)
+long_put = Option(
+    expiration=expiration,
+    price=Decimal("4.78"),
+    quantity=1,
+    strike=Decimal(567),
+    type=OptionType.PUT,
+)
+short_put = Option(
+    expiration=expiration,
+    price=Decimal("5.61"),
+    quantity=-1,
+    strike=Decimal(572),
+    type=OptionType.PUT,
+)
+short_call = Option(
+    expiration=expiration,
+    price=Decimal("5.23"),
+    quantity=-1,
+    strike=Decimal(602),
+    type=OptionType.CALL,
+)
+long_call = Option(
+    expiration=expiration,
+    price=Decimal("3.68"),
+    quantity=1,
+    strike=Decimal(607),
+    type=OptionType.CALL,
+)
+margin = calculate_margin(
+    [long_put, short_put, long_call, short_call], underlying
+)
+print(margin)
+```
+
+```python
+>>> cash_requirement=Decimal('262.00') margin_requirement=Decimal('262.00')
+```
+
+For normal equities you can omit the `etf_type` parameter:
+
+```python
+# a short F put
+underlying = Underlying(price=Decimal("11.03"))
+expiration = date(2024, 12, 20)
+put = Option(
+    expiration=expiration,
+    price=Decimal("0.45"),
+    quantity=-1,
+    strike=Decimal(11),
+    type=OptionType.PUT,
+)
+margin = calculate_margin([put], underlying)
+print(margin)
+```
+
+```python
+>>> cash_requirement=Decimal('1055.00') margin_requirement=Decimal('263.00')
+```
+
+And for leveraged products, you'll need to pass in the `leverage_factor`:
+
+```python
+# a naked TQQQ call
+underlying = Underlying(
+    price=Decimal("77.35"),
+    etf_type=ETFType.BROAD,
+    leverage_factor=Decimal(3),
+)
+expiration = date(2024, 12, 20)
+call = Option(
+    expiration=expiration,
+    price=Decimal("4.45"),
+    quantity=-1,
+    strike=Decimal(80),
+    type=OptionType.CALL,
+)
+margin = calculate_margin([call], underlying)
+print(margin)
+```
+
+```python
+>>> cash_requirement=Decimal('7555.00') margin_requirement=Decimal('3661.00')
+```
+
+Please note that all numbers are baseline estimates based on CBOE/CME guidelines and individual broker margins will likely vary significantly.

margin_estimator-0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+margin_estimator/__init__.py,sha256=jicOQATyGlqpsGfXsCIoVouspMVHO1HRShIsn3xCzDI,202
+margin_estimator/margin.py,sha256=3RSxHFpWQNPHcD9Mj6YBDeY0dXdYqeWnhuG6KUqH8Gw,8573
+margin_estimator/models.py,sha256=lMjUyL1ufrjXOSgkUUBL3c5bZwOKn3AsFOmGZkZVfF8,892
+margin_estimator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+margin_estimator-0.1.dist-info/METADATA,sha256=fK7E5YVtF0RMfV1ap64WX31ikrQt8r52-mRE3OQGKCM,4624
+margin_estimator-0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+margin_estimator-0.1.dist-info/licenses/LICENSE,sha256=DxJk7vwH5bPnqpXaMQ06BWBM6BVfBOx8GzFmqpKm8oQ,1066
+margin_estimator-0.1.dist-info/RECORD,,

margin_estimator-0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

margin_estimator-0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tastyware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.