---
title: "Use this when you have four of the five time-value-of-money variables (N periods, I/Y annual rate percent, PV, PMT, FV) and need the fifth - annuity, loan, or investment problems - instead of solving the equation by hand."
method: POST
path: "/v1/tvm_solve"
tags: ["finance"]
---

# Use this when you have four of the five time-value-of-money variables (N periods, I/Y annual rate percent, PV, PMT, FV) and need the fifth - annuity, loan, or investment problems - instead of solving the equation by hand.

`POST /v1/tvm_solve`

## Request

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

Use this when you have four of the five time-value-of-money variables (N periods, I/Y annual rate percent, PV, PMT, FV) and need the fifth - annuity, loan, or investment problems - instead of solving the equation by hand. Solving for I/Y uses Newton-Raphson (no closed form). Supports compoundingPerYear and annuityDue (payments at the beginning of each period). Follows the cash-flow sign convention (outflows negative). Deterministic: same input, same output. Example: solveFor 'fv', n 120, iy 6, pv -10000, pmt -200, compoundingPerYear 12 -> result 50969.84. result holds the solved value; iy is rounded to 4 decimals, all others to 2.

## Request body

- object
  - `solveFor` 'n' | 'iy' | 'pv' | 'pmt' | 'fv', required: Which variable to solve for.
  - `n` number: Number of periods.
  - `iy` number: Interest rate per year as a percent.
  - `pv` number: Present value (cash-flow sign convention).
  - `pmt` number: Payment per period.
  - `fv` number: Future value.
  - `compoundingPerYear` integer: Compounding periods per year (default 1).
  - `annuityDue` boolean: True if payments occur at the beginning of each period (default false = ordinary annuity).

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `solveFor` 'n' | 'iy' | 'pv' | 'pmt' | 'fv', required: Echo of which variable was solved for.
    - `result` number, required: The solved value (iy in percent, rounded to 4 decimals; n/pv/pmt/fv rounded to 2).
    - `compoundingPerYear` integer, required: Compounding periods per year used (default 1).
    - `annuityDue` boolean, required: True if payments were treated as beginning-of-period (annuity due).

## 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)