arcade-optionsahoy 0.1.7

Arcade toolkit for the OptionsAhoy equity-compensation calculators.

arcade-optionsahoy

An Arcade toolkit for the OptionsAhoy equity-compensation calculators. One @tool-decorated function per OptionsAhoy REST endpoint, built on the keyless optionsahoy client and the arcade-tdk Tool Development Kit. No OptionsAhoy account, no application programming interface (API) key, full federal tax code plus all 50 states and the District of Columbia (DC).

Why not just ask the model?

We benchmarked five frontier large language models (LLMs), 3 runs each, 15 trials total, on the same multi-year incentive stock option (ISO) exercise problem. Every trial overshot the true after-tax outcome, by 2x to 20x. See the benchmark, updated for the latest models, at https://optionsahoy.com/benchmark. Multi-year scheduling has a search space larger than an LLM can reason through in-context; these tools return the verifiable answer instead.

Raw responses and scoring: llm-iso-benchmark. Full write-up: But can it do taxes though?.

Verified

Beyond determinism, the tax math is independently verified, every release: every 2026 federal constant matches its IRS Rev. Proc. 2025-32 value, worked federal cases reproduce to the cent against the independently-maintained PSL Tax-Calculator, and state tax reproduces to the cent against OpenTaxSolver across CA, NY, NJ, PA, and MA, with the headline answer recomputed live in your browser. Proof, shown beside the public sources: https://optionsahoy.com/verification

What it provides

The toolkit exposes seven Arcade tools, each a @tool-decorated function with typing.Annotated parameters mirroring its endpoint:

• AmtIsoOptimize - multi-year ISO exercise optimizer under the alternative minimum tax (AMT)
• NsoCalculate - non-qualified stock option (NSO) exercise tax, sell-at-exercise versus hold
• RsuSellVsHold - restricted stock unit (RSU) sell at vest versus hold for long-term capital gains
• ConcentrationAnalyze - single-stock concentration risk and the after-tax cost of diversifying
• ProtectivePutPrice - protective put and zero-cost collar pricing
• QsbsCheck - qualified small business stock (QSBS) Section 1202 eligibility and exclusion
• EquityFundingPlan - multi-year plan to fund a cash goal from equity by a target date

Coverage spans the full federal tax code plus all 50 states and DC. The toolkit pulls in the keyless optionsahoy client automatically. No API key is read, stored, or sent anywhere. Set OPTIONSAHOY_BASE_URL to point the tools at a different host.

Tools: inputs and outputs

Each tool's parameters list the required fields below; every tool also accepts optional forward-looking fields (such as expected_sale_price, volatility, expected_market_return) and, where noted, a convenience ticker so the API can derive forward-looking inputs from that symbol. Returns are the top-level fields of the response, wrapped as {"ok": true, "result": {...}}; the fields below are those of result.

AmtIsoOptimize

Optimizes a multi-year incentive stock option (ISO) exercise schedule under the alternative minimum tax (AMT): how many shares to exercise each year so the after-tax outcome is best.

• Inputs (required): shares, strike (USD), fmv (USD), filing_status (single | married_joint | head_household), ordinary_income (USD), state_code (two-letter, or DC), carryforward_credit (USD), horizon (1 to 10), cash_return_rate (decimal), grant_date (YYYY-MM-DD), has_left_company (boolean), termination_date (YYYY-MM-DD, or null if still employed).
• Optional: expected_growth (decimal), volatility (decimal), volatility_drag (0 to 0.99), ticker (covered public symbol).
• Returns: crossoverShares and crossoverBargain (where AMT starts to bite this year); alreadyInAmt and stateHasAmt (booleans); bargainPerShare; effectiveHorizon; timing (key dates); and schedules with three strategies lumpSum, evenSplit, and optimized, each carrying per-year tax, AMT owed and credit, long-term capital-gains tax at final sale, and nfv (net future value).

NsoCalculate

Computes the tax and after-tax proceeds of exercising non-qualified stock options (NSOs), comparing selling at exercise against holding for later long-term capital gains.

• Inputs (required): shares, strike (USD), current_price (USD), ordinary_income (USD), filing_status, state_code, still_employed (boolean), hold_years (at least 1), hold_funding (sell-to-cover | cash).
• Optional: expected_sale_price (USD), haircut (0 to 1), volatility (decimal), expected_market_return (decimal), ticker.
• Returns: exercise (ordinary income and taxes at exercise, plus net cash if you sell every share); bracketJump; hold (the hold-and-sell-later path); sellNowInvest (sell now and invest the proceeds); holdMinusCashless (positive favors holding).

RsuSellVsHold

Compares selling vested restricted stock units (RSUs) at vest against holding them, on an after-tax, risk-adjusted basis.

• Inputs (required): shares, current_price (USD), ordinary_income (USD), filing_status, state_code, still_employed (boolean), hold_years (0.25 to 5).
• Optional: expected_sale_price (USD), haircut (0 to 1), volatility (decimal), expected_market_return (decimal), ticker.
• Returns: vest (taxes due at vest); bracketJump; hold; sellNowInvest; holdMinusSell (positive favors holding).

ConcentrationAnalyze

Quantifies single-stock concentration risk and compares the after-tax cost of three responses: sell down, hold, or hedge.

