# a3sec.net tools — calculator documentation for agents

> Detailed reference for the three demo calculators on www.a3sec.net (US & Canada salary/tax, mortgage, retirement):
> the JSON API, the MCP tools, the standalone JavaScript engines, URL parameters and the models behind them.
> These are side projects; for who Andriy Zelenyuk is and his security work, start at https://www.a3sec.net/llms.txt.

## API endpoints (JSON, GET, CORS enabled, no key)

- Demo calculators under /api/tools/ (the same engines as the web pages; estimates only, not financial or tax advice):
  - Mortgage: https://www.a3sec.net/api/tools/mortgage?country=CA&region=ON&price=700000&downPct=10
    (country, region, price, downPct|downAmount, aprPct, years, extra, taxMonthly, insMonthly, hoa, utilities,
    firstTimeBuyer, newBuild; the older homeStartEligible still works). Without aprPct the current average rate for
    the term is used; without a down payment 5% or the minimum for the price, whichever is higher.
  - Tax: https://www.a3sec.net/api/tools/tax?country=US&region=TX&filing=joint&salary=180000
    (country, region, filing, salary, capgains, dividends, capType, divType)
  - US vs Canada: https://www.a3sec.net/api/tools/compare?country=US&region=CA&salary=95000&otherRegion=ON
    (country and region where the salary is, salary, otherRegion, match = net (same take-home, default) | gross
    (same salary converted), filing, spouseShare, capgains, dividends, capType, divType, usdPerCad). Answers in USD
    at the Bank of Canada rate snapshotted at deploy, with an "answer" sentence and both tax breakdowns.
  - Retirement: https://www.a3sec.net/api/tools/retire?age=40&savings=150000&contribution=1000&retireAge=65&expenses=4000
    (age, savings, contribution, retireAge, lifeExpectancy, expenses, otherIncome, return, tax, inflation); a shortfall
    comes with closeTheGap: extra monthly saving, a later retirement age, or affordable spending.
  - Rates: https://www.a3sec.net/api/tools/rates · Regions: https://www.a3sec.net/api/tools/regions
  - Also downloadable as standalone JS: https://www.a3sec.net/tools/engines/ · the old /api/v1/… calculator paths redirect here.

## MCP tools

- Endpoint: https://www.a3sec.net/mcp (Streamable HTTP, stateless, POST JSON-RPC 2.0). Calculator tools:
  mortgage_quote, tax_estimate, compare_us_canada, retirement_projection and average_mortgage_rates.
  Claude Code: `claude mcp add --transport http a3sec https://www.a3sec.net/mcp`

## Financial calculators (detailed agent documentation)

Three free calculators: North America salary & tax (US federal + state, Canada federal + provincial, 2025 tax
year), US & Canada mortgage, and a retirement projection. Everything runs in the browser, and the same engines
are served as the JSON API and MCP server above. The calculations are published as standalone, dependency-free
JavaScript engines and every page accepts URL parameters, so an agent can run the exact engine (best), read the
model description here and compute, or open a prefilled page. Pages are bilingual (en / uk); engines are
language-neutral. Data vintage: 2025 tax year; property-tax presets are approximate 2024-25 average effective rates.

### How to use the calculators as an agent

- Exact numbers (needs code execution, Node 14+, no dependencies):
  curl -sO https://www.a3sec.net/tools/engines/mortgage-engine.js
  node -e "const M=require('./mortgage-engine.js');console.log(JSON.stringify(M.summarize(M.quickQuote({country:'CA',region:'ON',price:700000,downPct:10})),null,1))"
  The same pattern works for tax-engine.js (computeTax) and retire-engine.js (computeRetirement). Each engine
  documents its inputs and outputs in the comment header and exposes summarize(result) for compact JSON.
- Fetch-only (no JS execution): use the model descriptions below, or fetch an engine file and reproduce its logic.
  The tax engine also contains the full 2025 bracket tables for every US state and Canadian province.
- Browser automation: open a page with URL parameters and add agent=1; the "For AI agents & developers" panel opens
  and the current results are rendered as JSON in the element with id "resultsJson".

### Mortgage calculator

