{ "openapi": "3.0.3", "info": { "title": "Financial Calculator API", "version": "1.0.0", "description": "Loan, mortgage, compound interest, savings, and ROI calculators with full amortization schedules. Pure JavaScript — zero external dependencies. Designed for FinTech apps, loan comparison tools, and investment calculators.\n", "contact": { "name": "Revenue Lab API Support", "email": "api@hiroapp.cc" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api.sprytools.com/v1/finance", "description": "Production (SpryTools API Gateway)" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v1/loan": { "post": { "operationId": "calculateLoan", "summary": "Loan calculator with amortization schedule", "description": "Calculates the monthly payment for an annuity loan and returns a full amortization schedule breaking down each payment into principal and interest components.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanRequest" }, "example": { "principal": 10000, "annualRate": 5, "months": 60 } } } }, "responses": { "200": { "description": "Loan calculation result with amortization schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanResult" }, "example": { "principal": 10000, "annualRate": 5, "months": 60, "monthlyPayment": 188.71, "totalCost": 11322.74, "totalInterest": 1322.74, "schedule": [ { "month": 1, "payment": 188.71, "principal": 147.38, "interest": 41.67, "balance": 9852.62 }, { "month": 2, "payment": 188.71, "principal": 147.99, "interest": 41.05, "balance": 9704.63 } ] } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/mortgage": { "post": { "operationId": "calculateMortgage", "summary": "Mortgage calculator with optional extra payments", "description": "Calculates a standard mortgage payment and optionally shows how extra monthly payments (Sondertilgungen) reduce total interest and shorten the loan term.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MortgageRequest" }, "example": { "loanAmount": 250000, "annualRate": 3.5, "termYears": 25, "extraMonthlyPayment": 200 } } } }, "responses": { "200": { "description": "Mortgage calculation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MortgageResult" }, "example": { "loanAmount": 250000, "annualRate": 3.5, "termYears": 25, "monthlyPayment": 1251.17, "totalCost": 375350.78, "totalInterest": 125350.78, "withExtraPayment": { "extraMonthlyPayment": 200, "newMonthlyTotal": 1451.17, "monthsSaved": 52, "interestSaved": 18432.55, "newTermMonths": 248 } } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/compound": { "post": { "operationId": "calculateCompound", "summary": "Compound interest calculator", "description": "Calculates compound interest growth with optional regular contributions. Supports monthly, quarterly, and annual compounding frequencies. Returns final balance, total contributions, total interest earned, and a year-by-year breakdown.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompoundRequest" }, "example": { "principal": 5000, "annualRate": 7, "years": 10, "monthlyContribution": 100, "compoundingFrequency": "monthly" } } } }, "responses": { "200": { "description": "Compound interest result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompoundResult" }, "example": { "principal": 5000, "annualRate": 7, "years": 10, "monthlyContribution": 100, "compoundingFrequency": "monthly", "finalBalance": 27040.45, "totalContributions": 17000, "totalInterest": 10040.45, "yearlyBreakdown": [ { "year": 1, "balance": 6613.12, "contributions": 1200, "interest": 413.12 }, { "year": 10, "balance": 27040.45, "contributions": 12000, "interest": 10040.45 } ] } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/savings": { "post": { "operationId": "calculateSavings", "summary": "Savings goal calculator", "description": "Determines the required monthly contribution to reach a savings goal. Takes into account existing savings and compound interest.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsRequest" }, "example": { "targetAmount": 20000, "currentSavings": 3000, "annualRate": 4, "years": 5 } } } }, "responses": { "200": { "description": "Savings goal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsResult" }, "example": { "targetAmount": 20000, "currentSavings": 3000, "annualRate": 4, "years": 5, "requiredMonthlyContribution": 243.58, "totalContributions": 14614.8, "totalInterest": 2385.2, "projectedBalance": 20000 } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/roi": { "post": { "operationId": "calculateROI", "summary": "ROI and CAGR calculator", "description": "Calculates Return on Investment (ROI) as a percentage and annualized return (CAGR — Compound Annual Growth Rate) for multi-year investments.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ROIRequest" }, "example": { "initialInvestment": 8000, "finalValue": 12500, "years": 4 } } } }, "responses": { "200": { "description": "ROI calculation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ROIResult" }, "example": { "initialInvestment": 8000, "finalValue": 12500, "years": 4, "netProfit": 4500, "roiPercent": 56.25, "cagr": 11.82 } } } }, "400": { "description": "Missing or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns service health status. No authentication required.", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "finance-api" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-RapidAPI-Key" } }, "schemas": { "AmortizationEntry": { "type": "object", "properties": { "month": { "type": "integer", "description": "Payment number (1-based)." }, "payment": { "type": "number", "description": "Total payment amount." }, "principal": { "type": "number", "description": "Principal portion of this payment." }, "interest": { "type": "number", "description": "Interest portion of this payment." }, "balance": { "type": "number", "description": "Remaining balance after this payment." } }, "required": [ "month", "payment", "principal", "interest", "balance" ] }, "LoanRequest": { "type": "object", "required": [ "principal", "annualRate", "months" ], "properties": { "principal": { "type": "number", "description": "Loan amount.", "example": 10000, "minimum": 1 }, "annualRate": { "type": "number", "description": "Annual interest rate in percent (e.g. 5 for 5%).", "example": 5, "minimum": 0 }, "months": { "type": "integer", "description": "Loan term in months.", "example": 60, "minimum": 1, "maximum": 600 } } }, "LoanResult": { "type": "object", "properties": { "principal": { "type": "number" }, "annualRate": { "type": "number" }, "months": { "type": "integer" }, "monthlyPayment": { "type": "number", "description": "Fixed monthly annuity payment." }, "totalCost": { "type": "number", "description": "Total amount paid over the loan term." }, "totalInterest": { "type": "number", "description": "Total interest paid." }, "schedule": { "type": "array", "items": { "$ref": "#/components/schemas/AmortizationEntry" } } } }, "MortgageRequest": { "type": "object", "required": [ "loanAmount", "annualRate", "termYears" ], "properties": { "loanAmount": { "type": "number", "description": "Total mortgage loan amount.", "example": 250000, "minimum": 1 }, "annualRate": { "type": "number", "description": "Annual interest rate in percent.", "example": 3.5, "minimum": 0 }, "termYears": { "type": "integer", "description": "Mortgage term in years.", "example": 25, "minimum": 1, "maximum": 50 }, "extraMonthlyPayment": { "type": "number", "description": "Optional extra monthly payment on top of the regular payment.", "example": 200, "minimum": 0 } } }, "MortgageExtraResult": { "type": "object", "properties": { "extraMonthlyPayment": { "type": "number" }, "newMonthlyTotal": { "type": "number" }, "monthsSaved": { "type": "integer" }, "interestSaved": { "type": "number" }, "newTermMonths": { "type": "integer" } } }, "MortgageResult": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "annualRate": { "type": "number" }, "termYears": { "type": "integer" }, "monthlyPayment": { "type": "number" }, "totalCost": { "type": "number" }, "totalInterest": { "type": "number" }, "withExtraPayment": { "$ref": "#/components/schemas/MortgageExtraResult", "description": "Present only when extraMonthlyPayment was provided." } } }, "CompoundRequest": { "type": "object", "required": [ "principal", "annualRate", "years" ], "properties": { "principal": { "type": "number", "description": "Initial investment amount.", "example": 5000, "minimum": 0 }, "annualRate": { "type": "number", "description": "Annual interest rate in percent.", "example": 7, "minimum": 0 }, "years": { "type": "integer", "description": "Investment period in years.", "example": 10, "minimum": 1, "maximum": 100 }, "monthlyContribution": { "type": "number", "description": "Optional regular monthly contribution added to the principal.", "example": 100, "minimum": 0, "default": 0 }, "compoundingFrequency": { "type": "string", "description": "How often interest is compounded.", "enum": [ "monthly", "quarterly", "annually" ], "default": "monthly" } } }, "YearlyBreakdownEntry": { "type": "object", "properties": { "year": { "type": "integer" }, "balance": { "type": "number" }, "contributions": { "type": "number" }, "interest": { "type": "number" } } }, "CompoundResult": { "type": "object", "properties": { "principal": { "type": "number" }, "annualRate": { "type": "number" }, "years": { "type": "integer" }, "monthlyContribution": { "type": "number" }, "compoundingFrequency": { "type": "string" }, "finalBalance": { "type": "number" }, "totalContributions": { "type": "number" }, "totalInterest": { "type": "number" }, "yearlyBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/YearlyBreakdownEntry" } } } }, "SavingsRequest": { "type": "object", "required": [ "targetAmount", "years" ], "properties": { "targetAmount": { "type": "number", "description": "The savings goal to reach.", "example": 20000, "minimum": 1 }, "currentSavings": { "type": "number", "description": "Amount already saved (optional).", "example": 3000, "minimum": 0, "default": 0 }, "annualRate": { "type": "number", "description": "Expected annual interest rate in percent.", "example": 4, "minimum": 0, "default": 0 }, "years": { "type": "integer", "description": "Time horizon in years.", "example": 5, "minimum": 1, "maximum": 100 } } }, "SavingsResult": { "type": "object", "properties": { "targetAmount": { "type": "number" }, "currentSavings": { "type": "number" }, "annualRate": { "type": "number" }, "years": { "type": "integer" }, "requiredMonthlyContribution": { "type": "number", "description": "Monthly contribution needed to reach the target." }, "totalContributions": { "type": "number" }, "totalInterest": { "type": "number" }, "projectedBalance": { "type": "number" } } }, "ROIRequest": { "type": "object", "required": [ "initialInvestment", "finalValue" ], "properties": { "initialInvestment": { "type": "number", "description": "Amount invested.", "example": 8000, "minimum": 0.01 }, "finalValue": { "type": "number", "description": "Value of the investment at exit.", "example": 12500, "minimum": 0 }, "years": { "type": "number", "description": "Hold period in years. Required for CAGR calculation.", "example": 4, "minimum": 0 } } }, "ROIResult": { "type": "object", "properties": { "initialInvestment": { "type": "number" }, "finalValue": { "type": "number" }, "years": { "type": "number" }, "netProfit": { "type": "number", "description": "Final value minus initial investment." }, "roiPercent": { "type": "number", "description": "ROI as a percentage." }, "cagr": { "type": "number", "description": "Compound Annual Growth Rate in percent. Only present when years > 0." } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message." } }, "required": [ "error" ] } } } }