Valuation API

Calculate the Internal Rate of Return (IRR), MOIC and an IRR sensitivity table for a single lump-sum equity investment that returns one exit value after a whole-year hold period. WHEN TO USE: you have an upfront investment amount, a single exit value and a hold period in whole years (standard PE/VC single-exit scenario) and need the annualised return, the money multiple, or a return stress-test. The result also includes a plain-language interpretation benchmarked against VC/PE/public-market return hurdles. WHEN NOT TO USE: for cash-flow streams with multiple intermediate distributions (use calculate_npv or calculate_moic on the full cash-flow array), or when you only need the sensitivity grid (use calculate_irr_sensitivity). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access, no randomness; idempotent and non-destructive; identical inputs always produce identical outputs. IRR is solved over the cash-flow schedule [-investment, 0, ..., exit_value] via Newton-Raphson with bisection fallback. RETURNS: JSON object with concept, definition, formula, calculation (irr as a percentage string, moic as a multiple, cash_flows array), interpretation, and sensitivity (byMultiple, byHoldPeriod). PARAMETERS: initial_investment (number > 0, currency units), exit_value (number > 0, same currency units), hold_period (integer >= 1 whole years), currency (optional string: GBP default, USD, EUR, JPY, CHF — display only, no conversion).

Calculate the Net Present Value (NPV) of an ordered cash-flow series discounted at a given rate. The first cash flow is treated as time 0 and is NOT discounted (typically the negative initial investment). WHEN TO USE: to evaluate whether an investment creates or destroys value at a required discount rate, or to compare competing projects on a present-value basis when you have a full cash-flow schedule. WHEN NOT TO USE: for a single lump-sum investment with one exit value (use calculate_irr), or when you only need a money multiple with no time value (use calculate_moic). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. RETURNS: JSON object { npv: number rounded to 2dp, rate, cash_flows }. A positive NPV means the investment clears the discount-rate hurdle. PARAMETERS: rate (decimal discount rate, e.g. 0.10 = 10% — express as a decimal, never as percentage points), cash_flows (ordered number array starting at time 0; negative values are investments/outflows, positive values are distributions/inflows), e.g. [-100000, 0, 0, 0, 0, 250000].

Calculate the Multiple on Invested Capital (MOIC): total distributions divided by total invested, with no discounting and no time value. WHEN TO USE: for a quick money-multiple answer from a cash-flow schedule when you do not need a discount rate or annualised return. WHEN NOT TO USE: when time value of money matters (use calculate_irr for annualised return, or calculate_npv for discounted value). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. MOIC is computed as sum of positive cash flows divided by sum of absolute negative cash flows; returns 0 if there is no invested capital. RETURNS: JSON object { moic: number rounded to 2dp (e.g. 2.5 = 2.5x), cash_flows }. PARAMETERS: cash_flows (ordered number array starting at time 0; negatives are investments, positives are distributions), e.g. [-100000, 0, 0, 0, 0, 250000].

Compute a Discounted Cash Flow (DCF) valuation: enterprise value from projected free cash flows plus a Gordon-growth terminal value. WHEN TO USE: to value a company or asset from its projected free cash flows, WACC and perpetual terminal growth rate (standard corporate/asset valuation). WHEN NOT TO USE: for a single-exit lump-sum investment (use calculate_irr), or when you need the discount rate itself (use calculate_wacc). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. Terminal value uses the Gordon Growth Model; it is only defined when wacc is strictly greater than terminal_growth_rate. RETURNS: JSON object { inputs, results: { present_value, terminal_value, enterprise_value } }, each rounded to 2dp. present_value is the discounted explicit-period FCFs; enterprise_value = present_value + discounted terminal value (debt and cash are NOT netted — this is enterprise value, not equity value). PARAMETERS: free_cash_flows (array of per-period projected free cash flows, typically positive; the first element is discounted by one period), wacc (decimal, e.g. 0.10 = 10% — never pass percentage points; must be > terminal_growth_rate), terminal_growth_rate (decimal perpetual growth rate, e.g. 0.03 = 3% — never pass percentage points; must be < wacc).

