# Loan apr compute

`loan-apr-compute` · version 1.0.0 · Financial calculations · free, no key needed

APR of an equal-payment loan net of prepaid fees under US Reg Z or the EU consumer credit directive.

**Use when you need to: APR of a loan with origination fee · annual percentage rate including prepaid finance charges · Regulation Z APR calculation.**

## Decide before calling

Read the [versioned contract](/v1/tools/loan-apr-compute/versions/1.0.0) and the supported scope below. Reuse `loan-apr-compute@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `loan-apr-compute@1.0.0` for APR of a loan with origination fee. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- APR of a loan with origination fee
- annual percentage rate including prepaid finance charges
- Regulation Z APR calculation
- EU APRC effective annual rate of a consumer loan
- true cost of a loan with fees
- compare loan offers by APR
- finance charge and total of payments of a loan
- real interest rate of a loan after fees

## Not supported

- odd first periods, odd days, irregular payments or multiple advances
- the Regulation Z 1/8 percent tolerance test and disclosure rounding
- converting a known nominal rate to an effective rate (use rate-nominal-effective-convert)
- credit card, revolving or variable-rate APR disclosures

## Behavior

- Inputs: method (required, us-reg-z or eu-ccd), principal (the loan amount before prepaid charges, greater than 0), fees (prepaid finance charges deducted from the advance, decimal at least 0 and below principal; default "0"), payment (greater than 0, the regular payment), periods (integer 1 to 1200, the number of payments), payments_per_year P (one of 1, 2, 4, 12, 24, 26, 52; default 12), final_payment (optional decimal greater than 0: the last payment when it differs, for example a balloon; default equal to payment), scale (0 to 12, default 2, for amounts), rate_scale (0 to 12, default 4, for rates) and rounding (default half-up). The payments are equally spaced one unit period 1/P year apart, the first one full unit period after the advance; odd first periods, odd days, irregular payments and multiple advances are not supported.
- Stream: amount_financed A = principal - fees. Payment k (k = 1 .. periods) equals payment, except payment number periods equals final_payment when it is supplied. total_of_payments = sum of all payments and finance_charge = total_of_payments - amount_financed (interest plus prepaid charges).
- Periodic (unit-period) rate i is the actuarial root of A = sum over k of payment_k / (1+i)^k (12 CFR 1026 Appendix J general equation for equal unit periods, and Directive 2008/48/EC Annex I with t_k = k/P years). The root is unique for i > 0 because the equation has one sign change.
- method us-reg-z: apr = P * i (a nominal annual rate, the unit-period rate times unit periods per year, Appendix J (b)(5)(ii)). method eu-ccd: apr = (1+i)^P - 1, the effective annual rate X of Annex I (the APRC). Both use the same i, so for P = 1 they are equal.
- If total_of_payments < amount_financed the result is not_computable (details.reason payments_below_amount_financed). If total_of_payments equals amount_financed exactly, i and apr are 0 and no solver runs. Otherwise i is found in binary64 on the fixed unit-period rate grid [0, 0.005, 0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1, 0.125, 0.15, 0.175, 0.2, 0.25, 0.3, 0.4, 0.5, 0.75, 1, 1.5, 2, 3, 5, 10, 20, 50, 100, 1000] by f(i) = sum payment_k*exp(-k*log1p(i)) - A (pinned fdlibm exp and log1p, terms summed in ascending k) and Brent's method (tolerance 1e-14, at most 200 iterations) on the bracketing interval. A root above 1000 is not_computable (no_root_in_range); non-convergence is not_computable (no_convergence). Accuracy is about 1e-12 absolute on i, so digits beyond rate_scale 10 are not guaranteed.
- apr and periodic_rate are computed from the exact binary value of the float root (apr = P*i exactly for us-reg-z, or (1+i)^P - 1 in exact arithmetic for eu-ccd) and rounded once to rate_scale. amount_financed, finance_charge and total_of_payments are exact sums rounded once to scale. method echoes the input.
- For method eu-ccd, an effective annual rate (1+i)^P - 1 of 1e20 or more (for example a unit-period rate near 1000 with 52 payments per year) cannot be represented: not_computable (details.reason overflow). us-reg-z apr = P*i is at most 52 * 1000 and cannot overflow.
- Regulation Z tolerance rules (1026.22(a)(2), 1/8 of 1 percentage point) and the disclosure rounding of the APR are not applied; the result is the mathematical APR at the requested precision.
- Every rounded output is rounded exactly once from the unrounded value using the rounding mode: half-up (ties away from zero, the default), half-even, half-down (ties toward zero), up (away from zero), down (toward zero), ceiling, floor. Amount outputs print exactly scale fractional digits and rate-like outputs exactly rate_scale fractional digits; a result that rounds to zero prints without a minus sign (never '-0.00').
- Decimal string fields (amounts, rates) must match ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$ with at most 20 integer digits and at most 20 fractional digits; a JSON number, exponent form, leading plus, surrounding spaces, percent sign, missing integer part or trailing dot is invalid_input. Rates are decimal fractions (0.065 means 6.5 percent; "6.5" means 650 percent). A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing.
- Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

## Input

- `method` (one of "us-reg-z", "eu-ccd", required)
- `principal` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `fees` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `payment` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `periods` (integer, required): min 1; max 1200
- `payments_per_year` (one of 1, 2, 4, 12, 24, 26, 52, optional)
- `final_payment` (string, optional): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `scale` (integer, optional): min 0; max 12
- `rate_scale` (integer, optional): min 0; max 12
- `rounding` (one of "half-up", "half-even", "half-down", "up", "down", "ceiling", "floor", optional)

## Output

- `apr` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `periodic_rate` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `amount_financed` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `finance_charge` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `total_of_payments` (string, required): max length 64; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`
- `method` (one of "us-reg-z", "eu-ccd", required)

