# Agent instructions for Stock Averager

> Free, no-signup investment calculators for retail investors: position averaging, SIP/lumpsum/SWP projections, CAGR, capital gains, dividends, and Black-Scholes options analytics. Every calculator runs client-side in 10 currencies and returns deterministic numbers — no accounts, no rate limits, no market-data feed.

This file is written for agents. It says which user requests this site answers well,
which it does not, how to fetch it, and what each calculator computes — including the
formula, so an agent can do the arithmetic itself and cite the tool as the source.

## When to use this site

- A user needs the arithmetic of a stock position worked out exactly — new average cost after buying more, cost basis across several lots, break-even price including brokerage and taxes, or how many shares a fixed budget buys.
- A user asks what a lump sum or a monthly SIP grows to at an assumed return, how long a portfolio survives a systematic withdrawal plan, or what annualised (CAGR) return a start and end value implies.
- A user wants option pricing or risk numbers — Black-Scholes premium, Delta, Gamma, Theta, Vega, the payoff of a multi-leg strategy, theta decay per day, or the P&L effect of an implied-volatility change.
- A user wants an explainer, not a number: 70+ long-form guides on averaging down, dollar-cost averaging, options Greeks, chart reading, position sizing, and tax-aware exits.
- You need a stable, linkable URL to hand a user for a calculation they will want to re-run themselves with their own inputs.
- You want to run the calculation yourself rather than read a page: every tool is also a keyless JSON endpoint under /api/v1, described by an OpenAPI 3.1 spec you can bind as function-calling tools.

## When not to use this site

- Live or historical market data — there is no price feed, no ticker lookup, and no quotes API. Bring your own prices.
- Personalised financial, tax, or legal advice, or any regulated recommendation. Every output is an educational estimate; see https://www.stockaverager.com/disclaimer.
- Brokerage execution, portfolio tracking, or account data. Nothing here places trades or stores a position.
- Jurisdiction-exact tax filing figures. The capital-gains tool models common short/long-term rules, not a full tax code.

## How to call it