Calculate the Weighted Average Cost of Capital (WACC): the blended after-tax cost of a company's equity and debt capital, weighted by market values. WHEN TO USE: to determine the discount rate for a DCF valuation from equity market value, debt market value, costs of capital and corporate tax rate. WHEN NOT TO USE: when you already have the discount rate, or for the full valuation itself (use calculate_dcf). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. Formula: (E/V) x Re + (D/V) x Rd x (1 - tax_rate), where V = equity_value + debt_value; returns 0 if total value is 0. RETURNS: JSON object { wacc: decimal rounded to 6dp (e.g. 0.105), wacc_percent: percentage rounded to 2dp (e.g. 10.5), inputs }. PARAMETERS: equity_value (market value of equity, >= 0), debt_value (market value of debt, >= 0), cost_of_equity (decimal, e.g. 0.12 = 12%), cost_of_debt (decimal, e.g. 0.06 = 6%), tax_rate (decimal 0-1, e.g. 0.25 = 25%). All rates are decimals, never percentage points.

Compute an IRR sensitivity grid across a range of exit multiples and hold periods for a single lump-sum investment. WHEN TO USE: to stress-test how the annualised return varies with exit multiple and holding period before committing to an investment. Complements calculate_irr. WHEN NOT TO USE: when you need one precise IRR for a known exit value (use calculate_irr), or a full valuation (use calculate_dcf). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive. NOTE ON GRID GEOMETRY: the byMultiple grid is computed at the SECOND hold period in hold_periods (default 5 years); the byHoldPeriod grid is computed at a 2.5x exit multiple. RETURNS: JSON object { byMultiple: { "2.0x": 14.9, ... } with IRR values as percentage numbers rounded to 1dp, byHoldPeriod: { "5y": 18.4, ... } }. PARAMETERS: initial_investment (number > 0), exit_multiples (optional array of numbers to test, default [1.5, 2.0, 2.5, 3.0, 3.5]), hold_periods (optional array of positive integers (years) to test, default [3, 5, 7, 10]).

Calculate the earnings yield: earnings per share divided by share price — the inverse of the P/E ratio, expressing the earnings return on the share price as a percentage. Formula: Earnings Yield = EPS / Share Price. WHEN TO USE: Use to compare equity earnings returns directly against bond yields or the risk-free rate, or as a quick value screen — a high earnings yield can signal a cheap stock. WHEN NOT TO USE: Do NOT use when EPS is negative or zero (the yield is meaningless); use it as a complement to, not a replacement for, the P/E ratio (calculate_pe_ratio). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { earnings_yield: decimal (e.g. 0.05 = 5%), earnings_yield_pct: number (e.g. 5.0), pe_ratio: number (e.g. 20 = 20x), inputs }. The P/E ratio is the reciprocal of the earnings yield, returned so a client gets both figures from one call. PARAMETERS: earnings_per_share (required): Earnings per share (trailing or forward), e.g. 2.50. Must be > 0 for a meaningful yield. share_price (required): Current share price in currency units, e.g. 50.00. Must be > 0.

Calculate enterprise value (EV): the total value of a business to all capital providers — equity value plus net debt (total debt minus cash and equivalents). Formula: EV = Equity Value + Total Debt - Cash & Equivalents. WHEN TO USE: Use as the capital-structure-neutral measure of a company’s total value — the standard starting point for valuation multiples (EV/EBITDA, EV/Revenue) and M&A transaction values. WHEN NOT TO USE: Do NOT confuse EV with equity value (market cap) — EV is what you would pay to own the whole enterprise including its debt; use equity value for per-share figures. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { enterprise_value: number (currency), inputs }. PARAMETERS: equity_value (required): Equity value / market capitalisation, e.g. 5000000. Must be >= 0. total_debt (required): Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. cash_and_equivalents (required): Cash and cash equivalents to subtract, e.g. 500000. Must be >= 0.

