The RsuLotOptimize API from OptionsAhoy — 1 operation(s) for rsulotoptimize.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/optionsahoy-com-rsulotoptimize-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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: 3.2.0
info:
title: OptionsAhoy Calculator Rsu Lot Optimize 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: RsuLotOptimize
paths:
/api/v1/rsu-lot-order:
post:
summary: 'RSU lot-order divest plan: which lots to sell, on which dates, at the lowest…'
description: 'Given vested RSU lots (vest date, shares, cost basis), a current price, and a divest fraction, chooses which lots and which sale dates minimize total tax to divest the target share count. Three levers: specific-lot identification, long-term deferral, and multi-year bracket spreading with in-plan capital-loss carryforward. Flat-price assumption (no growth model). Returns the year-by-year sell schedule, total tax (federal LTCG + NIIT + state), the saving versus a first-in-first-out (FIFO) sell order on the same schedule, a 1/2/3-year horizon trade-off, and per-lot deferral callouts.'
operationId: optimizeRsuLotOrder
tags:
- RsuLotOptimize
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RsuLotOptimizeInput'
example:
lots:
- vestDate: '2022-08-15'
shares: 120
costBasisPerShare: 95
- vestDate: '2024-02-15'
shares: 100
costBasisPerShare: 130
- vestDate: '2026-05-15'
shares: 80
costBasisPerShare: 210
currentPrice: 180
divestFraction: 0.5
horizonYears: 2
ordinaryIncome: 200000
filingStatus: single
stateCode: CA
responses:
'200':
$ref: '#/components/responses/RsuLotOptimizeSuccess'
'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.
IsoDate:
type: string
format: date
description: ISO 8601 date string (YYYY-MM-DD).
RsuLotOptimizeResult:
type: object
description: 'RSU lot-order divest plan: which lots to sell on which dates to divest the target share count at the lowest total tax, versus a first-in-first-out (FIFO) sell order. All dollar amounts are USD.'
properties:
sharesToSell:
type: number
description: Shares the plan divests (round(divestFraction x totalShares), floored at 1).
totalShares:
type: number
description: Total shares across all input lots.
totalGross:
type: number
description: Gross proceeds from the divested shares, in dollars.
totalTax:
type: number
description: Total plan tax across all years (federal LTCG + NIIT + state, net of in-plan loss carryforward), in dollars.
totalAfterTax:
type: number
description: After-tax proceeds from the divested shares, in dollars.
schedule:
type: array
items:
type: object
description: All sales in one tax year, after Schedule D netting.
properties:
year:
type: number
description: Calendar tax year.
sales:
type: array
items:
type: object
description: One vested lot sold, in whole or part, on one date.
properties:
lotIndex:
type: number
description: 0-based index into the input lots array this row draws from.
vestDate:
type: string
description: Vest (acquisition) date of the lot, ISO date-time string.
saleDate:
type: string
description: 'Date this block is sold, ISO date-time string: today, a long-term-crossing date, or Jan 2 of a later plan year.'
year:
type: number
description: Calendar tax year of the sale.
shares:
type: number
description: Shares sold in this row (may be fractional).
grossProceeds:
type: number
description: Gross sale proceeds in dollars (shares x current price; flat-price assumption).
gainAmount:
type: number
description: Realized capital gain, negative for a loss, in dollars.
isLongTerm:
type: boolean
description: True when the lot was held more than one year at the sale date (long-term capital gain).
taxAttributed:
type: number
description: Signed tax attributed to this row in dollars; a loss row is negative (the tax it removes).
required:
- lotIndex
- vestDate
- saleDate
- year
- shares
- grossProceeds
- gainAmount
- isLongTerm
- taxAttributed
description: Per-lot sale rows in this year.
netLong:
type: number
description: Net long-term gain or loss after netting, in dollars.
netShort:
type: number
description: Net short-term gain or loss after netting, in dollars.
tax:
type: number
description: Total tax for this year (federal + state + NIIT), in dollars.
effectiveRate:
type: number
description: Year tax divided by year net gain, 0..1.
carryforwardGenerated:
type: number
description: Capital loss carried into the next plan year from this year, in dollars (0 when the year nets positive).
required:
- year
- sales
- netLong
- netShort
- tax
- effectiveRate
- carryforwardGenerated
description: The sell plan, grouped by tax year.
keptUnrealizedGain:
type: number
description: Unrealized gain still carried by the shares NOT sold, in dollars (deferred, not eliminated).
carryforwardRemaining:
type: number
description: Capital loss remaining at the end of the plan horizon, in dollars (reported, not modeled into future years).
headlineAfterTaxKept:
type: number
description: 'After-tax proceeds under the plan, in dollars: the headline "you keep $X" figure.'
headlineDeltaVsFifo:
type: number
description: Dollars saved versus selling oldest-first (FIFO) on the SAME schedule. Pure lot-selection benefit; >= 0 by construction.
attribution:
type: object
description: Telescoping attribution of the total saving vs a FIFO-all-today sale. lotSelection + spreadingDeferral = total.
properties:
lotSelection:
type: number
description: Saving from choosing which lots to sell (equals headlineDeltaVsFifo), in dollars.
spreadingDeferral:
type: number
description: Saving from spreading sales across years and deferring for long-term status, in dollars. Can be <= 0 in loss-mix cases.
total:
type: number
description: Total saving vs selling oldest-first, all today, in dollars.
required:
- lotSelection
- spreadingDeferral
- total
horizonCards:
type: array
items:
type: object
description: Total tax and after-tax proceeds for the same divest target under a given horizon.
properties:
horizonYears:
type: number
description: Plan length in tax years (1 = sell all now, 2, or 3).
totalTax:
type: number
description: Total plan tax under this horizon, in dollars.
afterTaxKept:
type: number
description: After-tax proceeds from the divested shares under this horizon, in dollars.
required:
- horizonYears
- totalTax
- afterTaxKept
description: The same divest target under a 1-year ("all now"), 2-year, and 3-year plan, for the trade-off strip.
deferralCallouts:
type: array
items:
type: object
description: A short-term lot that becomes long-term if its sale waits past longTermDate.
properties:
lotIndex:
type: number
description: 0-based index into the input lots array.
longTermDate:
type: string
description: Date the lot becomes long-term, ISO date-time string (a sale strictly after the first vest anniversary).
daysToWait:
type: number
description: Days from the planned sale date to longTermDate.
taxSaved:
type: number
description: Tax saved by waiting for long-term treatment, in dollars.
amountAtRisk:
type: number
description: Position value kept exposed to the stock while waiting, in dollars.
required:
- lotIndex
- longTermDate
- daysToWait
- taxSaved
- amountAtRisk
description: Per-lot short-term-to-long-term deferral opportunities.
required:
- sharesToSell
- totalShares
- totalGross
- totalTax
- totalAfterTax
- schedule
- keptUnrealizedGain
- carryforwardRemaining
- headlineAfterTaxKept
- headlineDeltaVsFifo
- attribution
- horizonCards
- deferralCallouts
StateCode:
type: string
pattern: ^[A-Z]{2}$
description: Two-letter United States state code (e.g. CA, NY, TX).
RsuLotOptimizeInput:
type: object
description: Vested RSU lots + a divest fraction. Chooses which lots to sell on which dates to divest the target share count at the lowest computed tax.
required:
- lots
- currentPrice
- divestFraction
- horizonYears
- ordinaryIncome
- filingStatus
- stateCode
properties:
lots:
type: array
minItems: 1
maxItems: 20
description: Vested RSU lots you still hold, one per vest tranche. At most 20 per call, the same cap the web calculator uses. Combine tranches sharing a vest date and cost basis.
items:
type: object
required:
- vestDate
- shares
- costBasisPerShare
properties:
vestDate:
$ref: '#/components/schemas/IsoDate'
shares:
type: number
exclusiveMinimum: 0
description: Shares still held from this vest. Fractional allowed.
costBasisPerShare:
type: number
minimum: 0
description: Per-share cost basis, USD (the share price on vest day).
currentPrice:
type: number
minimum: 0
description: Current share price, USD. Every sale is priced at this value (flat-price assumption).
divestFraction:
type: number
minimum: 0.1
maximum: 1
description: Fraction of total shares to divest, as a decimal (0.5 = sell half). Range 0.10 to 1.0.
horizonYears:
type: integer
minimum: 1
maximum: 3
description: 'Tax years the plan may span: 1 (sell all now), 2, or 3.'
ordinaryIncome:
type: number
minimum: 0
description: 'Total household ordinary income for the year, USD. Taxable income after deductions, not gross wages: no standard or itemized deduction is applied. Sets the LTCG bracket floor, short-term rate, and NIIT threshold.'
filingStatus:
$ref: '#/components/schemas/FilingStatus'
stateCode:
$ref: '#/components/schemas/StateCode'
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
RsuLotOptimizeSuccess:
description: Successful rsu_lot_optimize result.
content:
application/json:
schema:
type: object
required:
- ok
- result
properties:
ok:
type: boolean
const: true
result:
$ref: '#/components/schemas/RsuLotOptimizeResult'
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:
sharesToSell: 150
totalShares: 300
totalGross: 27000
totalTax: 184.3000000000011
totalAfterTax: 26815.699999999997
schedule:
- year: 2026
sales:
- lotIndex: 2
vestDate: '2026-05-15T00:00:00.000Z'
saleDate: '2026-06-24T12:00:00.000Z'
year: 2026
shares: 80
grossProceeds: 14400
gainAmount: -2400
isLongTerm: false
taxAttributed: -799.1999999999989
netLong: 0
netShort: -2400
tax: -799.1999999999989
effectiveRate: -0.055499999999999924
carryforwardGenerated: 0
- year: 2027
sales:
- lotIndex: 1
vestDate: '2024-02-15T00:00:00.000Z'
saleDate: '2027-01-02T00:00:00.000Z'
year: 2027
shares: 70
grossProceeds: 12600
gainAmount: 3500
isLongTerm: true
taxAttributed: 983.5
netLong: 3500
netShort: 0
tax: 983.5
effectiveRate: 0.07805555555555556
carryforwardGenerated: 0
keptUnrealizedGain: 11700
carryforwardRemaining: 0
headlineAfterTaxKept: 26815.699999999997
headlineDeltaVsFifo: 3103.3999999999996
attribution:
lotSelection: 3103.3999999999996
spreadingDeferral: -4.547473508864641e-13
total: 3103.399999999999
horizonCards:
- horizonYears: 1
totalTax: 309.1000000000011
afterTaxKept: 26690.899999999998
- horizonYears: 2
totalTax: 184.3000000000011
afterTaxKept: 26815.699999999997
- horizonYears: 3
totalTax: 184.3000000000011
afterTaxKept: 26815.699999999997
deferralCallouts: []
externalDocs:
description: Integration surface, citation guidance, and roadmap
url: https://optionsahoy.com/for-agents