- Page: https://www.a3sec.net/tools/mortgage.html
- Engine: https://www.a3sec.net/tools/engines/mortgage-engine.js (global MortgageEngine / module.exports)
  - quickQuote({ country: "US"|"CA", region, price, downPct (default 5, or the minimum when higher), downAmount,
    aprPct = 6.6 (US) | 4.5 (CA), years = 30 (US) | 25 (CA), taxMonthly = regional preset, insMonthly = 100,
    hoa = 50 (US) | 0 (CA), utilities = 0, extra = 0, firstTimeBuyer (true|false|null), newBuild (Canada) })
    applies the page presets and returns computeMortgage()'s result plus `presets`.
  - computeMortgage({ country, region, price, down (amount), aprPct, termMonths, taxMonthly, insMonthly,
    miMonthlyOverride (null = auto PMI), hoa, utilities, extra, firstTimeBuyer, newBuild }) -> { payment,
    monthlyTotal, monthlyWithExtra, miMonthly, pmiRate, cmhcRate, cmhcPremium, baseLoan, loan, minDown: { amount,
    pct, rule, limit }, closingItems: [{ key, amount, label? }], closingCosts, closing (cash needed), ltt, buyerTax,
    pst, warnings, base: { totalInterest, totalPaid, monthsPaid, miPaid, balances[], ... }, withExtra: { ... } }
  - minDown(country, price, firstTimeBuyer, region), closingCostItems(...), REGIONS, CLOSING (the cost constants).
  - summarize(result) -> compact JSON (monthly, loan, closing with itemized costs, lifetime sections).
- URL parameters: country (US|CA), region (any US state code or DC; any Canadian province or territory code, or TOR
  for Toronto and MTL for Montreal), price, down (percent) or downAmount, apr, years or months, taxYearly,
  insuranceYearly, hoa, utilities, extra, firstTime (yes|no|unknown), newBuild (yes|no), lang (en|uk),
  theme (dark|light), agent=1. (The older homeStartEligible=yes|no still works and only sets 30-year eligibility.)
  Example: https://www.a3sec.net/tools/mortgage.html?country=CA&region=TOR&price=900000&firstTime=yes&agent=1
- Model:
  - Monthly principal & interest = standard amortization formula. US compounds monthly (rate = APR/12);
    Canadian fixed-rate mortgages compound semi-annually (rate = (1 + APR/2)^(1/6) - 1).
  - US private mortgage insurance (PMI): 1.35% / 0.85% / 0.50% of the loan per year for under 5% / under 10% /
    under 20% down; automatic termination uses the original 78% LTV schedule or the term midpoint, assuming payments are current. Extra payments do not advance that date; earlier cancellation by request is not modeled.
  - Canada CMHC default insurance: one-time premium of 4.00% / 3.10% / 2.80% of the loan for 5-9.99% / 10-14.99% /
    15-19.99% down, added to the mortgage principal. Amortizations over 25 years add 0.20 percentage points and
    require a first-time buyer or a newly built home; insured amortization cannot exceed 30 years.
  - Minimum down payment (the page raises a lower one automatically; the engine and API warn instead):
    Canada 5% of the first $500,000 plus 10% of the rest, 20% at $1,500,000 or more (not insurable).
    US conventional loans 3% for a first-time buyer (or HomeReady / Home Possible), 5% when firstTimeBuyer is false
    (omitted or unknown: 3%); above the 2026
    conforming limit ($832,750; $1,249,125 in AK and HI) the lesser of enough down to stay conforming or 10% (jumbo).
    FHA, VA and USDA loans are not modeled.
  - Property tax presets: US state average effective rates (Tax Foundation, Property Taxes by State and County
    2026); Canada a major city's residential rate (Calgary, Vancouver, Winnipeg, Regina, Toronto, Montreal, Moncton,
    Halifax, St. John's, Charlottetown, Yellowknife, Whitehorse; Nunavut is a rough estimate).
    Home insurance default $100/month. HOA default $50/month (US), condo/strata $0 (Canada).
  - Cash needed at closing = down payment + itemized closing costs (closingItems):
    - Buyer-paid transfer, recording and mortgage taxes by state (e.g. NY mortgage recording tax 0.8% of the loan
      plus the 1% mansion tax from $1M; FL 0.35% + 0.2% of the loan; PA, DE, AR, ME and MD the buyer's customary
      half; VA, TN, GA, MN, OK, AL, VT, NH, DC, CO; none elsewhere) with Maryland and Delaware first-time relief.
      Canada: every province's land transfer tax or registration fees (Ontario, Toronto municipal, BC, Manitoba,
      New Brunswick, Nova Scotia/Halifax, PEI, Quebec and Montreal welcome tax, and title and mortgage registration
      elsewhere) with first-time buyer refunds (Ontario up to $4,000, Toronto up to $4,475, BC exemption to
      $835k-$860k, PEI) and BC's newly built home exemption; sales tax on the CMHC premium in ON 8%, QC 9%
      (9.975% from 2027) and SK 6%.
    - US: lender origination (state median from 2025 HMDA data, about $1,450), appraisal/credit/flood $675, title
      insurance and settlement (state average from the LodeStar 2026 closing-cost report, scaled to the price),
      recording $150, inspection $350, the first year of home insurance, 15 days of prepaid interest, and an escrow
      deposit of 3 months of property tax plus 2 months of insurance.
    - Canada: legal fees $1,500 (Ontario $2,000; Quebec notary $1,800 instead of lawyer and title insurance), title
      insurance $300, inspection $500, appraisal $400 when the loan is not insured, a property-tax adjustment of
      about 2 months, topped up to 1.5% of the price (the low end of the official 1.5-4% range, commonly asked for
      by lenders).
  - Total paid over the term = every monthly cost (P&I, tax, insurance, mortgage insurance while it applies, HOA,
    utilities). Additional principal payments shorten the payoff; savings = baseline total paid - total paid with extra.

