Quickstart

From zero to a reproducible retirement projection in under five minutes.

Numeratica is a developer-first API for US household-finance math — 76 calculators across retirement, tax, Social Security, equity compensation, insurance needs, education funding, mortgages, workplace benefits, debt, and portfolio mechanics, plus a batch endpoint that runs up to 20 of them in one call. Every result is deterministic and reproducible: same inputs and seed always return the same answer and the same result_id.

1 · Get an API key

Authenticate

Every /v1 call takes an API key as a bearer token. Swap the nmr_sk_test_xxx placeholder below for your own key — get a free one in seconds (no card; or email support@numeratica.com for higher limits). Health probes (/readyz) are public.

Try it from the docs. The API Reference has a built-in request client — drop in your own key and send real requests while you read. We don't publish a shared sandbox key, so there's nothing public to scrape or abuse: you always use your own.

Keep keys server-side in production. Never embed a key in client-side JavaScript or a public repo. Only the SHA-256 hash of your key is stored — it can't be recovered, only rotated.

2 · Make your first call

Retirement Monte Carlo

Project a 2,000-path retirement simulation. Pass a seed so the run is exactly reproducible. 2,000 paths is the free-tier ceiling, so this call works with the key you just created; paid keys run up to 200,000.

curl -X POST https://api.numeratica.com/v1/retirement/monte-carlo \
  -H "Authorization: Bearer nmr_sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "current_age": 40,
    "retirement_age": 65,
    "end_age": 95,
    "current_balance": 500000,
    "annual_contribution": 30000,
    "annual_spending": 60000,
    "expected_return": 0.07,
    "return_volatility": 0.12,
    "inflation": 0.025,
    "num_simulations": 2000,
    "seed": 12345
  }'

3 · Read the result

Understand the response

{
  "result_id": "mc_3c6918dbf2026099",
  "engine_version": "montecarlo-1.0.0",
  "seed": 12345,
  "result": {
    "success_probability": 0.8895,
    "median_ending_balance": 13659838.00,
    "ending_balance_percentiles": {
      "p10": 0,
      "p25": 4339230.65,
      "p50": 13659838.00,
      "p75": 29264810.45,
      "p90": 56257304.29
    },
    "median_depletion_age": 87,
    "num_simulations": 2000
  },
  "disclaimer": "Hypothetical projection from a stochastic model; simulated results do not reflect actual investment performance and are not a guarantee of future results. Informational only; not financial advice."
}

result_id — a content hash of the inputs + engine version. Run the same request again and you get the same id, so results are cacheable and auditable.
seed — echoed back. Reuse it to reproduce an exact run; omit it and the API generates one (and returns it) so the run is still reproducible.
success_probability — share of simulated paths that did not deplete before end_age. Here, 90.3%.
engine_version — pinned per engine; output only changes when this changes (see determinism).

What makes Numeratica different

Deterministic by design

Same inputs + seed → same result_id, byte-for-byte. Cache, diff, and audit results with confidence.

Sourced, kept-current data

Tax brackets, IRMAA, contribution limits and more are snapshotted from primary sources with checksums — we show our work.

Informational, not advice

Every response carries a disclaimer. Numeratica returns calculation-engine output; it does not provide financial advice.

Next steps

API Reference — every endpoint, generated from the OpenAPI spec with request and response schemas.
Core concepts — auth, determinism & result_id, seeds, the error model, and versioning.
Guides — retirement readiness, Roth conversion, student loans, college aid, insurance needs, rebalancing — each with a copy-the-source rendered output.