# Financial Calculator API (Loans, NPV/IRR, Bonds, Options) (`jumblemog/financial-calculator`) Actor

Loans and mortgages with amortization, savings goals, NPV, IRR and XIRR, bond yield and duration, option Greeks and implied volatility, depreciation and APR/APY, from one line.

- **URL**: https://apify.com/jumblemog/financial-calculator.md
- **Developed by:** [Jumble Mog](https://apify.com/jumblemog) (community)
- **Categories:** AI, Automation, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Financial Calculator API (Loans, NPV/IRR, Bonds, Options)

**Answer finance questions from one line of text.** Ask `$25,000 car loan at 7.9% for 60 months with $100 extra a month` and you get the payment, the full amortization schedule and how much interest the extra saves. One Actor covers seven kinds of questions:

- **Loans and mortgages**: the payment, total interest, a yearly and a payment-by-payment schedule, extra payments (monthly, yearly or lump sums), property tax, insurance, HOA and PMI, points and fees as an APR, the balance after a time. It also works backwards: how much you can borrow, how long a payment takes, or what rate a payment implies.
- **Savings and investments**: future value with deposits or withdrawals, the monthly amount to reach a goal, present value, years to a goal or until money runs out, the rate of return (CAGR), and values in today's money after inflation.
- **Cash flows**: NPV, IRR (every IRR when the signs change more than once), MIRR, payback, discounted payback, the profitability index, and XIRR and XNPV for dated flows.
- **Bonds**: the price from a yield or the yield from a price, accrued interest, current yield, Macaulay and modified duration, convexity, DV01, yield to call and yield to worst.
- **Options**: Black-Scholes-Merton prices for European options and a binomial tree for American ones, with delta, gamma, vega, theta and rho, implied volatility from a market price, breakeven and the risk-neutral chance of finishing in the money.
- **Depreciation**: straight-line, declining balance (200% or 150%, switching to straight-line), sum-of-the-years' digits and MACRS (IRS tables).
- **Interest rates**: APR to APY and back at any compounding, and real rates after inflation.

Each answer comes with a **chart** and a **Markdown report**.

It's made for:

- AI agents and chatbots that need exact money math instead of a guess: language models are unreliable at IRR, amortization and option Greeks.
- Fintech, real estate, lending and personal-finance apps that need an API for loan, savings or investment numbers.
- Analysts, students and teachers who want the full working (schedules, cash-flow tables and formulas) next to the answer.

![A chart made by this Actor for a $320,000 mortgage at 6.5% for 30 years with $200 extra a month: $2,022.62 a month, paid off in 23.4 years, saving $105,429 of interest; yearly bars of principal and interest and the balance with and without the extra payments](https://api.apify.com/v2/key-value-stores/Km5b4PG3kYHdZSb1E/records/financial-calculator-example.png?signature=naE2nHUaIWTX74XC5KL3)

### How to use it

1. Write **Requests**, one per question. The form has examples.
2. Optionally set the default **currency symbol** and the **risk-free rate** for options.
3. Click **Start**. Each request is a row in the results, with its summary, tables, chart and report.

#### What you can write

| You write | You get |
|---|---|
| `$25,000 car loan at 7.9% for 60 months`, `$400k home 20% down 6.5% 30 years` | Payment, interest, schedule |
| `... property tax 1.2%, insurance $1,500 a year, HOA 200 a month, PMI 0.5%` | The full monthly payment |
| `... $200 extra a month`, `$1,000 extra a year`, `lump sum $10,000 in year 3` | Payoff time and interest saved |
| `... 1 point and $4,000 closing costs`, `... balance after 5 years` | APR; the balance then |
| `how much can I borrow paying $2,000 a month at 6% for 30 years`, `pay off $8,000 at 22% paying $300 a month` | The loan amount; the months to pay off |
| `save $500 a month for 30 years at 7% with 3% inflation` | Future value, also in today's money |
| `how much a month to reach $1,000,000 in 25 years at 6%`, `present value of $50,000 in 10 years at 4%` | The amount to save; the amount today |
| `CAGR from $10,000 to $25,000 over 7 years`, `$1,000,000 at 5% withdrawing $60,000 a year, how long` | The rate; the years |
| `NPV and IRR at 8% of -10000, 3000, 4200, 6800`, `NPV at 10%: invest 50000 then 15000 a year for 5 years` | NPV, IRR, MIRR, payback |
| `xirr 2024-01-01 -10000, 2024-06-30 2000, 2025-03-15 9500` | XIRR (and XNPV with a rate) |
| `5% coupon bond, 10 years, yield 6%`, `price 97.5, callable in 3 years at 101`, `zero coupon 5 years ytm 4.5%` | Price or yield, duration, convexity, yield to call |
| `call option S=100 K=105 30 days vol 25% r 4%`, `american put on a $50 stock, strike 50, 5 months, vol 40%` | Price and Greeks |
| `implied vol of a call priced 4.2, S 100, strike 105, 6 months` | Implied volatility |
| `MACRS 7 year on $120,000`, `double declining $50,000 machine, $5,000 salvage, 5 years` | Depreciation schedule |
| `6% APR compounded monthly to APY`, `APY 5% with 3% inflation` | Effective, nominal and real rates |

#### As objects

Give `type` and that type's fields (rates in %, times in years unless named):

| type | Fields |
|---|---|
| `loan` | `principal` or `price` with `downPct`/`downPayment`, `ratePct`, `years` or `months`, `paymentsPerYear`, `payment`, `extra`, `extraPerYear`, `lumps` \[{`year`, `amount`}], `taxPerYear` or `taxPct`, `insurancePerYear`, `hoaPerMonth`, `pmiPct`, `fees`, `pointsPct`, `afterYears` |
| `savings` | `pv`, `pmt` (negative = withdrawal), `fv`, `ratePct`, `years`, `perYear`, `compounding`, `timing` (`begin`/`end`), `inflationPct`, `solveFor` (`fv`, `pmt`, `pv`, `years`, `rate`) |
| `cashflows` | `flows`, `dates`, `ratePct`, `financePct`, `reinvestPct`, `perYear` |
| `bond` | `face`, `couponPct`, `years` or `maturity`, `frequency`, `price` (per 100) or `yieldPct`, `callYears`, `callPrice` |
| `option` | `kind`, `style`, `spot`, `strike`, `days`/`years`/`expiry`, `volPct` or `price`, `ratePct`, `dividendPct` |
| `depreciation` | `cost`, `salvage`, `life`, `method` (`sl`, `ddb`, `db150`, `syd`, `macrs`), `factor` |
| `rate` | `ratePct` with `compounding`, or `apyPct`; `inflationPct` |

For example `{"type": "loan", "principal": 250000, "ratePct": 6, "years": 15}`. A `text` field is read first and the other fields override it.

### Examples

- `$25,000 car loan at 7.9% for 60 months with $100 extra a month` → $505.71 a month, $5,343 interest; the extra pays it off in 4.1 years and saves $1,074.
- `mortgage on a $400,000 home, 20% down, 6.5% for 30 years, property tax 1.2%, insurance $1,500 a year` → $2,022.62 principal and interest, $2,547.62 with tax and insurance.
- `save $500 a month for 30 years at 7%` → $609,985 ($180,000 put in, $429,985 growth).
- `NPV and IRR at 8% of -10000, 3000, 4200, 6800` → NPV $1,776.66, IRR 16.34%, payback 2.41 years.
- `5% coupon bond, 10 years, yield 6%` → 92.561 per 100, modified duration 7.67, convexity 71.8.
- `call option S=100 K=105 30 days vol 25% r 4%` → 1.1677, delta 0.275, theta −0.043 a day.
- `MACRS 7 year on $120,000` → $17,148 in year 1, $29,388 in year 2.

### How-to examples

Each example below is a complete input. The result line is what the run says in `summary`.

#### How to calculate a loan payment and an amortization schedule

```json
{"requests": ["$25,000 car loan at 7.9% for 60 months with $100 extra a month"]}
```

Result: "$25,000 at 7.9% for 5 years: $505.71 a month; $5,343 interest, $30,343 in all; $100 extra a month pays it off in 4.1 years and saves $1,074 interest." The month-by-month schedule comes with it.

#### How to find how long it takes to pay off a credit card

```json
{"requests": ["how long to pay off $8,000 credit card at 22% paying $300 a month"]}
```

Result: "$8,000 at 22% paying $300 a month is paid off in 37 months (3.1 years); $3,083 interest." The value you leave out, here the time, is the one it solves for.

#### How to calculate NPV, IRR and payback

```json
{"requests": ["NPV and IRR at 8% of -10000, 3000, 4200, 6800", "save $500 a month for 30 years at 7%"]}
```

Result: "NPV at 8% is $1,776.66; IRR 16.34%; MIRR 14.05%; payback 2.41 years." and "$500 a month for 30 years at 7% grows to $609,985 ($180,000 put in, $429,985 growth)." Several calculations of different kinds fit in one run.

#### How to let an AI agent do financial math

Add this Actor to the [Apify MCP server](https://mcp.apify.com) with `https://mcp.apify.com/?tools=jumblemog/financial-calculator`. The agent passes the user's question as written, such as "mortgage on a $400,000 home, 20% down, 6.5% for 30 years", and gives back the `summary` instead of doing the math itself.

### FAQ

**What can it calculate?** Loans and mortgages (with tax, insurance and extra payments), savings and retirement growth, present and future value, NPV, IRR and MIRR, bond prices and duration, Black-Scholes options with Greeks, and depreciation, including MACRS.

**Do I need to fill in fields?** No. Write the calculation in plain words, or as an object such as `{"type": "loan", "principal": 250000, "ratePct": 6, "years": 15}`.

**Which currency does it use?** Dollars by default. Set `currency` for another one.

**How does it calculate?** With the standard time-value-of-money formulas, the same ones behind Excel's PMT, NPV and IRR. **How it works** below lists them.

**Does it work with Zapier, Make or n8n?** Yes. Call the Actor with its Apify app or an HTTP request and pass `summary` on.

### Output

One dataset item per request, also saved together in the run's `OUTPUT` record:

```json
{
  "request": 1, "status": "ok", "type": "loan", "title": "Loan: $25,000 at 7.9% for 5 years",
  "summary": "$25,000 at 7.9% for 5 years: $505.71 a month; $5,343 interest, $30,343 in all; $100 extra a month pays it off in 4.1 years and saves $1,074 interest.",
  "loan": {"principal": 25000.0, "ratePct": 7.9, "years": 5.0, "paymentsPerYear": 12, "payment": 505.71, "payments": 60.0, "totalInterest": 5342.85, "totalPaid": 30342.85, "extraPerPayment": 100.0, "payoffPayments": 49, "payoffYears": 4.08, "interestSaved": 1074.08, "...": "..."},
  "yearly": [{"year": 1, "interest": 1779.06, "principalPaid": 5489.51, "extra": 1200.0, "balance": 19510.49, "balanceWithoutExtra": 20754.91}, "..."],
  "schedule": [{"n": 1, "payment": 505.71, "interest": 164.58, "principal": 341.13, "extra": 100.0, "balance": 24558.87}, "..."],
  "units": {"currency": "$", "rates": "% a year unless named otherwise", "time": "years"}
}
```

Each type has its own keys: `loan`, `yearly` and `schedule`; `savings` and `yearly`; `cashFlows` and `flows`; `bond`, `bondFlows` and `curve`; `option`, `greeks`, `otherSide` and `curve`; `depreciation` and `depSchedule`; `rates` and `conversions`. Every item has `warnings`, `notes` (every assumption and default), a Markdown `report` and links to the chart and report. A request that can't be computed has `"status": "failed"` and the reason in `error`, and isn't billed.

### How it works

1. **Loans**: payment = P × r ÷ (1 − (1 + r)^−n) with r the rate per payment; each payment pays the interest on the balance and the rest goes to principal. Extra payments go straight to principal. APR is the rate at which the payments repay the loan less fees and points. PMI stops when the balance reaches 78% of the price.
2. **Savings**: balance = PV(1 + r)^n + PMT × ((1 + r)^n − 1) ÷ r (× (1 + r) for deposits at the start), solved for whichever value is missing; other compounding is converted to a rate per deposit.
3. **Cash flows**: the first flow is now; IRR and XIRR are found by scanning for every sign change of the NPV and refining each; XIRR discounts by (1 + rate)^(days ÷ 365) like Excel.
4. **Bonds**: cash flows from the next coupon, with the fraction of a period to it and the accrued interest; yields compound with the coupons (bond-equivalent yield).
5. **Options**: Black-Scholes-Merton with a continuous dividend yield; American options on a 400-step Cox-Ross-Rubinstein tree, with Greeks by bumping it; implied volatility by bisection.
6. **Depreciation**: MACRS from IRS Publication 946 Table A-1 (half-year convention); declining balance switches to straight-line when that's larger, like Excel's VDB.

### Pricing

You pay one low price per calculation, at the price shown on this page. The charts and report are included. Requests that can't be computed are never charged. If you set a maximum cost per run, the Actor stops before a request that wouldn't fit.

### Speed

A request takes milliseconds (an American option about a second). A run through the API answers in about 10 seconds, including the cloud container starting.

### Tips and limits

- **Estimates, not advice**: lenders round, count days and charge fees in their own ways; use the numbers to compare and check, and confirm with the lender, issuer or a tax adviser.
- **Bonds** are priced as if settled today, a fraction of a period before the next coupon; day-count conventions (30/360, actual/actual) can move the accrued interest slightly.
- **Options** are priced with a constant volatility and rate; the chance in the money is risk-neutral, not a forecast.
- **MACRS** uses the half-year convention without bonus depreciation or Section 179.
- **Limits**: 200 requests per run; schedules up to 2,400 payments.

### For AI agents and developers

This Actor works with the [Apify MCP server](https://mcp.apify.com), so AI agents can call it as a tool. Pass `requests` as plain text and read `summary`, the type's keys (`loan`, `savings`, `cashFlows`, `bond`, `option`, `depreciation`, `rates`) and `warnings`. A direct API call that waits for the answer:

```bash
curl -X POST "https://api.apify.com/v2/acts/jumblemog~financial-calculator/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requests": ["$300,000 mortgage at 6.75% for 30 years with $250 extra a month"]}'
```

`run-sync` instead returns the run's `OUTPUT`: the status, the counts and every result as JSON.

In Python, with the `apify-client` package:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("jumblemog/financial-calculator").call(run_input={
    "requests": [{"type": "cashflows", "flows": [-50000, 12000, 15000, 18000, 21000], "ratePct": 9}],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["summary"])
```

### Credits

- Methods: standard time-value-of-money and amortization formulas; bond pricing as in Fabozzi's *Bond Markets, Analysis and Strategies*; Black-Scholes-Merton and the Cox-Ross-Rubinstein tree as in Hull's *Options, Futures, and Other Derivatives*; MACRS rates from IRS Publication 946.
- Charts: [Vega-Lite](https://vega.github.io/vega-lite/) and [vl-convert](https://github.com/vega/vl-convert) (BSD-3-Clause), with the [Inter](https://rsms.me/inter/) font (SIL Open Font License).

# Actor input Schema

## `requests` (type: `array`):

One calculation per entry, as a line of text or an object. Loans: '$25,000 car loan at 7.9% for 60 months', '$400k home 20% down 6.5% 30 years, tax 1.2%, insurance $1,500 a year, PMI 0.5%', '$200 extra a month', 'balance after 5 years', '1 point and $4,000 closing costs' (APR), 'how much can I borrow paying $2,000 a month at 6% for 30 years'. Savings: 'save $500 a month for 30 years at 7%', 'how much a month to reach $1,000,000 in 25 years at 6%', 'CAGR from $10,000 to $25,000 over 7 years', '$1,000,000 at 5% withdrawing $60,000 a year, how long'. Cash flows: 'NPV and IRR at 8% of -10000, 3000, 4200, 6800', 'xirr 2024-01-01 -10000, 2025-03-15 12000'. Bonds: '5% coupon bond, 10 years, yield 6%' or 'price 95', 'callable in 3 years at 101'. Options: 'call S=100 K=105 30 days vol 25% r 4%', 'american put ...', 'implied vol of a call priced 4.2 ...'. Depreciation: 'MACRS 7 year on $120,000', 'double declining $50,000, $5,000 salvage, 5 years'. Rates: '6% APR compounded monthly to APY'. Objects take type (loan, savings, cashflows, bond, option, depreciation, rate) and that type's fields, e.g. {"type": "loan", "principal": 250000, "ratePct": 6, "years": 15}; see the README for every field.

## `currency` (type: `string`):

Shown before amounts when a request doesn't use a symbol ($ by default; e.g. €, £).

## `riskFreePct` (type: `number`):

For options when a request doesn't give one (4% by default).

## `charts` (type: `boolean`):

A loan's yearly principal, interest and balance; savings growth; cash flows; a bond's price-yield curve; an option's value against the stock; a depreciation schedule.

## Actor input object example

```json
{
  "requests": [
    "$25,000 car loan at 7.9% for 60 months with $100 extra a month",
    "mortgage on a $400,000 home, 20% down, 6.5% for 30 years, property tax 1.2%, insurance $1,500 a year",
    "save $500 a month for 30 years at 7% with 3% inflation",
    "NPV and IRR at 8% of -10000, 3000, 4200, 6800",
    "5% coupon bond, 10 years, price 95",
    "call option S=100 K=105 30 days vol 25% r 4%",
    {
      "type": "depreciation",
      "cost": 120000,
      "method": "macrs",
      "life": 7
    }
  ],
  "charts": true
}
```

# Actor output Schema

## `results` (type: `string`):

One row per request: the summary and chart.

## `output` (type: `string`):

The OUTPUT record: every result in one JSON object.

## `files` (type: `string`):

Charts (PNG and SVG) and Markdown reports in the run's key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "requests": [
        "$25,000 car loan at 7.9% for 60 months with $100 extra a month",
        "mortgage on a $400,000 home, 20% down, 6.5% for 30 years, property tax 1.2%, insurance $1,500 a year",
        "save $500 a month for 30 years at 7% with 3% inflation",
        "NPV and IRR at 8% of -10000, 3000, 4200, 6800",
        "5% coupon bond, 10 years, price 95",
        "call option S=100 K=105 30 days vol 25% r 4%",
        {
            "type": "depreciation",
            "cost": 120000,
            "method": "macrs",
            "life": 7
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jumblemog/financial-calculator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "requests": [
        "$25,000 car loan at 7.9% for 60 months with $100 extra a month",
        "mortgage on a $400,000 home, 20% down, 6.5% for 30 years, property tax 1.2%, insurance $1,500 a year",
        "save $500 a month for 30 years at 7% with 3% inflation",
        "NPV and IRR at 8% of -10000, 3000, 4200, 6800",
        "5% coupon bond, 10 years, price 95",
        "call option S=100 K=105 30 days vol 25% r 4%",
        {
            "type": "depreciation",
            "cost": 120000,
            "method": "macrs",
            "life": 7,
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("jumblemog/financial-calculator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "requests": [
    "$25,000 car loan at 7.9% for 60 months with $100 extra a month",
    "mortgage on a $400,000 home, 20% down, 6.5% for 30 years, property tax 1.2%, insurance $1,500 a year",
    "save $500 a month for 30 years at 7% with 3% inflation",
    "NPV and IRR at 8% of -10000, 3000, 4200, 6800",
    "5% coupon bond, 10 years, price 95",
    "call option S=100 K=105 30 days vol 25% r 4%",
    {
      "type": "depreciation",
      "cost": 120000,
      "method": "macrs",
      "life": 7
    }
  ]
}' |
apify call jumblemog/financial-calculator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jumblemog/financial-calculator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/TK50mVucspWskrdK7/builds/K6SDDQQX41ZH9nhEg/openapi.json