US APR (Truth in Lending, Regulation Z) API
The annual percentage rate of a closed-end loan the way Regulation Z Appendix J defines it (actuarial method), with odd first periods and the accuracy tolerance.
POST https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z
- Version 1
- MCP tool
calc_finance_apr_us_reg_z - Try it in the browser
Computes the APR that US lenders must disclose under the Truth in Lending Act, using the actuarial method of Regulation Z, Appendix J: the rate per unit-period at which the payments, discounted back to consummation, equal the amount financed, times the number of unit-periods in a year. An odd first period is counted the way Appendix J counts it: full months back from the first payment date and the remaining days divided by 30, with simple interest for the fraction. Single-payment loans use the term as the unit-period. The equation is solved exactly and the APR is correctly rounded; the response also gives the finance charge and whether the 1/8 or 1/4 percentage point tolerance applies.
Formula
A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100
- One advance at consummation and payments at regular intervals, with an odd first period allowed; loans with several advances or irregular intervals are not covered yet.
- All months count as equal (Appendix J (b)(3)(iv)): an odd first period is the days counted forward from consummation to one full month before the first payment, divided by 30. When a month lacks the payment day, its last day is used.
- A single payment is a single advance, single payment transaction: its term is the unit-period ((b)(5)(vi) and (vii)). Without dates a weekly or biweekly payment is a term of 7 or 14 days, so 365 ÷ 7 or 365 ÷ 14 unit-periods a year; a semimonthly single payment needs dates.
- The APR is the exact solution of the Appendix J equation, rounded half up to 2 decimals by default; set options.decimals for more.
- Fees paid before or at consummation that are finance charges belong in the finance charge: subtract them from the loan amount to get the amount financed.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
amount_financed required |
decimal (string) | The amount financed: the credit the borrower receives, after any prepaid finance charges. Allowed: > 0 and <= 1000000000000000. Unit: currency. |
payment_amounts required |
list of decimal (string) | The payments in order. Give one amount per group of equal payments and the group sizes in payment_counts, e.g. ["210.71", "220.25"] with [24, 36]; without payment_counts each amount is one payment. 1 to 100 items. Each item: >= 0 and <= 1000000000000000. Unit: currency. |
payment_counts |
list of decimal (string) | How many payments of each amount in payment_amounts (whole numbers, same order). Omit it when every amount is a single payment. Up to 100 items. Each item: >= 1 and <= 1200. |
payment_frequency |
monthly | semimonthly | biweekly | weekly | quarterly | semiannually | annually default monthly |
How often payments are due; this is the unit-period. Options: monthly: 12 a year; semimonthly: 24 a year; biweekly: every 2 weeks, 26 a year; weekly: 52 a year; quarterly: 4 a year; semiannually: 2 a year; annually: once a year |
consummation_date |
date (YYYY-MM-DD) | When the loan is made (the finance charge starts). Give it with first_payment_date to count an odd first period; without both, the first payment is one full period after consummation. |
first_payment_date |
date (YYYY-MM-DD) | When the first payment is due. Later payments follow at the payment frequency. |
month_end_payments |
boolean default False |
Payments are due on the last day of each month, so months are counted from month end to month end (Appendix J (b)(3)(iv)). |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_up. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
apr_percent | decimal (string) | The annual percentage rate, in percent. Unit: percent. |
finance_charge | decimal (string) | Total of payments minus the amount financed. Unit: currency. |
total_of_payments | decimal (string) | Sum of all payments. Unit: currency. |
number_of_payments | integer | Number of payments. |
unit_period | string | The unit-period used. |
unit_periods_per_year | string | Unit-periods in a year; APR = rate per unit-period × this (exact). |
first_payment_unit_periods | integer | Full unit-periods from consummation to the first payment. |
first_period_fraction | string | The odd fraction of a unit-period before the first payment (0 for none). |
regular_transaction | boolean | True when the payments are equal (apart from the first and the last), so the 1/8 point tolerance applies; false for irregular payments (1/4 point). |
tolerance_percent | string | A disclosed APR within this many percentage points of the exact APR is accurate (Regulation Z § 1026.22(a)(2) and (3)). |
Examples
Regulation Z step-rate example: $10,000, 24 × $210.71, 24 × $220.25, 12 × $222.59
curl https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_financed": "10000",
"payment_amounts": ["210.71", "220.25", "222.59"],
"payment_counts": ["24", "24", "12"]
}'
{
"calculator": "finance/apr/us-reg-z@1",
"result": {
"apr_percent": "10.75",
"finance_charge": "3014.12",
"total_of_payments": "13014.12",
"number_of_payments": 60,
"unit_period": "month",
"unit_periods_per_year": "12",
"first_payment_unit_periods": 1,
"first_period_fraction": "0",
"regular_transaction": false,
"tolerance_percent": "0.25"
},
"exactness": {
"apr_percent": "rounded",
"finance_charge": "exact",
"total_of_payments": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"amount_financed": "10000",
"payment_amounts": [
"210.71",
"220.25",
"222.59"
],
"payment_counts": [
"24",
"24",
"12"
],
"payment_frequency": "monthly",
"month_end_payments": false
},
"formula": "A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100",
"references": [
{
"title": "Regulation Z, Appendix J: Annual percentage rate computations for closed-end credit transactions",
"url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/J/"
},
{
"title": "Regulation Z, official interpretation of § 1026.22 (step-rate and add-on rate examples, tolerances)",
"url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/Interp-22"
}
],
"warnings": []
}
$5,000 in 24 monthly payments of $230, first payment 34 days after the loan
curl https://api.curatedapi.com/v1/calc/finance/apr/us-reg-z \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_financed": "5000",
"payment_amounts": ["230"],
"payment_counts": ["24"],
"consummation_date": "2026-01-12",
"first_payment_date": "2026-02-15"
}'
{
"calculator": "finance/apr/us-reg-z@1",
"result": {
"apr_percent": "9.61",
"finance_charge": "520.00",
"total_of_payments": "5520.00",
"number_of_payments": 24,
"unit_period": "month",
"unit_periods_per_year": "12",
"first_payment_unit_periods": 1,
"first_period_fraction": "0.1",
"regular_transaction": true,
"tolerance_percent": "0.125"
},
"exactness": {
"apr_percent": "rounded",
"finance_charge": "exact",
"total_of_payments": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"amount_financed": "5000",
"payment_amounts": [
"230"
],
"payment_counts": [
"24"
],
"payment_frequency": "monthly",
"consummation_date": "2026-01-12",
"first_payment_date": "2026-02-15",
"month_end_payments": false
},
"formula": "A = Σ P_j / ((1 + f·i)(1 + i)^t_j); APR = i × unit-periods per year × 100",
"references": [
{
"title": "Regulation Z, Appendix J: Annual percentage rate computations for closed-end credit transactions",
"url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/J/"
},
{
"title": "Regulation Z, official interpretation of § 1026.22 (step-rate and add-on rate examples, tolerances)",
"url": "https://www.consumerfinance.gov/rules-policy/regulations/1026/Interp-22"
}
],
"warnings": []
}
References
- Regulation Z, Appendix J: Annual percentage rate computations for closed-end credit transactions
- Regulation Z, official interpretation of § 1026.22 (step-rate and add-on rate examples, tolerances)
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.