Integrate verified financial math in minutes

Quickstart (REST)

Three endpoints per model: the JSON contract (GET /api/v1/models/{model}), the full specification (…/spec), and execution (POST /api/v1/models/{model}). Discover models at GET /api/v1/models.

curl -s https://worthune.com/api/v1/models/relocation \
  -X POST -H 'content-type: application/json' \
  -d '{
    "currentSalary": 95000,
    "newSalary": 108000,
    "currentMonthlyExpenses": 4200,
    "newMonthlyExpenses": 4900,
    "movingCosts": 6000,
    "currentSavings": 40000,
    "annualReturn": 0.07,
    "yearsHorizon": 10
  }'

Or from JavaScript:

const res = await fetch(
  "https://worthune.com/api/v1/models/relocation",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(inputs), // per the model's contract
  },
);
const result = await res.json();
if (result.ok) {
  console.log(result.outputs.breakEvenMonths);
  console.log(result.specVersion, result.assumptions);
}

MCP setup (AI assistants)

Streamable-HTTP endpoint, no auth: https://worthune.com/api/mcp/mcp — listed in the official MCP registry as com.worthune/models.

• Claude: Settings → Connectors → Add custom connector → paste the endpoint URL.
• ChatGPT: Settings → Connectors (developer mode) → add the same URL.
• Tools: list_models (catalog) → get_model_contract (inputs, domains, sentinels; pass include_spec: true for the full spec) → run_model (validated execution).
• Handoff pattern: after a run, deep-link users to the matching interactive calculator with inputs prefilled, e.g. /scenarios/relocation?currentSavings=40000.

The response envelope

Every successful run returns the same shape — designed so a caller (human or AI) can show its work:

• outputs — the verified model outputs, untouched.
• specVersion / specUrl — the exact contract version that produced them.
• sentinels — special values explained (e.g. breakEvenMonths: 9999 means “never”), each with a triggered flag.
• assumptions — what the model held true for this run.
• facts — government constants used (value, tax year, primary source).
• record — a decision record: SHA-256 over the canonical JSON of {model, specVersion, inputs, outputs} (keys sorted recursively). Store it with anything built on these numbers; recompute it later to prove they came from that spec version, unaltered.
• inputs — echoed back; disclaimer — planning model, not advice.

Validation & errors

Inputs are validated against the spec's domains at the boundary. Out-of-domain values are rejected, never clamped — engine behavior outside a spec's domain is undocumented, and a silently adjusted answer is worse than an error. All fields are required; unknown fields are rejected.

HTTP 400
{
  "ok": false,
  "model": "relocation",
  "errors": [
    { "field": "newSalary", "message": "must be between 30000 and 300000" },
    { "field": "yearsHorizon", "message": "required" }
  ]
}

Unknown models return 404. Malformed JSON returns 400 with a single error message.

Conventions

• Rates are annual decimals (0.07 = 7%) unless a contract says otherwise (two models use percent points — their contracts and specs flag it prominently).
• Non-finite numbers are encoded as the strings "Infinity" / "NaN" (JSON has no representation for them).
• Chart arrays are part of the verified contract and returned in full.
• Model changes ship as spec version bumps — see the public changelog. Pin behavior by checking specVersion.
• Fair use is 5,000 runs a month per app — a guideline, not a meter (see pricing). A burst backstop of 120 requests/minute per IP returns 429 with a retry-after header; it stops runaway loops, never real users. Aggregate usage is public at /api/v1/telemetry.

Embeds — a verified calculator in one script tag

Drop any of the 27 calculators into your page. Prefill inputs with data-input-* attributes; the frame carries its own verification link and disclaimer. Free with the built-in attribution.

<div data-worthune-embed="relocation"
     data-height="720"
     data-input-currentSavings="40000"></div>
<script async src="https://worthune.com/embed.js"></script>

Eval datasets & the facts API

• /api/v1/evals — verified eval datasets for financial AI testing: 250 deterministic input/expected-output pairs per model as JSONL, the exact cases our dual-implementation harness runs in CI. Overview at /evals.
• /api/v1/facts — the sourced-constants registry (IRS limits, brackets, SSA factors) with primary sources, effective periods, and verification dates. Human-readable at /facts.

Model reference

Each page shows the model's input contract and a live request/response pair generated from the real engine: