Compare loans
compare_loansRead-onlyIdempotent
Use this when the user wants to compare 2 to 4 loan or mortgage options side by side, such as 15-year vs 30-year, different interest rates, paying discount points, or a mortgage calculator for refinance options. Shared values (loan amount, rate, term) go at the top level and each scenario overrides what differs. Returns payment, total interest, upfront costs, total cost, payoff date and the break-even month for points or fees, plus a comparison CSV. Fixed-rate loans only; does not look up current rates or recommend a lender. Do not use for a single loan (use calculate_loan).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | ISO 4217 currency code for formatting, e.g. USD, EUR, GBP. Default USD. | |
| pmi_rate | No | Yearly private mortgage insurance rate as a percent of the original loan, e.g. 0.5. Needs home_price. Charged only while the loan is above 80% of the home value, and dropped once the balance reaches 78%. | |
| principal | No | Shared loan amount used by every scenario that does not set its own, e.g. 280000. | |
| scenarios | Yes | 2 to 4 loan scenarios. Each needs its own annual_rate and term unless set at the top level, e.g. [{"label":"30-year","annual_rate":6.5,"term_years":30},{"label":"15-year","annual_rate":5.75,"term_years":15}]. | |
| home_price | No | Purchase price or current home value, e.g. 400000. Used with down_payment/down_payment_percent to get the loan amount, and as the value for PMI loan-to-value. | |
| start_date | No | Date of the first payment, YYYY-MM or YYYY-MM-DD, e.g. 2026-11. Defaults to the first day of next month. | |
| term_years | No | Shared term in years for scenarios that do not set their own, e.g. 30. | |
| accelerated | No | For biweekly/weekly only: true pays half (biweekly) or a quarter (weekly) of the monthly payment each period, which adds about one extra monthly payment a year. Default false (a true biweekly/weekly amortization). | |
| annual_rate | No | Shared annual rate in percent for scenarios that do not set their own, e.g. 6.5. | |
| term_months | No | Loan term in months, e.g. 360 or 72 for a car loan. | |
| down_payment | No | Down payment amount, e.g. 50000. Used with home_price. | |
| payment_frequency | No | How often payments are made: monthly (default), biweekly (every 2 weeks, 26 a year), or weekly (52 a year). | |
| down_payment_percent | No | Down payment as a percent of home_price, e.g. 20 for 20%. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | ||
| warnings | Yes | ||
| downloads | Yes | ||
| reference | Yes | ||
| scenarios | Yes | ||
| lowest_payment | Yes | ||
| lowest_cost_of_borrowing | Yes |