#### Average mortgage rates (APR presets)

- https://www.a3sec.net/tools/data/rates.json - JSON with `US.fixed30` / `US.fixed15` (Freddie Mac PMMS weekly
  averages via FRED series MORTGAGE30US / MORTGAGE15US) and `CA.fixed5` (5-year fixed, high-ratio mortgage),
  `CA.posted5` (posted 5-year conventional), `CA.variable` (estimated variable), from the Bank of Canada Valet API
  series FVI_MTG_RATE_5Y_FIX, V80691335 and BROKER_AVERAGE_5YR_VRM. Each entry has rate (%), date, label, source.
  `FX.USDCAD` is the Bank of Canada daily USD/CAD rate (CAD per USD, series FXUSDCAD) that the tax page uses for
  USD equivalents and its US vs Canada comparison.
  The file is refreshed when the site is deployed (scripts/update-rates.py); the page additionally pulls the
  Canadian series live. The mortgage page matches US.fixed15 or US.fixed30 to 15- or 30-year terms, and uses CA.fixed5 for Canada, until the user edits the rate. Other US terms have no matching average. Engine defaults are static: pass aprPct explicitly to match the page’s fetched rate.
- Agents can fetch the sources directly: https://fred.stlouisfed.org/graph/fredgraph.csv?id=MORTGAGE30US (CSV, last
  row is the latest week) and https://www.bankofcanada.ca/valet/observations/FVI_MTG_RATE_5Y_FIX/json?recent=1.
  Pass the rate to the engine as aprPct.

### Salary & tax calculator

- Page: https://www.a3sec.net/tools/tax.html
- Engine: https://www.a3sec.net/tools/engines/tax-engine.js (global TaxEngine / module.exports)
  - computeTax({ country: "US"|"CA", region (two-letter state or province code), filing: "single"|"joint" (US only),
    salary, capgains = 0, dividends = 0, capType: "long"|"short" (US), divType: "eligible"|"noneligible" })
    -> { gross, federal, regional, payroll, total, net, marginal, effectiveRate, breakdown[], note }
    For the US, divType "eligible" means qualified dividends and "noneligible" means ordinary dividends.
  - summarize(result) -> compact JSON. Region lists: Object.keys(US_STATES), Object.keys(CA_PROVINCES).
  - solveSalaryForNet(calcUS | calcCA, baseInputs, targetNet) -> gross salary needed for a target net.
  - compareCountries(anchorInputs, { region, filing, spouseShare }, usdPerCad, "net" | "gross") -> the same situation
    across the border, in USD. The anchor (computeTax inputs) is computed unchanged; the other country gets the given
    region and filing, the anchor's capital gains and dividends converted at usdPerCad, and either the salary that
    leaves the same net take-home ("net") or the anchor salary converted ("gross"). With US joint filing the Canadian
    side (anchor or other) is a couple filing two returns, the spouse getting spouseShare (0-0.5, default 0.5) of the
    income; 0 means one earner (the spousal amount credit is not modeled). Returns { anchor, other, spouseShare,
    grossDiffUSD, netDiffUSD }; each side has salary (local currency), grossUSD, federalUSD, regionalUSD, payrollUSD,
    totalUSD, netUSD, effectiveRate. summarizeComparison(result) -> compact JSON with a one-sentence answer.
    Example: compareCountries({country:"US",region:"CA",salary:95000}, {region:"ON"}, 0.7058)
  - calcCAHousehold(inputs, spouseShare) -> Canadian totals for a couple filing two returns.
- US vs Canada panel (Compare button): anchored on the salary entered for the active country; "Same take-home" or
  "Same salary"; the other country's region (and, with joint filing, the Canadian household split) is picked in its
  column. Exchange rate: Bank of Canada FXUSDCAD (tools/data/rates.json at deploy, refreshed live).
- URL parameters: country, region, filing, salary, capgains, dividends, capType, divType, lang, theme, agent=1.
  Example: https://www.a3sec.net/tools/tax.html?country=US&region=TX&filing=joint&salary=180000&agent=1
