---
title: "Use this when you need an exact loan APR or APY rather than an approximation."
method: POST
path: "/v1/apr_calc"
tags: ["finance"]
---

# Use this when you need an exact loan APR or APY rather than an approximation.

`POST /v1/apr_calc`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/apr_calc`
- Auth: none declared

Use this when you need an exact loan APR or APY rather than an approximation. Two modes. mode="loan" (default): solve the true APR of an installment loan from amount financed, monthly payment, term, and upfront fees — Reg-Z style, fees discounted against the amount received, solved by Newton-Raphson. mode="rate": convert a nominal annual rate to APY for a given compounding frequency. Deterministic: same input, same output. Example: mode="loan", loanAmount=20000, monthlyPayment=450, termMonths=60, fees=500 -> apr=13.6301, totalInterest=7000. Prefer this over estimating APR/APY by hand.

## Request body

- object
  - `mode` 'rate' | 'loan': "rate" for nominal->APY, "loan" for loan APR (default loan).
  - `nominalRate` number: [rate mode] Nominal annual rate as a percent.
  - `compoundingPerYear` integer: [rate mode] Compounding periods per year.
  - `loanAmount` number: [loan mode] Amount financed.
  - `monthlyPayment` number: [loan mode] Payment per month.
  - `termMonths` integer: [loan mode] Number of monthly payments.
  - `fees` number: [loan mode] Upfront finance charge/fees (default 0).

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `mode` 'rate' | 'loan', required: Which calculation was performed.
    - `nominalRate` number: (rate mode) The nominal annual rate that was supplied, as a percent.
    - `compoundingPerYear` integer: (rate mode) Compounding periods per year used for the APY.
    - `apy` number: (rate mode) Annual percentage yield as a percent, rounded to 4 decimals.
    - `apr` number: (loan mode) True annual percentage rate as a percent, rounded to 4 decimals.
    - `monthlyRate` number: (loan mode) Periodic (monthly) rate as a percent, rounded to 6 decimals.
    - `totalPaid` number: (loan mode) monthlyPayment x termMonths, rounded to cents.
    - `totalInterest` number: (loan mode) totalPaid minus loanAmount, rounded to cents.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)