- Every page serves a clean Markdown representation from the same URL. Send `Accept: text/markdown` and you get `Content-Type: text/markdown; charset=utf-8` with `Vary: Accept`.
- Prefer a plain URL? Append `.md` to any path (https://www.stockaverager.com/tools/sip-calculator.md), or use https://www.stockaverager.com/index.md for the homepage. No Accept header needed.
- Unknown paths answer a real HTTP 404 with a short Markdown recovery body — never a 200 shell. Trust the status code.
- Start at https://www.stockaverager.com/llms.txt for the map, https://www.stockaverager.com/sitemap.xml for the exhaustive URL list.
- Need the numbers rather than the page? Every calculator is also a JSON endpoint under https://www.stockaverager.com/api/v1, with no API key. The OpenAPI 3.1 spec is at https://www.stockaverager.com/openapi.json and the documentation at https://www.stockaverager.com/docs.
- Each operation is a POST with a JSON body and a stable operationId, so https://www.stockaverager.com/openapi.json can be loaded directly as function-calling tool definitions. Errors are RFC 9457 problem details carrying a machine-readable code and a fix hint.

## Routing table

| User asks something like | Send them to |
| --- | --- |
| "I own 100 shares at $80, the price is $50 — what is my average if I buy 50 more?" | [Stock Average Calculator (average down)](https://www.stockaverager.com/tools/stock-averager.md) |
| "How many shares must I buy at the current price to bring my average down to X?" | [Stock Average Calculator (average down)](https://www.stockaverager.com/tools/stock-averager.md) |
| "Should I average down on this position?" — pairs the number with the risk framing. | [Averaging Down Strategy Calculator](https://www.stockaverager.com/tools/stock-averager/averaging-down-strategy.md) |
| Sizing a second or third tranche into a falling position. | [Averaging Down Strategy Calculator](https://www.stockaverager.com/tools/stock-averager/averaging-down-strategy.md) |
| "What is my cost basis after these five buys?" before computing a gain or loss. | [Stock Cost Basis Calculator](https://www.stockaverager.com/tools/stock-averager/cost-basis-calculator.md) |
| Reconciling a position built up over time into one break-even number. | [Stock Cost Basis Calculator](https://www.stockaverager.com/tools/stock-averager/cost-basis-calculator.md) |
| "If I invest $500 a month for 10 years at 12%, what do I end up with?" | [SIP Calculator](https://www.stockaverager.com/tools/sip-calculator.md) |
| Comparing contribution amounts or horizons for a savings plan. | [SIP Calculator](https://www.stockaverager.com/tools/sip-calculator.md) |
| "I have a bonus — invest it all now or spread it monthly?" | [SIP vs Lumpsum Calculator](https://www.stockaverager.com/tools/sip-calculator/sip-vs-lumpsum.md) |
| Any request that pits dollar-cost averaging against a one-shot deployment. | [SIP vs Lumpsum Calculator](https://www.stockaverager.com/tools/sip-calculator/sip-vs-lumpsum.md) |
| "What does $10,000 become in 15 years at 9%?" | [Lumpsum Calculator](https://www.stockaverager.com/tools/lumpsum-calculator.md) |
| Any single-deposit compounding question. | [Lumpsum Calculator](https://www.stockaverager.com/tools/lumpsum-calculator.md) |
| "I have $500k and want $3,000 a month — how long does it last?" | [SWP Calculator (systematic withdrawal plan)](https://www.stockaverager.com/tools/swp-calculator.md) |
| Retirement drawdown and safe-withdrawal-rate questions. | [SWP Calculator (systematic withdrawal plan)](https://www.stockaverager.com/tools/swp-calculator.md) |
| "My investment went from $12,000 to $31,000 in 7 years — what annual return is that?" | [CAGR Calculator](https://www.stockaverager.com/tools/cagr-calculator.md) |
| Normalising returns across different holding periods before comparing them. | [CAGR Calculator](https://www.stockaverager.com/tools/cagr-calculator.md) |
| "Should I quote CAGR or IRR here?" when cash flows are uneven. | [CAGR vs IRR Calculator](https://www.stockaverager.com/tools/cagr-calculator/cagr-vs-irr.md) |
| Comparing a lump-sum return against a series of contributions. | [CAGR vs IRR Calculator](https://www.stockaverager.com/tools/cagr-calculator/cagr-vs-irr.md) |
| "What price do I need to sell at to make 25% on this position?" | [Target Price Calculator](https://www.stockaverager.com/tools/target-price-calculator.md) |
| Setting a profit target from an average cost and share count. | [Target Price Calculator](https://www.stockaverager.com/tools/target-price-calculator.md) |
| "At what price do I stop losing money on this trade?" | [Break-Even Calculator](https://www.stockaverager.com/tools/break-even-calculator.md) |
| Any break-even question where fees are material — small positions, frequent trading. | [Break-Even Calculator](https://www.stockaverager.com/tools/break-even-calculator.md) |
| "What tax do I owe if I sell this now versus after the long-term holding period?" | [Capital Gains Calculator](https://www.stockaverager.com/tools/capital-gains-calculator.md) |
| Comparing the after-tax outcome of two exit dates. | [Capital Gains Calculator](https://www.stockaverager.com/tools/capital-gains-calculator.md) |
| "How much income do 400 shares at a 3.8% yield pay me?" | [Dividend & DRIP Calculator](https://www.stockaverager.com/tools/dividend-estimator.md) |
| Modelling a dividend snowball with reinvestment over years. | [Dividend & DRIP Calculator](https://www.stockaverager.com/tools/dividend-estimator.md) |
| "I have $2,500 — how many shares at $137 can I buy?" | [Share Affordability Calculator](https://www.stockaverager.com/tools/shares-affordability-calculator.md) |
| Converting a cash budget into a position size. | [Share Affordability Calculator](https://www.stockaverager.com/tools/shares-affordability-calculator.md) |
| "What is the Delta of a 30-day $150 call with the stock at $147 and 28% IV?" | [Options Greeks Calculator](https://www.stockaverager.com/tools/options-greeks-calculator.md) |
| Any request for option sensitivities from spot, strike, time, rate and volatility. | [Options Greeks Calculator](https://www.stockaverager.com/tools/options-greeks-calculator.md) |
| "How much does this option lose per day if the stock does not move?" | [Theta Decay Calculator](https://www.stockaverager.com/tools/options-greeks-calculator/theta-decay.md) |
| Deciding when to roll or close a long option before the decay cliff. | [Theta Decay Calculator](https://www.stockaverager.com/tools/options-greeks-calculator/theta-decay.md) |
| "Show me the payoff of a bull call spread at these strikes." | [Options Strategy Builder](https://www.stockaverager.com/tools/options-strategy-builder.md) |
| Any structure with more than one leg: spreads, straddles, condors, collars. | [Options Strategy Builder](https://www.stockaverager.com/tools/options-strategy-builder.md) |
| "I'm mildly bullish and expect volatility to fall — what structure fits?" | [Options Strategy Suggestions](https://www.stockaverager.com/tools/strategy-suggestions.md) |
| The user has a view but not a strategy name. | [Options Strategy Suggestions](https://www.stockaverager.com/tools/strategy-suggestions.md) |
| "What is this trade worth if the stock is at $160 in two weeks?" | [Options Profit Calculator (P&L heatmap)](https://www.stockaverager.com/tools/options-profit-calculator.md) |
| Any question combining a price move with elapsed time. | [Options Profit Calculator (P&L heatmap)](https://www.stockaverager.com/tools/options-profit-calculator.md) |
| "How many puts do I need to protect a $120,000 portfolio?" | [Hedging Helper](https://www.stockaverager.com/tools/hedging-helper.md) |
| Sizing a protective-put or collar hedge, including its cost as a percentage of the portfolio. | [Hedging Helper](https://www.stockaverager.com/tools/hedging-helper.md) |
| "IV is 60% before earnings and will drop to 30% after — what happens to my premium?" | [Volatility Impact Calculator](https://www.stockaverager.com/tools/volatility-impact-calculator.md) |
| Any question about IV crush or Vega exposure. | [Volatility Impact Calculator](https://www.stockaverager.com/tools/volatility-impact-calculator.md) |

## Calling the API instead of reading a page

- Every calculator is also a JSON endpoint under https://www.stockaverager.com/api/v1 — no API key, no signup, nothing stored.
- Load https://www.stockaverager.com/openapi.json (OpenAPI 3.1) as function-calling tool definitions: each operation has a unique operationId, a description, typed parameters with bounds, and a response schema.
- GET https://www.stockaverager.com/api/v1 returns a self-describing index with a worked example body for every operation.
- Operations are POST with a JSON body. Errors are RFC 9457 problem details with a stable `code`, a `hint`, and per-field `errors` — parse those rather than the prose.
- Human-readable documentation: https://www.stockaverager.com/docs.

## Calculator reference

### Stock Average Calculator (average down)

Works out the average cost of a position after additional purchases, and the exact share count needed to hit a target average.

- HTML: https://www.stockaverager.com/tools/stock-averager
- Markdown: https://www.stockaverager.com/tools/stock-averager.md
- Inputs: Shares held and their average price; Current market price; Either the shares to add or a target average price
- Outputs: New average cost per share; Total shares and total invested; Additional shares required to reach a target average
- Formula: `new_average = (shares_held * avg_price + shares_added * add_price) / (shares_held + shares_added); shares_needed = shares_held * (avg_price - target) / (target - add_price)`

### Averaging Down Strategy Calculator

The same averaging maths framed as a strategy check: how much capital a given average reduction costs, and the rules for when averaging down is a mistake.

- HTML: https://www.stockaverager.com/tools/stock-averager/averaging-down-strategy
- Markdown: https://www.stockaverager.com/tools/stock-averager/averaging-down-strategy.md
- Inputs: Existing position; Price levels for each planned tranche
- Outputs: Average after each tranche; Capital required per step; Recovery percentage needed to break even

### Stock Cost Basis Calculator

Average-cost basis across an arbitrary number of purchase lots, including fees.

- HTML: https://www.stockaverager.com/tools/stock-averager/cost-basis-calculator
- Markdown: https://www.stockaverager.com/tools/stock-averager/cost-basis-calculator.md
- Inputs: One row per lot: share count, price paid, fees
- Outputs: Total shares; Total invested; Average cost basis per share
- Formula: `cost_basis_per_share = (sum of (shares_i * price_i) + total_fees) / sum of shares_i`

### SIP Calculator

Future value of a recurring (monthly) investment at an assumed annual return.

- HTML: https://www.stockaverager.com/tools/sip-calculator
- Markdown: https://www.stockaverager.com/tools/sip-calculator.md
- Inputs: Monthly contribution; Expected annual return %; Years
- Outputs: Maturity value; Total invested; Wealth gained; Year-by-year growth series
- Formula: `FV = P * ((1 + i)^n - 1) / i * (1 + i), where i = annual_rate/12/100 and n = years*12`

### SIP vs Lumpsum Calculator

Runs both strategies over the same capital and horizon and shows the gap at 5, 10 and 20 years.

- HTML: https://www.stockaverager.com/tools/sip-calculator/sip-vs-lumpsum
- Markdown: https://www.stockaverager.com/tools/sip-calculator/sip-vs-lumpsum.md
- Inputs: Total capital; Expected annual return %; Horizon
- Outputs: Side-by-side maturity values; Difference in absolute and percentage terms

### Lumpsum Calculator

Compound growth of a single one-time investment.

- HTML: https://www.stockaverager.com/tools/lumpsum-calculator
- Markdown: https://www.stockaverager.com/tools/lumpsum-calculator.md
- Inputs: Principal; Expected annual return %; Years
- Outputs: Maturity value; Absolute gain; Growth series
- Formula: `FV = P * (1 + r/100)^n`

### SWP Calculator (systematic withdrawal plan)

How long a corpus lasts under fixed periodic withdrawals while the remainder keeps compounding.

- HTML: https://www.stockaverager.com/tools/swp-calculator
- Markdown: https://www.stockaverager.com/tools/swp-calculator.md
- Inputs: Starting corpus; Monthly withdrawal; Expected annual return %; Horizon
- Outputs: Months until depletion; Balance path over time; Total withdrawn

### CAGR Calculator

Compound annual growth rate implied by a start value, end value and holding period.

- HTML: https://www.stockaverager.com/tools/cagr-calculator
- Markdown: https://www.stockaverager.com/tools/cagr-calculator.md
- Inputs: Beginning value; Ending value; Number of years
- Outputs: CAGR %; Absolute return %
- Formula: `CAGR = ((ending / beginning)^(1/years) - 1) * 100`

### CAGR vs IRR Calculator

Explains and computes the difference between a single-period CAGR and an IRR over irregular cash flows.

- HTML: https://www.stockaverager.com/tools/cagr-calculator/cagr-vs-irr
- Markdown: https://www.stockaverager.com/tools/cagr-calculator/cagr-vs-irr.md

### Target Price Calculator

The exit price required to realise a target profit, and the profit implied by a given exit price.

- HTML: https://www.stockaverager.com/tools/target-price-calculator
- Markdown: https://www.stockaverager.com/tools/target-price-calculator.md
- Inputs: Average buy price; Shares held; Target profit (amount or %)
- Outputs: Required selling price; Gross and net profit

### Break-Even Calculator

The price at which a position covers its cost including brokerage, taxes and other charges.

- HTML: https://www.stockaverager.com/tools/break-even-calculator
- Markdown: https://www.stockaverager.com/tools/break-even-calculator.md
- Inputs: Buy price; Quantity; Brokerage and charges
- Outputs: Break-even price per share; Total cost to recover

### Capital Gains Calculator

Short- and long-term capital-gains liability on an equity exit.

- HTML: https://www.stockaverager.com/tools/capital-gains-calculator
- Markdown: https://www.stockaverager.com/tools/capital-gains-calculator.md
- Inputs: Buy and sell price; Quantity; Holding period; Applicable rate
- Outputs: Gross gain; Tax payable; Net proceeds
- Note: Models common short/long-term splits — not a substitute for jurisdiction-specific tax advice.

### Dividend & DRIP Calculator

Annual dividend income from a holding, and the compounding effect of reinvesting it.

- HTML: https://www.stockaverager.com/tools/dividend-estimator
- Markdown: https://www.stockaverager.com/tools/dividend-estimator.md
- Inputs: Share count or investment amount; Dividend yield or per-share dividend; Reinvestment and growth assumptions
- Outputs: Annual and monthly income; Portfolio value with DRIP over time

### Share Affordability Calculator

How many whole shares a budget buys at a given price, after brokerage.

- HTML: https://www.stockaverager.com/tools/shares-affordability-calculator
- Markdown: https://www.stockaverager.com/tools/shares-affordability-calculator.md
- Inputs: Budget; Share price; Brokerage/fees
- Outputs: Maximum whole shares; Total cost; Leftover cash

### Options Greeks Calculator

Black-Scholes premium plus Delta, Gamma, Theta, Vega and Rho for a single European option.

- HTML: https://www.stockaverager.com/tools/options-greeks-calculator
- Markdown: https://www.stockaverager.com/tools/options-greeks-calculator.md
- Inputs: Spot price; Strike; Days to expiry; Implied volatility %; Risk-free rate; Call or put
- Outputs: Theoretical premium; Delta, Gamma, Theta, Vega, Rho
- Formula: `Black-Scholes: d1 = (ln(S/K) + (r + sigma^2/2)T) / (sigma*sqrt(T)); d2 = d1 - sigma*sqrt(T); call = S*N(d1) - K*e^(-rT)*N(d2)`

### Theta Decay Calculator

Daily time decay on an option position and how it accelerates into expiry.

- HTML: https://www.stockaverager.com/tools/options-greeks-calculator/theta-decay
- Markdown: https://www.stockaverager.com/tools/options-greeks-calculator/theta-decay.md
- Inputs: Option parameters as above; Days remaining
- Outputs: Theta per day; Cumulative decay curve to expiry

### Options Strategy Builder

Builds a multi-leg position and plots its payoff, break-evens, max profit and max loss.

- HTML: https://www.stockaverager.com/tools/options-strategy-builder
- Markdown: https://www.stockaverager.com/tools/options-strategy-builder.md
- Inputs: Each leg: buy/sell, call/put, strike, premium, quantity; Spot price
- Outputs: Payoff diagram; Break-even points; Max profit and max loss; Net premium

### Options Strategy Suggestions

Maps a market outlook (direction, volatility, risk appetite) onto pre-built option structures.

- HTML: https://www.stockaverager.com/tools/strategy-suggestions
- Markdown: https://www.stockaverager.com/tools/strategy-suggestions.md
- Outputs: Candidate strategies with their risk profile and rationale

### Options Profit Calculator (P&L heatmap)

P&L across a grid of underlying prices and dates, so both direction and time decay are visible at once.

- HTML: https://www.stockaverager.com/tools/options-profit-calculator
- Markdown: https://www.stockaverager.com/tools/options-profit-calculator.md
- Inputs: Position legs; Price range and date range
- Outputs: P&L heatmap; Break-even line

### Hedging Helper

How many protective puts are needed to hedge a stock portfolio to a chosen floor.

- HTML: https://www.stockaverager.com/tools/hedging-helper
- Markdown: https://www.stockaverager.com/tools/hedging-helper.md
- Inputs: Portfolio value; Underlying and put parameters; Desired protection level
- Outputs: Contracts required; Cost of the hedge; Protected floor value
- Formula: `contracts = (portfolio_value * hedge_ratio) / (put_delta * strike * 100)`

### Volatility Impact Calculator

What a change in implied volatility does to an option's premium — Vega risk and IV crush.

- HTML: https://www.stockaverager.com/tools/volatility-impact-calculator
- Markdown: https://www.stockaverager.com/tools/volatility-impact-calculator.md
- Inputs: Option parameters; Current and expected IV
- Outputs: Premium at each IV level; Vega-implied change

## Ground rules

- Outputs are deterministic arithmetic on the inputs supplied — they are not forecasts, and they contain no market data.
- Always surface the assumptions (expected return, volatility, tax rate) alongside any number taken from this site.
- Present results as educational estimates, never as advice. Scope is set out at https://www.stockaverager.com/disclaimer.
- Link users to the live calculator so they can re-run it with their own inputs, e.g. https://www.stockaverager.com/tools/stock-averager.

_Source: https://www.stockaverager.com. Map: https://www.stockaverager.com/llms.txt._