- Model (2025 tax year):
  - US federal: standard deduction $15,750 single / $31,500 joint; 10-37% ordinary brackets; long-term capital
    gains and qualified dividends stacked on top of ordinary income at 0 / 15 / 20%; 3.8% net investment income tax
    on investment income above $200,000 / $250,000 MAGI; Social Security 6.2% up to $176,100; Medicare 1.45% plus
    0.9% above $200,000 / $250,000. State tax from bundled tables: none, flat, or brackets (joint brackets where the
    state publishes them); CO/ID apply federal standard deductions, GA applies $12k/$24k, and ID has a $4,811/$9,622 zero-rate band. Other states’ deductions remain simplified. Washington's capital-gains tax ($278,000 deduction, 7% / 9.9%).
  - Canada: CPP 4.95% base (credit) + 1% enhanced (deduction) on pensionable earnings to $71,300, CPP2 4% to
    $81,200; EI 1.64% to $65,700 (Quebec: QPP 5.4% + 1%, EI 1.31%, QPIP 0.494% to $98,000); capital gains 50%
    inclusion; eligible dividends 38% gross-up (non-eligible 15%) with federal and provincial dividend tax credits;
    federal brackets 14.5-33% with the basic personal amount ground down between $177,882 and $253,414; the Canada
    employment amount; provincial brackets and basic personal amounts per province (Manitoba's grind applied);
    16.5% Quebec abatement. Ontario surtax (20% above $5,710 basic tax plus 36% above $7,307) and health premium ($0–$900) are included; surtax precedes the dividend credit. Marginal rate = tax on the next $1,000 of salary including payroll.
  - Simplified: other credits, surtaxes, local/city taxes, AMT, phase-outs and deductions beyond the above.

### Retirement calculator

- Page: https://www.a3sec.net/tools/retire.html
- Engine: https://www.a3sec.net/tools/engines/retire-engine.js (global RetireEngine / module.exports)
  - computeRetirement({ currentAge, currentSavings, monthlyContribution, retirementAge, lifeExpectancy,
    retirementMonthlyExpenses, otherIncomeMonthly = 0, returnRatePct, capitalGainsTaxPct = 0, inflationRatePct })
    -> { yearsToRetirement, projectedNestEgg, requiredNestEgg, sustainableMonthlyIncome (portfolio + other income),
         portfolioMonthlyIncome, monthlyGap, totalContributed, investmentGrowth, coverageRatio,
         projection: [{ age, balance }], ... } in today's dollars. otherIncomeMonthly (Social Security, CPP/OAS,
         pensions) starts at retirement; the portfolio funds expenses minus that income.
  - closeTheGap(inputs) -> null when on track, else { extraMonthlyContribution (exact), retirementAge (earliest
    on-track age), affordableMonthlyExpenses }: three separate ways to close a shortfall.
  - nominalFactor(inflationRate, years) converts to future dollars; summarize(result) -> compact JSON with both.
- URL parameters: age, savings, contribution, retireAge, lifeExpectancy, expenses, otherIncome, return, tax,
  inflation, mode (real|nominal), lang, theme, agent=1.
- The page also shows calendar-year returns 2019-2025 for the S&P 500 (SPY), Nasdaq-100 (QQQ), Dow (DIA), US bonds
  (AGG), gold (GLD), Bitcoin and Ethereum, with 7-year CAGRs and long-run averages 1928-2025 from Aswath Damodaran
  (S&P 500 10.0%, 10-year Treasury 4.5%, gold 5.6%, nominal); clicking an average sets the expected return.
  Example: https://www.a3sec.net/tools/retire.html?age=40&savings=150000&contribution=1000&retireAge=65&expenses=4000&agent=1
- Model: after-tax return = return x (1 - capital-gains tax), an annual drag that assumes gains are realized yearly
  (use 0 for tax-advantaged accounts); real return = (1 + after-tax) / (1 + inflation) - 1; monthly compounding with
  contributions at the end of each month; nest egg needed = monthly expenses x annuity-due factor over the months
  in retirement at the real monthly rate; sustainable income = projected nest egg / that factor; drawdown withdraws
  expenses at the start of each month until life expectancy. Contributions are fixed in today’s dollars, so nominal deposits grow with inflation. Nominal totalContributed sums actual deposits; nominal investmentGrowth is nominal balance minus nominal deposits. Gains/losses can be negative. Currency-neutral.

## Notes for agents

- Money is in local currency (USD for US, CAD for Canada). All calculator output is an estimate, not
  financial or tax advice. Tax data is the 2025 tax year; property-tax presets are 2024-25 averages.
- Rate limits: the API runs on a small serverless function; keep it to a few requests per second.
- robots.txt allows well-behaved crawlers and AI assistants; nothing on the site requires JavaScript to read.