OptionsAhoy Concentration API
Single-stock concentration risk
Operations 1
Documentation
Documentation
https://optionsahoy.com/for-agents
APIReference
https://optionsahoy.com/for-agents/api
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/optionsahoy-com-concentration-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: OptionsAhoy Calculator Concentration API
summary: Deterministic equity-compensation calculator endpoints. JSON in, JSON out.
description: Multi-year equity-compensation optimization engine.
version: 1.10.1
contact:
name: AlphaLatitude Inc.
email: andrew@alphalatitude.com
url: https://optionsahoy.com/for-agents
license:
name: Proprietary. Free for non-commercial use during beta.
url: https://optionsahoy.com/terms
servers:
- url: https://optionsahoy.com
description: Production
tags:
- name: Concentration
description: Single-stock concentration risk
paths:
/api/v1/concentration:
post:
summary: Single-stock concentration risk
description: 'Quantifies single-stock concentration risk: drawdown exposure at 30/50/70% scenarios and the after-tax comparison of selling down vs. holding vs. hedging, with multi-year tax math.'
operationId: calculateConcentration
tags:
- Concentration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConcentrationInput'
example:
positionValue: 400000
costBasis: 100000
acquisitionDate: '2022-01-01'
sector: tech_software
stateCode: CA
filingStatus: single
ordinaryIncome: 200000
totalAssets: 1200000
volatility: 0.45
expectedPositionReturn: 0.1
expectedMarketReturn: 0.07
responses:
'200':
$ref: '#/components/responses/ConcentrationSuccess'
'400':
$ref: '#/components/responses/BadRequest'
'405':
$ref: '#/components/responses/MethodNotAllowed'
components:
schemas:
FilingStatus:
type: string
enum:
- single
- married_joint
- head_household
description: United States federal filing status.
ConcentrationResult:
type: object
description: Single-stock concentration analysis. All dollar amounts are USD.
properties:
concentration:
type: number
description: Position value / total assets, 0..1.
riskBand:
type: string
enum:
- Low
- Moderate
- Concentrated
- Highly concentrated
- Extreme
description: Qualitative concentration band for the position weight.
isLongTermToday:
type: boolean
description: True when the position already qualifies for long-term capital gains treatment.
longTermDate:
type: string
description: Date the position turns long-term (acquisitionDate + 1 year). ISO 8601 date-time string.
daysUntilLongTerm:
type: number
description: Days until long-term treatment; 0 when already long-term.
lossExposure:
type: array
description: Dollar damage at 30/50/70% single-stock drawdowns.
items:
type: object
properties:
drop:
type: number
description: Modeled drawdown as a fraction of position value (0.30, 0.50, 0.70).
dollarLoss:
type: number
description: Dollars lost at this drawdown.
newConcentration:
type: number
description: Portfolio concentration (0..1) after the drawdown.
required:
- drop
- dollarLoss
- newConcentration
waitForLtInsight:
type:
- object
- 'null'
description: Tax saved by waiting for long-term treatment before selling; null when already long-term or no sale is needed.
properties:
longTermDate:
type: string
description: Date the position turns long-term. ISO 8601 date-time string.
daysAway:
type: number
description: Days until that date.
immediateLumpSumTax:
type: number
description: Tax in dollars on the full sell-down executed today (short-term rates).
delayedLumpSumTax:
type: number
description: Tax in dollars on the same sale executed after the long-term date.
savings:
type: number
description: immediateLumpSumTax - delayedLumpSumTax in dollars (floored at 0).
required:
- longTermDate
- daysAway
- immediateLumpSumTax
- delayedLumpSumTax
- savings
schedule:
type: array
description: Sell-down plans over 1, 2, and 3 years; empty when the position is already at or below the target weight.
items:
type: object
properties:
planKey:
type: string
enum:
- lump_sum
- two_year
- three_year
description: Plan identifier.
planLabel:
type: string
description: Human-readable plan name, e.g. "Sell over 2 years".
yearlySales:
type: array
description: 'One entry per sale year: year (1-indexed), saleAmount, gainAmount, isLongTerm, federalTax, stateTax, totalTax in dollars, plus a per-slice breakdown.'
items:
type: object
properties:
year:
type: number
description: Sale year, 1-indexed.
saleAmount:
type: number
description: Dollars sold this year.
gainAmount:
type: number
description: Taxable gain in dollars within the sale.
isLongTerm:
type: boolean
description: True when this sale gets long-term capital gains treatment.
federalTax:
type: number
description: Federal tax in dollars on this sale (including NIIT).
stateTax:
type: number
description: State tax in dollars on this sale.
totalTax:
type: number
description: Total tax in dollars on this sale.
breakdown:
type: array
items:
type: object
description: 'One tax slice: a dollar amount taxed at one rate.'
properties:
label:
type: string
description: Tax line label, e.g. "Federal LTCG", "NIIT", "California".
rate:
type: number
description: Rate applied to this slice as a decimal (0.15 = 15%).
amount:
type: number
description: Dollars of gain in this slice.
tax:
type: number
description: 'Tax in dollars: amount x rate.'
required:
- label
- rate
- amount
- tax
description: Per-rate tax slices for this sale.
required:
- year
- saleAmount
- gainAmount
- isLongTerm
- federalTax
- stateTax
- totalTax
- breakdown
totalSale:
type: number
description: Total nominal sale dollars across the plan years.
totalTax:
type: number
description: Total tax in dollars across the plan years.
endOfHorizonWealth:
type: number
description: Total after-tax wealth in dollars at the end of the 3-year comparison horizon.
savingsVsLumpSum:
type: number
description: Raw tax saved in dollars vs selling everything today; positive means this plan pays less tax.
wealthVsLumpSum:
type: number
description: End-of-horizon wealth delta in dollars vs the sell-everything-today baseline; positive means this plan ends wealthier.
year1IsShortTerm:
type: boolean
description: True when the first sale year would be taxed at short-term rates.
taxBreakdown:
type: array
items:
type: object
description: 'One tax slice: a dollar amount taxed at one rate.'
properties:
label:
type: string
description: Tax line label, e.g. "Federal LTCG", "NIIT", "California".
rate:
type: number
description: Rate applied to this slice as a decimal (0.15 = 15%).
amount:
type: number
description: Dollars of gain in this slice.
tax:
type: number
description: 'Tax in dollars: amount x rate.'
required:
- label
- rate
- amount
- tax
description: Plan-total tax slices, same-rate rows merged.
wealthByYear:
type: array
items:
type: number
description: Total wealth in dollars at the end of each year, t = 0..3 (4 points). For charting.
required:
- planKey
- planLabel
- yearlySales
- totalSale
- totalTax
- endOfHorizonWealth
- savingsVsLumpSum
- wealthVsLumpSum
- year1IsShortTerm
- taxBreakdown
- wealthByYear
hedging:
type: object
description: Modeled cost of a protective hedge covering the full position. Defaults to a 1-year 30%-OTM put; if a `hedgeChoice` is supplied, this block prices that structure (kind / protectionLevel / tenorYears, plus a short call for a collar).
properties:
kind:
type: string
enum:
- put
- collar
description: 'Structure priced: "put" (default) or "collar" when a hedgeChoice with kind:"collar" and upsideCapPct was supplied.'
protectionLevel:
type: number
description: Floor as a fraction below spot (0.30 = a 30%-OTM put). Echoes hedgeChoice.protectionLevel, else 0.30.
tenorYears:
type: number
description: Hedge tenor in years. Echoes hedgeChoice.tenorYears, else 1.
strike:
type: number
description: Long put strike in dollars ((1 - protectionLevel) x position value).
putPrice:
type: number
description: Gross long-put premium in dollars for the tenor.
callStrike:
type: number
description: Collar short-call strike in dollars ((1 + upsideCapPct) x position value). Omitted for a put.
callPrice:
type: number
description: Collar short-call premium in dollars received. Omitted for a put.
netPremium:
type: number
description: 'Net premium paid in dollars: putPrice for a put, max(0, putPrice - callPrice) for a collar.'
sigma:
type: number
description: Annualized volatility used in pricing (explicit or ticker-implied vol, else a sector-typical implied volatility).
riskFreeRate:
type: number
description: Annualized risk-free rate used in pricing, as a decimal.
required:
- kind
- protectionLevel
- tenorYears
- strike
- putPrice
- netPremium
- sigma
- riskFreeRate
sectorContextLine:
type: string
description: One-line volatility/drawdown context for the chosen sector.
advisorBenchmarkLine:
type: string
description: One-line comparison of the user weight vs the common advisor 10% single-name guideline.
required:
- concentration
- riskBand
- isLongTermToday
- longTermDate
- daysUntilLongTerm
- lossExposure
- waitForLtInsight
- schedule
- hedging
- sectorContextLine
- advisorBenchmarkLine
ConcentrationInput:
type: object
required:
- positionValue
- costBasis
- acquisitionDate
- sector
- stateCode
- filingStatus
- ordinaryIncome
- totalAssets
properties:
positionValue:
type: number
minimum: 0
description: Current value of the concentrated position, USD.
costBasis:
type: number
minimum: 0
acquisitionDate:
$ref: '#/components/schemas/IsoDate'
sector:
$ref: '#/components/schemas/SectorKey'
stateCode:
$ref: '#/components/schemas/StateCode'
filingStatus:
$ref: '#/components/schemas/FilingStatus'
ordinaryIncome:
type: number
minimum: 0
totalAssets:
type: number
minimum: 0
description: Total investable portfolio in dollars (concentrated position + everything else). User-supplied; never inferred.
expectedPositionReturn:
type:
- number
- string
description: Annual return on the concentrated stock. Required unless `ticker` resolves it from trailing CAGR. Also accepts the string "market" to use the S&P 500 trailing average when the user has no view.
expectedMarketReturn:
type:
- number
- string
description: Annual return on diversified holdings + reinvested proceeds. Defaults to SPY trailing CAGR for the 3-year horizon if omitted. The string "market" names that same default explicitly.
ticker:
$ref: '#/components/schemas/Ticker'
volatilityDrag:
type: number
minimum: 0
maximum: 0.99
description: Multiplicative haircut on the 3y stock-price path. Either this OR `volatility` is required for drag; if both are supplied, `volatilityDrag` wins.
volatility:
type: number
minimum: 0
description: Annualized volatility (sigma). Used for the closed-form option pricing hedging path AND, when `volatilityDrag` is omitted, derives drag = 1 - exp(-(sigma^2 / 2) * 3). Either this OR `volatilityDrag` is required for drag.
maximum: 5
hedgeChoice:
type: object
required:
- kind
- protectionLevel
- tenorYears
properties:
kind:
type: string
enum:
- put
- collar
protectionLevel:
type: number
minimum: 0.05
maximum: 0.5
tenorYears:
type: number
minimum: 0.25
upsideCapPct:
type: number
IsoDate:
type: string
format: date
description: ISO 8601 date string (YYYY-MM-DD).
Ticker:
type: string
description: Optional public-stock symbol (e.g. "NVDA"). When set, the API substitutes the ticker's trailing CAGR for any unsupplied expected-return / sale-price field instead of requiring the caller to invent one. ~90 symbols covered; unknown tickers fall through to 'required field' 400 errors.
SectorKey:
type: string
enum:
- tech_software
- semiconductors
- consumer_cyclical
- consumer_defensive
- financials
- healthcare_biotech
- energy
- industrials
- communication
- broad_market
StateCode:
type: string
pattern: ^[A-Z]{2}$
description: Two-letter United States state code (e.g. CA, NY, TX).
responses:
MethodNotAllowed:
description: Endpoint accepts only POST (and OPTIONS for CORS preflight).
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
BadRequest:
description: Invalid input or calculation failure. The `error` string names the specific field or condition.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
ConcentrationSuccess:
description: Successful concentration_analyze result.
content:
application/json:
schema:
type: object
required:
- ok
- result
properties:
ok:
type: boolean
const: true
result:
$ref: '#/components/schemas/ConcentrationResult'
next_steps:
type: object
description: 'Constant per endpoint: the free interactive version of this calculator, related endpoints worth running next, and the OptionsAhoy beta for integrated multi-position optimization.'
properties:
web_tool:
type: string
also_run:
type: array
items:
type: string
beta:
type: string
example:
ok: true
result:
concentration: 0.3333333333333333
riskBand: Concentrated
isLongTermToday: true
longTermDate: '2023-01-02T00:00:00.000Z'
daysUntilLongTerm: 0
lossExposure:
- drop: 0.3
dollarLoss: 120000
newConcentration: 0.25925925925925924
- drop: 0.5
dollarLoss: 200000
newConcentration: 0.2
- drop: 0.7
dollarLoss: 280000
newConcentration: 0.13043478260869565
waitForLtInsight: null
schedule:
- planKey: lump_sum
planLabel: Sell over 1 year
yearlySales:
- year: 1
saleAmount: 399729.11491267144
gainAmount: 299729.11491267144
isLongTerm: true
federalTax: 56349.073603582234
stateTax: 29696.88998513187
totalTax: 86045.9635887141
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 299729.11491267144
tax: 44959.36723690072
- label: NIIT
rate: 0.038
amount: 299729.11491267144
tax: 11389.706366681514
- label: CA
rate: 0.093
amount: 171479
tax: 15947.547
- label: CA
rate: 0.103
amount: 74292
tax: 7652.076
- label: CA
rate: 0.113
amount: 53958.114912671444
tax: 6097.266985131873
totalSale: 399729.11491267144
totalTax: 86045.9635887141
endOfHorizonWealth: 1350554.3624649164
savingsVsLumpSum: 81.53641128589516
wealthVsLumpSum: -13987.346552583855
year1IsShortTerm: false
taxBreakdown:
- label: Federal LTCG
rate: 0.15
amount: 299729.11491267144
tax: 44959.36723690072
- label: NIIT
rate: 0.038
amount: 299729.11491267144
tax: 11389.706366681514
- label: CA
rate: 0.093
amount: 171479
tax: 15947.547
- label: CA
rate: 0.103
amount: 74292
tax: 7652.076
- label: CA
rate: 0.113
amount: 53958.114912671444
tax: 6097.266985131873
wealthByYear:
- 1200000
- 1179626.4848151945
- 1262200.338752258
- 1350554.3624649164
- planKey: two_year
planLabel: Sell over 2 years
yearlySales:
- year: 1
saleAmount: 199864.55745633572
gainAmount: 149864.55745633572
isLongTerm: true
federalTax: 28174.536801791117
stateTax: 13937.403843439228
totalTax: 42111.940645230345
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 149864.55745633572
tax: 22479.68361845036
- label: NIIT
rate: 0.038
amount: 149864.55745633572
tax: 5694.853183340757
- label: CA
rate: 0.093
amount: 149864.55745633572
tax: 13937.403843439222
- year: 2
saleAmount: 199614.72675951532
gainAmount: 149614.72675951532
isLongTerm: true
federalTax: 28127.568630788883
stateTax: 13914.16958863493
totalTax: 42041.738219423816
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 149614.72675951532
tax: 22442.2090139273
- label: NIIT
rate: 0.038
amount: 149614.72675951532
tax: 5685.359616861582
- label: CA
rate: 0.093
amount: 149614.72675951532
tax: 13914.169588634924
totalSale: 399479.28421585105
totalTax: 84153.67886465415
endOfHorizonWealth: 1340318.0844518472
savingsVsLumpSum: 1973.8211353458464
wealthVsLumpSum: -24223.624565653037
year1IsShortTerm: false
taxBreakdown:
- label: Federal LTCG
rate: 0.15
amount: 299479.28421585105
tax: 44921.892632377654
- label: NIIT
rate: 0.038
amount: 299479.28421585105
tax: 11380.212800202338
- label: CA
rate: 0.093
amount: 299479.28421585105
tax: 27851.573432074147
wealthByYear:
- 1200000
- 1218503.1623343432
- 1252633.723786773
- 1340318.0844518472
- planKey: three_year
planLabel: Sell over 3 years
yearlySales:
- year: 1
saleAmount: 133243.03830422385
gainAmount: 99909.70497089053
isLongTerm: true
federalTax: 18783.02453452742
stateTax: 9291.602562292821
totalTax: 28074.62709682024
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 99909.70497089053
tax: 14986.455745633579
- label: NIIT
rate: 0.038
amount: 99909.70497089053
tax: 3796.56878889384
- label: CA
rate: 0.093
amount: 99909.70497089053
tax: 9291.60256229282
- year: 2
saleAmount: 133076.48450634358
gainAmount: 99743.15117301025
isLongTerm: true
federalTax: 18751.712420525924
stateTax: 9276.113059089956
totalTax: 28027.82547961588
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 99743.15117301025
tax: 14961.472675951536
- label: NIIT
rate: 0.038
amount: 99743.15117301024
tax: 3790.239744574389
- label: CA
rate: 0.093
amount: 99743.15117301025
tax: 9276.113059089954
- year: 3
saleAmount: 132910.13890071065
gainAmount: 99576.80556737732
isLongTerm: true
federalTax: 18720.439446666936
stateTax: 9260.64291776609
totalTax: 27981.082364433027
breakdown:
- label: Federal LTCG
rate: 0.15
amount: 99576.80556737732
tax: 14936.520835106598
- label: NIIT
rate: 0.038
amount: 99576.8055673773
tax: 3783.9186115603375
- label: CA
rate: 0.093
amount: 99576.80556737732
tax: 9260.64291776609
totalSale: 399229.661711278
totalTax: 84083.53494086914
endOfHorizonWealth: 1328478.6892989082
savingsVsLumpSum: 2043.96505913086
wealthVsLumpSum: -36063.019718592055
year1IsShortTerm: false
taxBreakdown:
- label: Federal LTCG
rate: 0.15
amount: 299229.6617112781
tax: 44884.44925669171
- label: NIIT
rate: 0.038
amount: 299229.6617112781
tax: 11370.727145028566
- label: CA
rate: 0.093
amount: 299229.6617112781
tax: 27828.358539148863
wealthByYear:
- 1200000
- 1230835.441556229
- 1273396.0241911819
- 1328478.6892989082
hedging:
kind: put
protectionLevel: 0.30000000000000004
tenorYears: 1
strike: 280000
putPrice: 14759.629358774771
netPremium: 14759.629358774771
sigma: 0.45
riskFreeRate: 0.045
sectorContextLine: Tech / Software single names hit a 50%+ peak-to-trough drawdown in roughly 1 of every 5 rolling 3-year windows over 2014–2024. Even mega-caps aren’t exempt.
advisorBenchmarkLine: Most fee-only advisors target ≤10% in any single name. You're at 33%.
externalDocs:
description: Integration surface, citation guidance, and roadmap
url: https://optionsahoy.com/for-agents