---
title: "Solve a time-value-of-money problem"
method: POST
path: "/v1/tvm"
tags: ["Utilities"]
---

# Solve a time-value-of-money problem

`POST /v1/tvm`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tvm`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Relates the five standard variables (rate, nper, pmt, pv, fv) and solves for the one named in solve_for given the other four. Sign convention: cash you pay out is negative, cash you receive is positive. rate is the interest rate per period; nper is the number of periods. Deterministic.

## Request body

- TVMRequest
  - `solve_for` 'fv' | 'pv' | 'pmt' | 'rate' | 'nper', required: Which variable to solve for. The other four must be supplied.
  - `rate` number: Interest rate per period (> -1, magnitude <= 100). Required unless solving for rate.
  - `nper` number: Number of periods (> 0, <= 100000). Required unless solving for nper.
  - `pmt` number: Payment per period (negative = outflow).
  - `pv` number: Present value (negative = outflow).
  - `fv` number: Future value.
  - `payments_at_beginning` boolean: If true, payments occur at the start of each period (annuity due).

## Response `200`

Solved variables

- TVMResponse
  - `result_id` string
  - `engine_version` string
  - `solve_for` string
  - `inputs` TVMRequest
    - `solve_for` 'fv' | 'pv' | 'pmt' | 'rate' | 'nper', required: Which variable to solve for. The other four must be supplied.
    - `rate` number: Interest rate per period (> -1, magnitude <= 100). Required unless solving for rate.
    - `nper` number: Number of periods (> 0, <= 100000). Required unless solving for nper.
    - `pmt` number: Payment per period (negative = outflow).
    - `pv` number: Present value (negative = outflow).
    - `fv` number: Future value.
    - `payments_at_beginning` boolean: If true, payments occur at the start of each period (annuity due).
  - `result` object: The full, consistent set of variables with the solved value filled in.
    - `rate` number
    - `nper` number
    - `pmt` number
    - `pv` number
    - `fv` number
  - `disclaimer` string

## Other responses

- `400`: Invalid request or no solution
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)