optionsahoy 0.1.0__tar.gz

optionsahoy-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.pyc

optionsahoy-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: optionsahoy
+Version: 0.1.0
+Summary: Thin Python client for the OptionsAhoy keyless public equity-compensation REST API.
+Project-URL: Homepage, https://optionsahoy.com
+Project-URL: Repository, https://github.com/AlvisoOculus/optionsahoy-mcp
+Project-URL: Documentation, https://optionsahoy.com/for-agents
+Author: AlphaLatitude Inc.
+License: MIT
+Keywords: amt,equity-compensation,iso,nso,options,qsbs,rsu
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# optionsahoy
+
+A thin, dependency-light Python client for the OptionsAhoy keyless public REST API.
+It wraps the equity-compensation calculators (incentive stock option (ISO) /
+alternative minimum tax (AMT), non-qualified stock options (NSO), restricted stock
+units (RSU), single-stock concentration, protective put hedges, qualified small
+business stock (QSBS), and funding a cash goal from equity).
+
+No API key is required, read, or sent anywhere. The only runtime dependency is
+[httpx](https://www.python-httpx.org/).
+
+## Install
+
+```bash
+pip install optionsahoy
+```
+
+Or from this repository, editable:
+
+```bash
+pip install -e integrations/python/optionsahoy
+```
+
+## Usage
+
+```python
+from optionsahoy import OptionsAhoyClient, OptionsAhoyError
+
+client = OptionsAhoyClient()  # base_url defaults to https://optionsahoy.com
+
+try:
+    result = client.qsbs(
+        acquisitionDate="2018-01-01",
+        saleDate="2026-02-01",
+        entityType="us-c-corp",
+        acquisitionMethod="original-issuance",
+        assetCategory="under-50m",
+        industry="tech-software",
+        activeBusiness="yes",
+        adjustedBasis=10000,
+        expectedGain=2000000,
+        stateCode="CA",
+        ordinaryIncome=250000,
+        filingStatus="single",
+    )
+    print(result)
+except OptionsAhoyError as err:
+    print(err.status_code, err.payload)
+```
+
+Field names, types, and required-ness mirror the published OpenAPI schema at
+<https://optionsahoy.com/openapi.json>. Optional fields left unset are not sent.
+
+### Forward-looking inputs
+
+Some endpoints (for example `nso` and `rsu_sell_vs_hold`) accept forward-looking
+fields such as `expectedSalePrice` and `volatility` that the OpenAPI schema marks
+optional. At runtime the API requires you to supply these explicitly, or to set a
+covered `ticker` (for example `"NVDA"`) so the API can derive them from that
+symbol's trailing data. Do not invent these values; pass what the user provides or a
+ticker. Omitting both returns a clear 400 explaining which field is needed.
+
+## Methods
+
+- `amt_iso(...)` — multi-year ISO exercise optimizer under the AMT
+- `nso(...)` — NSO exercise tax and after-tax proceeds
+- `rsu_sell_vs_hold(...)` — sell-at-vest versus hold for RSUs
+- `concentration(...)` — concentrated single-stock position analysis
+- `protective_put(...)` — protective put hedge pricing
+- `qsbs(...)` — QSBS eligibility and capital-gains exclusion
+- `equity_funding(...)` — plan equity sales to fund a cash goal by a target date

optionsahoy-0.1.0/README.md

@@ -0,0 +1,71 @@
+# optionsahoy
+
+A thin, dependency-light Python client for the OptionsAhoy keyless public REST API.
+It wraps the equity-compensation calculators (incentive stock option (ISO) /
+alternative minimum tax (AMT), non-qualified stock options (NSO), restricted stock
+units (RSU), single-stock concentration, protective put hedges, qualified small
+business stock (QSBS), and funding a cash goal from equity).
+
+No API key is required, read, or sent anywhere. The only runtime dependency is
+[httpx](https://www.python-httpx.org/).
+
+## Install
+
+```bash
+pip install optionsahoy
+```
+
+Or from this repository, editable:
+
+```bash
+pip install -e integrations/python/optionsahoy
+```
+
+## Usage
+
+```python
+from optionsahoy import OptionsAhoyClient, OptionsAhoyError
+
+client = OptionsAhoyClient()  # base_url defaults to https://optionsahoy.com
+
+try:
+    result = client.qsbs(
+        acquisitionDate="2018-01-01",
+        saleDate="2026-02-01",
+        entityType="us-c-corp",
+        acquisitionMethod="original-issuance",
+        assetCategory="under-50m",
+        industry="tech-software",
+        activeBusiness="yes",
+        adjustedBasis=10000,
+        expectedGain=2000000,
+        stateCode="CA",
+        ordinaryIncome=250000,
+        filingStatus="single",
+    )
+    print(result)
+except OptionsAhoyError as err:
+    print(err.status_code, err.payload)
+```
+
+Field names, types, and required-ness mirror the published OpenAPI schema at
+<https://optionsahoy.com/openapi.json>. Optional fields left unset are not sent.
+
+### Forward-looking inputs
+
+Some endpoints (for example `nso` and `rsu_sell_vs_hold`) accept forward-looking
+fields such as `expectedSalePrice` and `volatility` that the OpenAPI schema marks
+optional. At runtime the API requires you to supply these explicitly, or to set a
+covered `ticker` (for example `"NVDA"`) so the API can derive them from that
+symbol's trailing data. Do not invent these values; pass what the user provides or a
+ticker. Omitting both returns a clear 400 explaining which field is needed.
+
+## Methods
+
+- `amt_iso(...)` — multi-year ISO exercise optimizer under the AMT
+- `nso(...)` — NSO exercise tax and after-tax proceeds
+- `rsu_sell_vs_hold(...)` — sell-at-vest versus hold for RSUs
+- `concentration(...)` — concentrated single-stock position analysis
+- `protective_put(...)` — protective put hedge pricing
+- `qsbs(...)` — QSBS eligibility and capital-gains exclusion
+- `equity_funding(...)` — plan equity sales to fund a cash goal by a target date

optionsahoy-0.1.0/optionsahoy/__init__.py

@@ -0,0 +1,10 @@
+"""OptionsAhoy: a thin, dependency-light client for the keyless public REST API."""
+
+from optionsahoy.client import (
+    DEFAULT_BASE_URL,
+    OptionsAhoyClient,
+    OptionsAhoyError,
+)
+
+__all__ = ["OptionsAhoyClient", "OptionsAhoyError", "DEFAULT_BASE_URL"]
+__version__ = "0.1.0"

optionsahoy-0.1.0/optionsahoy/client.py

@@ -0,0 +1,383 @@
+"""HTTP client for the OptionsAhoy keyless public REST API.
+
+Every endpoint is an unauthenticated POST (except the discovery/stats GETs, which
+this client does not wrap). Field names, types, and required-ness mirror the
+published OpenAPI schema at https://optionsahoy.com/openapi.json one for one; this
+client does not invent or rename fields.
+
+No API key is read, stored, or sent anywhere.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://optionsahoy.com"
+DEFAULT_TIMEOUT = 30.0
+
+
+class OptionsAhoyError(Exception):
+    """Raised when the OptionsAhoy API returns an HTTP error or an unusable response.
+
+    Attributes:
+        status_code: HTTP status code, when one is available.
+        payload: Parsed error body (typically ``{"error": "..."}``), when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        payload: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+def _drop_none(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Strip keys whose value is None so optional, unset fields are not posted.
+
+    ``terminationDate`` is intentionally kept even when None: the AMT/ISO schema
+    requires it and treats null as a meaningful "no termination" value.
+    """
+    keep_null = {"terminationDate"}
+    return {k: v for k, v in payload.items() if v is not None or k in keep_null}
+
+
+class OptionsAhoyClient:
+    """Synchronous client wrapping the OptionsAhoy calculator endpoints.
+
+    Example:
+        >>> client = OptionsAhoyClient()
+        >>> result = client.qsbs(
+        ...     acquisitionDate="2018-01-01",
+        ...     saleDate="2026-02-01",
+        ...     entityType="us-c-corp",
+        ...     acquisitionMethod="original-issuance",
+        ...     assetCategory="under-50m",
+        ...     industry="tech-software",
+        ...     activeBusiness="yes",
+        ...     adjustedBasis=10000,
+        ...     expectedGain=2000000,
+        ...     stateCode="CA",
+        ...     ordinaryIncome=250000,
+        ...     filingStatus="single",
+        ... )
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "OptionsAhoyClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- transport ---------------------------------------------------------
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        body = _drop_none(payload)
+        try:
+            response = self._client.post(url, json=body)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail: Any = None
+            try:
+                detail = exc.response.json()
+            except Exception:  # noqa: BLE001 - body may not be JSON
+                detail = exc.response.text
+            message = f"OptionsAhoy request to {path} failed ({exc.response.status_code})"
+            if isinstance(detail, dict) and detail.get("error"):
+                message = f"{message}: {detail['error']}"
+            raise OptionsAhoyError(
+                message, status_code=exc.response.status_code, payload=detail
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise OptionsAhoyError(f"OptionsAhoy request to {path} failed: {exc}") from exc
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise OptionsAhoyError(
+                f"OptionsAhoy response from {path} was not valid JSON"
+            ) from exc
+
+    # -- endpoints ---------------------------------------------------------
+
+    def amt_iso(
+        self,
+        *,
+        shares: int,
+        strike: float,
+        fmv: float,
+        filingStatus: str,
+        ordinaryIncome: float,
+        stateCode: str,
+        carryforwardCredit: float,
+        horizon: int,
+        cashReturnRate: float,
+        grantDate: str,
+        hasLeftCompany: bool,
+        terminationDate: Optional[str],
+        expectedGrowth: Optional[float] = None,
+        ticker: Optional[str] = None,
+        volatilityDrag: Optional[float] = None,
+        volatility: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Optimize a multi-year incentive stock option (ISO) exercise schedule under the
+        alternative minimum tax (AMT)."""
+        return self._post(
+            "/api/v1/amt-iso",
+            {
+                "shares": shares,
+                "strike": strike,
+                "fmv": fmv,
+                "filingStatus": filingStatus,
+                "ordinaryIncome": ordinaryIncome,
+                "stateCode": stateCode,
+                "carryforwardCredit": carryforwardCredit,
+                "horizon": horizon,
+                "cashReturnRate": cashReturnRate,
+                "grantDate": grantDate,
+                "hasLeftCompany": hasLeftCompany,
+                "terminationDate": terminationDate,
+                "expectedGrowth": expectedGrowth,
+                "ticker": ticker,
+                "volatilityDrag": volatilityDrag,
+                "volatility": volatility,
+            },
+        )
+
+    def nso(
+        self,
+        *,
+        shares: int,
+        strike: float,
+        currentPrice: float,
+        ordinaryIncome: float,
+        filingStatus: str,
+        stateCode: str,
+        stillEmployed: bool,
+        holdYears: float,
+        holdFunding: str,
+        expectedSalePrice: Optional[float] = None,
+        haircut: Optional[float] = None,
+        volatility: Optional[float] = None,
+        expectedMarketReturn: Optional[float] = None,
+        ticker: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Compute the tax and after-tax proceeds of exercising non-qualified stock
+        options (NSOs) and holding versus selling."""
+        return self._post(
+            "/api/v1/nso",
+            {
+                "shares": shares,
+                "strike": strike,
+                "currentPrice": currentPrice,
+                "ordinaryIncome": ordinaryIncome,
+                "filingStatus": filingStatus,
+                "stateCode": stateCode,
+                "stillEmployed": stillEmployed,
+                "holdYears": holdYears,
+                "holdFunding": holdFunding,
+                "expectedSalePrice": expectedSalePrice,
+                "haircut": haircut,
+                "volatility": volatility,
+                "expectedMarketReturn": expectedMarketReturn,
+                "ticker": ticker,
+            },
+        )
+
+    def rsu_sell_vs_hold(
+        self,
+        *,
+        shares: int,
+        currentPrice: float,
+        ordinaryIncome: float,
+        filingStatus: str,
+        stateCode: str,
+        stillEmployed: bool,
+        holdYears: float,
+        expectedSalePrice: Optional[float] = None,
+        haircut: Optional[float] = None,
+        volatility: Optional[float] = None,
+        expectedMarketReturn: Optional[float] = None,
+        ticker: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Compare selling vested restricted stock units (RSUs) at vest against holding
+        them, on an after-tax, risk-adjusted basis."""
+        return self._post(
+            "/api/v1/rsu-sell-vs-hold",
+            {
+                "shares": shares,
+                "currentPrice": currentPrice,
+                "ordinaryIncome": ordinaryIncome,
+                "filingStatus": filingStatus,
+                "stateCode": stateCode,
+                "stillEmployed": stillEmployed,
+                "holdYears": holdYears,
+                "expectedSalePrice": expectedSalePrice,
+                "haircut": haircut,
+                "volatility": volatility,
+                "expectedMarketReturn": expectedMarketReturn,
+                "ticker": ticker,
+            },
+        )
+
+    def concentration(
+        self,
+        *,
+        positionValue: float,
+        costBasis: float,
+        acquisitionDate: str,
+        sector: str,
+        stateCode: str,
+        filingStatus: str,
+        ordinaryIncome: float,
+        totalAssets: float,
+        expectedPositionReturn: Optional[float] = None,
+        expectedMarketReturn: Optional[float] = None,
+        ticker: Optional[str] = None,
+        volatilityDrag: Optional[float] = None,
+        volatility: Optional[float] = None,
+        hedgeChoice: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Analyze a concentrated single-stock position and the after-tax cost of
+        diversifying it."""
+        return self._post(
+            "/api/v1/concentration",
+            {
+                "positionValue": positionValue,
+                "costBasis": costBasis,
+                "acquisitionDate": acquisitionDate,
+                "sector": sector,
+                "stateCode": stateCode,
+                "filingStatus": filingStatus,
+                "ordinaryIncome": ordinaryIncome,
+                "totalAssets": totalAssets,
+                "expectedPositionReturn": expectedPositionReturn,
+                "expectedMarketReturn": expectedMarketReturn,
+                "ticker": ticker,
+                "volatilityDrag": volatilityDrag,
+                "volatility": volatility,
+                "hedgeChoice": hedgeChoice,
+            },
+        )
+
+    def protective_put(
+        self,
+        *,
+        positionValue: float,
+        sector: str,
+        protectionLevel: float,
+        tenorYears: float,
+        volatility: Optional[float] = None,
+        expectedReturn: Optional[float] = None,
+        tickerLabel: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Price a protective put hedge for a stock position at a given downside
+        protection level and tenor."""
+        return self._post(
+            "/api/v1/protective-put",
+            {
+                "positionValue": positionValue,
+                "sector": sector,
+                "protectionLevel": protectionLevel,
+                "tenorYears": tenorYears,
+                "volatility": volatility,
+                "expectedReturn": expectedReturn,
+                "tickerLabel": tickerLabel,
+            },
+        )
+
+    def qsbs(
+        self,
+        *,
+        acquisitionDate: str,
+        saleDate: str,
+        entityType: str,
+        acquisitionMethod: str,
+        assetCategory: str,
+        industry: str,
+        activeBusiness: str,
+        adjustedBasis: float,
+        expectedGain: float,
+        stateCode: str,
+        ordinaryIncome: float,
+        filingStatus: str,
+    ) -> Dict[str, Any]:
+        """Check qualified small business stock (QSBS) eligibility and the resulting
+        federal and state capital-gains exclusion."""
+        return self._post(
+            "/api/v1/qsbs",
+            {
+                "acquisitionDate": acquisitionDate,
+                "saleDate": saleDate,
+                "entityType": entityType,
+                "acquisitionMethod": acquisitionMethod,
+                "assetCategory": assetCategory,
+                "industry": industry,
+                "activeBusiness": activeBusiness,
+                "adjustedBasis": adjustedBasis,
+                "expectedGain": expectedGain,
+                "stateCode": stateCode,
+                "ordinaryIncome": ordinaryIncome,
+                "filingStatus": filingStatus,
+            },
+        )
+
+    def equity_funding(
+        self,
+        *,
+        targetAfterTax: float,
+        targetDate: str,
+        ordinaryIncome: float,
+        filingStatus: str,
+        stateCode: str,
+        stacks: Optional[List[Dict[str, Any]]] = None,
+        lots: Optional[List[Dict[str, Any]]] = None,
+        currentPrice: Optional[float] = None,
+        expectedAnnualGrowth: Optional[float] = None,
+        cashInterestRate: Optional[float] = None,
+        riskToleranceShortfall: Optional[float] = None,
+        defaultVolatility: Optional[float] = None,
+        today: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Plan which equity lots to sell, and when, to fund a cash goal by a target date
+        with the least after-tax cost. Provide ``stacks`` (preferred) or the legacy
+        ``lots`` plus ``currentPrice``."""
+        return self._post(
+            "/api/v1/equity-funding",
+            {
+                "targetAfterTax": targetAfterTax,
+                "targetDate": targetDate,
+                "ordinaryIncome": ordinaryIncome,
+                "filingStatus": filingStatus,
+                "stateCode": stateCode,
+                "stacks": stacks,
+                "lots": lots,
+                "currentPrice": currentPrice,
+                "expectedAnnualGrowth": expectedAnnualGrowth,
+                "cashInterestRate": cashInterestRate,
+                "riskToleranceShortfall": riskToleranceShortfall,
+                "defaultVolatility": defaultVolatility,
+                "today": today,
+            },
+        )

optionsahoy-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "optionsahoy"
+version = "0.1.0"
+description = "Thin Python client for the OptionsAhoy keyless public equity-compensation REST API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AlphaLatitude Inc." }]
+keywords = ["equity-compensation", "iso", "amt", "nso", "rsu", "qsbs", "options"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://optionsahoy.com"
+Repository = "https://github.com/AlvisoOculus/optionsahoy-mcp"
+Documentation = "https://optionsahoy.com/for-agents"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "respx>=0.21", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["optionsahoy"]
+
+[tool.pytest.ini_options]
+markers = [
+    "live: hits the real OptionsAhoy API (skipped unless OA_LIVE=1 is set).",
+]
+
+[tool.ruff]
+line-length = 100

optionsahoy-0.1.0/tests/test_client.py

@@ -0,0 +1,217 @@
+"""Mocked-transport tests for the OptionsAhoy client.
+
+The HTTP layer is mocked with respx so each test asserts the method posts to the
+correct path with the correct JSON body and parses the response, without hitting
+the network.
+"""
+
+import os
+
+import httpx
+import pytest
+import respx
+
+from optionsahoy import OptionsAhoyClient, OptionsAhoyError
+
+BASE = "https://optionsahoy.com"
+
+# Minimal, schema-valid kwargs per endpoint. Method name -> (path, kwargs).
+CASES = {
+    "amt_iso": (
+        "/api/v1/amt-iso",
+        dict(
+            shares=1000,
+            strike=2.0,
+            fmv=20.0,
+            filingStatus="single",
+            ordinaryIncome=200000,
+            stateCode="CA",
+            carryforwardCredit=0,
+            horizon=5,
+            cashReturnRate=0.04,
+            grantDate="2021-01-01",
+            hasLeftCompany=False,
+            terminationDate=None,
+        ),
+    ),
+    "nso": (
+        "/api/v1/nso",
+        dict(
+            shares=1000,
+            strike=2.0,
+            currentPrice=20.0,
+            ordinaryIncome=200000,
+            filingStatus="single",
+            stateCode="CA",
+            stillEmployed=True,
+            holdYears=2,
+            holdFunding="cash",
+        ),
+    ),
+    "rsu_sell_vs_hold": (
+        "/api/v1/rsu-sell-vs-hold",
+        dict(
+            shares=500,
+            currentPrice=50.0,
+            ordinaryIncome=200000,
+            filingStatus="single",
+            stateCode="CA",
+            stillEmployed=True,
+            holdYears=1,
+        ),
+    ),
+    "concentration": (
+        "/api/v1/concentration",
+        dict(
+            positionValue=500000,
+            costBasis=50000,
+            acquisitionDate="2020-01-01",
+            sector="tech_software",
+            stateCode="CA",
+            filingStatus="single",
+            ordinaryIncome=200000,
+            totalAssets=800000,
+        ),
+    ),
+    "protective_put": (
+        "/api/v1/protective-put",
+        dict(
+            positionValue=500000,
+            sector="tech_software",
+            protectionLevel=0.1,
+            tenorYears=1,
+        ),
+    ),
+    "qsbs": (
+        "/api/v1/qsbs",
+        dict(
+            acquisitionDate="2018-01-01",
+            saleDate="2026-02-01",
+            entityType="us-c-corp",
+            acquisitionMethod="original-issuance",
+            assetCategory="under-50m",
+            industry="tech-software",
+            activeBusiness="yes",
+            adjustedBasis=10000,
+            expectedGain=2000000,
+            stateCode="CA",
+            ordinaryIncome=250000,
+            filingStatus="single",
+        ),
+    ),
+    "equity_funding": (
+        "/api/v1/equity-funding",
+        dict(
+            targetAfterTax=200000,
+            targetDate="2027-01-01",
+            ordinaryIncome=200000,
+            filingStatus="single",
+            stateCode="CA",
+            stacks=[
+                {
+                    "currentPrice": 50.0,
+                    "lots": [
+                        {
+                            "shares": 1000,
+                            "costBasisPerShare": 10.0,
+                            "acquisitionDate": "2021-01-01",
+                        }
+                    ],
+                }
+            ],
+        ),
+    ),
+}
+
+
+@pytest.fixture
+def client():
+    return OptionsAhoyClient()
+
+
+@pytest.mark.parametrize("method_name", list(CASES))
+@respx.mock
+def test_method_posts_correct_path_and_body(client, method_name):
+    path, kwargs = CASES[method_name]
+    sentinel = {"ok": True, "result": {"method": method_name}}
+    route = respx.post(f"{BASE}{path}").mock(
+        return_value=httpx.Response(200, json=sentinel)
+    )
+
+    result = getattr(client, method_name)(**kwargs)
+
+    assert route.called
+    assert result == sentinel
+    request = route.calls.last.request
+    import json
+
+    sent = json.loads(request.content)
+    # Every supplied kwarg (None stripped, except terminationDate) is in the body.
+    for key, value in kwargs.items():
+        if value is None and key != "terminationDate":
+            continue
+        assert sent[key] == value
+
+
+@respx.mock
+def test_none_optionals_are_stripped(client):
+    route = respx.post(f"{BASE}/api/v1/nso").mock(
+        return_value=httpx.Response(200, json={"ok": True})
+    )
+    client.nso(**CASES["nso"][1])
+    import json
+
+    sent = json.loads(route.calls.last.request.content)
+    assert "haircut" not in sent
+    assert "ticker" not in sent
+
+
+@respx.mock
+def test_termination_date_null_is_kept(client):
+    route = respx.post(f"{BASE}/api/v1/amt-iso").mock(
+        return_value=httpx.Response(200, json={"ok": True})
+    )
+    client.amt_iso(**CASES["amt_iso"][1])
+    import json
+
+    sent = json.loads(route.calls.last.request.content)
+    assert "terminationDate" in sent
+    assert sent["terminationDate"] is None
+
+
+@respx.mock
+def test_http_error_raises_optionsahoy_error(client):
+    respx.post(f"{BASE}/api/v1/qsbs").mock(
+        return_value=httpx.Response(400, json={"error": "bad input"})
+    )
+    with pytest.raises(OptionsAhoyError) as exc:
+        client.qsbs(**CASES["qsbs"][1])
+    assert exc.value.status_code == 400
+    assert exc.value.payload == {"error": "bad input"}
+    assert "bad input" in str(exc.value)
+
+
+@respx.mock
+def test_non_json_response_raises(client):
+    respx.post(f"{BASE}/api/v1/nso").mock(
+        return_value=httpx.Response(200, text="not json")
+    )
+    with pytest.raises(OptionsAhoyError):
+        client.nso(**CASES["nso"][1])
+
+
+def test_custom_base_url_strips_trailing_slash():
+    c = OptionsAhoyClient(base_url="https://example.test/")
+    assert c.base_url == "https://example.test"
+
+
+# --- live smoke -----------------------------------------------------------
+
+
+@pytest.mark.live
+@pytest.mark.skipif(os.environ.get("OA_LIVE") != "1", reason="set OA_LIVE=1 to run")
+def test_live_qsbs_returns_top_level_key():
+    client = OptionsAhoyClient()
+    result = client.qsbs(**CASES["qsbs"][1])
+    assert isinstance(result, dict)
+    assert "ok" in result or "result" in result, result