• Inputs (required): position_value (USD), cost_basis (USD), acquisition_date (YYYY-MM-DD), sector (one of tech_software, semiconductors, consumer_cyclical, consumer_defensive, financials, healthcare_biotech, energy, industrials, communication, broad_market), state_code, filing_status, ordinary_income (USD), total_assets (USD).
• Optional: expected_position_return and expected_market_return (decimals), or ticker; volatility (decimal), volatility_drag (0 to 0.99), hedge_choice ({kind, protectionLevel, tenorYears, upsideCapPct}).
• Returns: concentration (0 to 1); riskBand; isLongTermToday, longTermDate, daysUntilLongTerm; lossExposure[]; schedule[] (after-tax sell-down plans); hedging (present when hedge_choice is given); sectorContextLine and advisorBenchmarkLine.

ProtectivePutPrice

Prices a protective put and a zero-cost collar for a stock position at a chosen downside-protection level and tenor.

• Inputs (required): position_value (USD), sector (same set as concentration), protection_level (0.05 to 0.5), tenor_years (at least 0.25).
• Optional: volatility (decimal), expected_return (decimal), ticker_label.
• Returns: inputs; riskFreeRate and realWorldDrift; barePut (the put alone); collar (put financed by selling a call, with upsideCap and isZeroCost); payoffTable[]; payoffRange; recommended (bare-put | collar | none).

QsbsCheck

Checks qualified small business stock (QSBS) Section 1202 eligibility and computes the resulting federal capital-gains exclusion.

• Inputs (required): acquisition_date and sale_date (YYYY-MM-DD), entity_type (us-c-corp | other), acquisition_method (original-issuance | gift-or-inheritance | secondary | unsure), asset_category (under-50m | 50m-to-75m | over-75m | unsure), industry (see the tool docstring for the full enum), active_business (yes | no | unsure), adjusted_basis (USD), expected_gain (USD), state_code, ordinary_income (USD), filing_status.
• Returns: verdict; exclusionPercent (0 to 1); perIssuerCap, tenXBasisCap, applicableCap; excludableGain and taxableGain; federalTaxSaved; stateConforms and stateNote; holdingYears; yearsUntilFullExclusion; era; tests[].

EquityFundingPlan

Plans which equity lots to sell, and when, to fund a cash goal by a target date at the least after-tax cost, accounting for holding-period thresholds and shortfall risk.

• Inputs (required): target_after_tax (USD), target_date (YYYY-MM-DD), ordinary_income (USD), filing_status, state_code, plus the holdings as either stacks (preferred: a list of stacks, each with currentPrice and a lots list of {shares, costBasisPerShare, acquisitionDate, vestDate?}) or the legacy lots plus a single current_price.
• Optional: expected_annual_growth (decimal), cash_interest_rate (decimal), risk_tolerance_shortfall (0 to 1), default_volatility (decimal), today (YYYY-MM-DD).
• Returns: four named plans recommended, lockInNow, balanced, holdForGrowth, plus frontier[], and the echoed targetAfterTax, targetDateISO, appliedRiskTolerance. Each plan carries wealthAtTarget, totalTax, shortfallProbability, and a plan with feasible, schedule (per-year sales), comparison, and remainingShares.

The authoritative request schemas are the OpenAPI spec at https://optionsahoy.com/openapi.json and the agent docs at https://optionsahoy.com/for-agents.

Install

pip install arcade-optionsahoy

Quickstart

The toolkit is a standard Arcade toolkit: load it into a ToolCatalog and serve it, or run it in your own MCP server. To inspect the registered tools:

from arcade_tdk import ToolCatalog
import arcade_optionsahoy

catalog = ToolCatalog()
catalog.add_module(arcade_optionsahoy)

print(len(catalog))                 # 7
print([t.definition.name for t in catalog])

To run the tools through the Arcade engine, install the Arcade CLI and follow the Creating a Toolkit guide, which loads installed toolkit packages by name. You can also call any tool directly as a plain Python function:

from arcade_optionsahoy import qsbs_check

result = qsbs_check(
    acquisition_date="2018-01-01",
    sale_date="2026-02-01",
    entity_type="us-c-corp",
    acquisition_method="original-issuance",
    asset_category="under-50m",
    industry="tech-software",
    active_business="yes",
    adjusted_basis=10000,
    expected_gain=2000000,
    state_code="CA",
    ordinary_income=250000,
    filing_status="single",
)
print(result["result"]["verdict"])

The seven endpoints accept forward-looking fields (such as expected_sale_price or volatility) that the schema marks optional but the API requires at call time; set a covered ticker (for example "NVDA") to let the API derive them, or pass explicit values. Omitting both returns a clear 400 explaining which field is needed.

Runnable example and source

• Runnable example: examples/
• Source: integrations/python/arcade-optionsahoy

Related

Sibling packages wrapping the same calculators:

• optionsahoy - plain Python client (no framework)
• crewai-optionsahoy - CrewAI tools
• optionsahoy-langchain - LangChain tools
• llama-index-tools-optionsahoy - LlamaIndex tools

Other surfaces for the same calculators:

• Hosted Model Context Protocol (MCP) server: https://optionsahoy.com/mcp
• Agent integration docs: https://optionsahoy.com/for-agents
• Free in-browser calculators: https://optionsahoy.com/tools

Built by AlphaLatitude Inc., the company behind OptionsAhoy.