showrealcost

For a fixed-rate installment loan (personal, auto, any level-payment loan): the monthly payment, total interest, total repaid, how the first payment splits between interest and principal, and optionally how much has been paid and is still owed after a number of payments. Use for "what will this loan cost" and "where did my payments go".

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Amount borrowed, in dollars"
    },
    "annual_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "Annual interest rate in percent, e.g. 6.97"
    },
    "months": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600,
      "description": "Number of monthly payments"
    },
    "payments_made": {
      "type": "integer",
      "minimum": 0,
      "maximum": 600,
      "description": "Optional: payments already made, to see progress so far"
    }
  },
  "required": [
    "amount",
    "annual_rate_pct",
    "months"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

How long a balance (credit card or loan) takes to pay off at a fixed monthly payment, and the interest paid. Use for "how long to pay off my card at $X a month" and for comparing a bigger payment by calling it twice.

{
  "type": "object",
  "properties": {
    "balance": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Balance owed today, in dollars"
    },
    "annual_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "Annual interest rate in percent"
    },
    "monthly_payment": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Fixed amount paid each month, in dollars"
    }
  },
  "required": [
    "balance",
    "annual_rate_pct",
    "monthly_payment"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compare two to four loan offers with different rates and fees fairly: each offer is sized so the borrower receives the same cash, then compared on payment, total cost of borrowing (interest plus fees) and estimated APR. Use for "is a lower rate with an origination fee cheaper than a higher rate with none".

{
  "type": "object",
  "properties": {
    "cash_needed": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Cash the borrower needs to receive, in dollars"
    },
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "maxLength": 60,
            "description": "A short name for the offer"
          },
          "annual_rate_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "months": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600
          },
          "fee_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 50,
            "description": "Origination fee as a percent of the loan, if any"
          },
          "fee_deducted": {
            "type": "boolean",
            "description": "True (default) if the fee is taken out of the loan before the money is paid out; false if it is added to the balance"
          }
        },
        "required": [
          "annual_rate_pct",
          "months"
        ],
        "additionalProperties": false
      },
      "minItems": 2,
      "maxItems": 4
    }
  },
  "required": [
    "cash_needed",
    "offers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For a payday loan, title loan, pawn loan, cash-advance app or any loan priced by a fee for a number of days: the fee in dollars, the APR, and what renewing (rolling over) costs. Use for "what is the APR on a $500 payday loan at $15 per $100" and "what does rolling it over cost".

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Amount borrowed, in dollars"
    },
    "fee_per_100": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Fee per $100 borrowed for one term, in dollars (e.g. 15)"
    },
    "flat_fee": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000,
      "description": "Any flat fee, tip or instant-transfer fee for one term, in dollars"
    },
    "term_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 366,
      "description": "Days until the loan is due"
    },
    "renewals": {
      "type": "integer",
      "minimum": 0,
      "maximum": 52,
      "description": "Times the loan is renewed or rolled over by paying only the fee"
    }
  },
  "required": [
    "amount",
    "term_days"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compare keeping a loan against a refinance offer, from today forward: interest remaining on the current loan, interest on the new loan, and what happens if the borrower takes the new rate but keeps paying the old payment. Use for "the new loan has a lower payment, does it actually save money".

{
  "type": "object",
  "properties": {
    "balance": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Balance owed today, in dollars"
    },
    "current_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "current_payment": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Current monthly payment, in dollars"
    },
    "new_rate_pct": {
      "$ref": "#/properties/current_rate_pct"
    },
    "new_months": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600,
      "description": "Term of the new loan in months"
    },
    "new_loan_fee": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000,
      "description": "Any fee added to the new loan, in dollars"
    }
  },
  "required": [
    "balance",
    "current_rate_pct",
    "current_payment",
    "new_rate_pct",
    "new_months"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For a precomputed or add-on interest loan (common from dealers, finance companies and furniture stores): the payoff after a number of payments under the Rule of 78s and under the actuarial method, and how much more the Rule of 78s keeps. Use for "why is my payoff different from my balance".

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Amount financed, in dollars"
    },
    "annual_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "Contract rate in percent"
    },
    "months": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600
    },
    "payments_made": {
      "type": "integer",
      "minimum": 0,
      "maximum": 600,
      "description": "Payments made so far"
    }
  },
  "required": [
    "amount",
    "annual_rate_pct",
    "months",
    "payments_made"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The interest a simple-interest loan adds each day, and over a number of days. Use for reading a payoff letter, for "how much more is my payoff than my statement balance", and for the cost of a skipped or deferred payment.

{
  "type": "object",
  "properties": {
    "balance": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Principal balance, in dollars"
    },
    "annual_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3660,
      "description": "Days of interest"
    }
  },
  "required": [
    "balance",
    "annual_rate_pct",
    "days"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Simulate paying off several debts with minimum payments plus an optional extra each month, highest rate first (avalanche) and smallest balance first (snowball), against minimums only. Returns months to debt-free and total interest for each. Use for "avalanche or snowball on my debts" and "what does $200 extra a month do".

{
  "type": "object",
  "properties": {
    "debts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 40
          },
          "balance": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000000
          },
          "annual_rate_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 1000
          },
          "min_payment": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 10000000,
            "description": "Minimum monthly payment, held fixed"
          }
        },
        "required": [
          "balance",
          "annual_rate_pct",
          "min_payment"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 12
    },
    "extra_per_month": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000,
      "description": "Extra paid each month on top of all minimums, in dollars"
    }
  },
  "required": [
    "debts"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The latest Federal Reserve (G.19) average interest rates at commercial banks for a 24-month personal loan, 60- and 72-month new car loans, and credit cards, with the change from the previous quarter and from a year earlier. Optionally compares a rate someone was offered with the average and gives the gap in dollars. Averages across banks, never any one lender; quarterly figures bundled with the server, not live quotes. Use for "what is the average car loan rate", "have personal loan rates gone up" and "is 9% high for a car loan".

{
  "type": "object",
  "properties": {
    "loan_type": {
      "type": "string",
      "enum": [
        "personal_loan_24_months",
        "new_car_loan_60_months",
        "new_car_loan_72_months",
        "credit_card"
      ],
      "description": "One kind of loan; leave out for all four"
    },
    "offered_rate_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "Optional: a rate the person was offered, to compare with the average (needs loan_type)"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "Optional with offered_rate_pct: amount borrowed or card balance, in dollars"
    },
    "months": {
      "type": "integer",
      "minimum": 1,
      "maximum": 600,
      "description": "Optional with offered_rate_pct: number of monthly payments"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}