Calculate the EV/EBITDA multiple: enterprise value divided by EBITDA — the most widely used valuation multiple for comparing companies independent of capital structure, tax and depreciation policy. Formula: EV/EBITDA = Enterprise Value / EBITDA. WHEN TO USE: Use for relative valuation of cash-generative businesses against peer multiples or transaction comps; a lower multiple may indicate relative undervaluation (or justified risk). WHEN NOT TO USE: Do NOT use when EBITDA is negative or near zero, or for early-stage companies with no meaningful EBITDA — the multiple is meaningless there (use EV/Revenue). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { ev_to_ebitda: number (e.g. 8.5 = 8.5x), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be > 0. ebitda (required): Earnings before interest, tax, depreciation and amortisation, e.g. 1200000. Must be > 0 for a meaningful multiple.

Calculate the EV/Revenue (EV/Sales) multiple: enterprise value divided by revenue — a valuation multiple usable for companies with thin, negative or zero EBITDA (e.g. high-growth or pre-profit businesses). Formula: EV/Revenue = Enterprise Value / Revenue. WHEN TO USE: Use for valuing pre-profit / high-growth companies, or as a cross-check alongside EV/EBITDA for mature ones. WHEN NOT TO USE: Do NOT use revenue multiples alone — they ignore profitability entirely (a company can have a low EV/S and still destroy value); pair with margin and growth context. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { ev_to_revenue: number (e.g. 3.2 = 3.2x), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be > 0. revenue (required): Revenue (net sales) over the trailing period, e.g. 3100000. Must be > 0.

Calculate the cost of equity using the Capital Asset Pricing Model (CAPM): the risk-free rate plus beta times the market risk premium. Formula: Re = Rf + beta x (Rm - Rf). WHEN TO USE: Use to estimate the required return on equity — an input to WACC (calculate_wacc) and DCF discount rates, or as a standalone return hurdle. WHEN NOT TO USE: Do NOT use for companies where beta is a poor risk measure (private companies without a traded beta — consider building up from comparable betas via calculate_unlever_beta / calculate_relever_beta first). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { cost_of_equity: decimal (e.g. 0.115 = 11.5%), cost_of_equity_pct: number (e.g. 11.5), inputs }. PARAMETERS: risk_free_rate (required): Risk-free rate as a decimal, e.g. 0.04 = 4% (typically the 10-year government bond yield; never pass percentage points). beta (required): Equity beta (levered, if the company has debt), e.g. 1.2. Use unlevered/relevered betas when comparing capital structures. market_return (required): Expected market return (Rm) as a decimal, e.g. 0.10 = 10% (never pass percentage points). The market risk premium is computed internally as Rm - Rf.

Unlever a (levered) equity beta to its asset beta using the Hamada formula — removing the financial-risk effect of debt so betas of companies with different capital structures can be compared. Formula: Beta(unlevered) = Beta(levered) / (1 + (1 - tax rate) x Debt/Equity). WHEN TO USE: Use when valuing a private company or a deal with a different capital structure than the public comparable — unlever the comps’ betas, average them, then relever at your target structure. WHEN NOT TO USE: Do NOT unlever with an inconsistent tax rate or debt/equity ratio — the result is only as clean as its inputs; for companies with significant non-debt liabilities consider a more advanced formula. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { unlevered_beta: number (e.g. 0.85), inputs }. PARAMETERS: levered_beta (required): The observed (levered) equity beta of the comparable company, e.g. 1.2. Must be > 0. tax_rate (required): Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. debt_to_equity (required): Debt-to-equity ratio of the company whose beta is being unlevered (market values preferred), e.g. 0.5 = 0.5x. Must be >= 0.

Relever an unlevered (asset) beta to a target capital structure using the Hamada formula — restoring financial risk for the specific debt/equity mix of the company or deal being valued. Formula: Beta(levered) = Beta(unlevered) x (1 + (1 - tax rate) x Debt/Equity). WHEN TO USE: Use AFTER unlevering comparable betas: apply the average unlevered beta to your target company’s (or transaction’s) capital structure to obtain the beta for WACC. WHEN NOT TO USE: Do NOT relever onto an unrealistic target structure — extreme leverage produces extreme betas that may overstate risk; sanity-check the resulting cost of equity. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { levered_beta: number (e.g. 1.15), inputs }. PARAMETERS: unlevered_beta (required): Unlevered (asset) beta, e.g. 0.85. Must be > 0. tax_rate (required): Corporate tax rate as a decimal between 0 and 1, e.g. 0.25 = 25%. debt_to_equity (required): Target debt-to-equity ratio (market values preferred), e.g. 0.6 = 0.6x. Must be >= 0.

Calculate equity value from enterprise value: the value attributable to common shareholders, derived by subtracting net debt (total debt minus cash) from enterprise value — the reverse of the EV bridge. Formula: Equity Value = Enterprise Value - Total Debt + Cash & Equivalents. WHEN TO USE: Use when you hold enterprise value (e.g. from a DCF or an EV multiple) and need the implied equity value / market capitalisation for per-share or acquisition-equity figures. WHEN NOT TO USE: Do NOT use when you already have market capitalisation directly; and do NOT net non-interest-bearing liabilities — only interest-bearing total debt is subtracted. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero, non-finite inputs, or mathematically undefined combinations return an explicit error instead of a number. RETURNS: JSON object { equity_value_from_enterprise_value: number (currency), inputs }. PARAMETERS: enterprise_value (required): Enterprise value in currency units, e.g. 10000000. Must be >= 0. total_debt (required): Total interest-bearing debt (short + long term), e.g. 2000000. Must be >= 0. cash_and_equivalents (required): Cash and cash equivalents to add back, e.g. 500000. Must be >= 0.