Quickstart

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

Numeratica is a developer-first API for US retirement and financial-planning math — Monte Carlo projections, taxes, RMDs, Social Security, Roth conversions, and more. 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 10,000-path retirement simulation. Pass a seed so the run is exactly reproducible.

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": 10000,
    "seed": 12345
  }'

3 · Read the result

Understand the response

{
  "result_id": "mc_5445a80e48d88d60",
  "engine_version": "montecarlo-1.0.0",
  "seed": 12345,
  "result": {
    "success_probability": 0.9026,
    "median_ending_balance": 16871636.36,
    "ending_balance_percentiles": {
      "p10": 102175.32,
      "p25": 6177105.71,
      "p50": 16871636.36,
      "p75": 36221935.82,
      "p90": 60601503.01
    },
    "median_depletion_age": 87,
    "num_simulations": 10000
  },
  "disclaimer": "Calculation engine output for informational purposes 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, IRMAA planning, RMD — each with a copy-the-source rendered output.