## Limits

- max periods: 1200
- max string bytes: 64

## Example

Request input:

```json
{
  "method": "us-reg-z",
  "principal": "5000",
  "payment": "166.07",
  "periods": 36,
  "rate_scale": 4
}
```

Response:

```json
{
  "result": {
    "apr": "0.1200",
    "periodic_rate": "0.0100",
    "amount_financed": "5000.00",
    "finance_charge": "978.52",
    "total_of_payments": "5978.52",
    "method": "us-reg-z"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "loan-apr-compute",
  "version": "1.0.0",
  "input": {
    "method": "us-reg-z",
    "principal": "5000",
    "payment": "166.07",
    "periods": 36,
    "rate_scale": 4
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/loan-apr-compute/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"method":"us-reg-z","principal":"5000","payment":"166.07","periods":36,"rate_scale":4}'
```

The machine-readable contract is at [/v1/tools/loan-apr-compute/versions/1.0.0](/v1/tools/loan-apr-compute/versions/1.0.0).

### CLI

```sh
node cli.mjs run loan-apr-compute 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Loan amortization schedule](/tools/loan-amortization-schedule): Cent-exact level-payment loan schedule with per-period rounding, extra payments, dates and a row window.
- [Interest accrual compute](/tools/interest-accrual-compute): Simple or compound (periodic or continuous) interest over a term in years or a dated span with a day-count basis.
- [Rate nominal effective convert](/tools/rate-nominal-effective-convert): Convert an interest rate between nominal (periodic compounding), effective annual and continuous compounding forms.
- [Bond duration convexity](/tools/bond-duration-convexity): Macaulay and modified duration, convexity and DV01 of a fixed-coupon bond at a yield (Excel DURATION, MDURATION).
- [Cashflow mirr](/tools/cashflow-mirr): MIRR of periodic cash flows from a finance rate and a reinvestment rate, with compounded and discounted totals.
- [Growth cagr compute](/tools/growth-cagr-compute): CAGR from start and end values or a total return over years or dates, with a sub-year warning.