v1 API · live for partners

Financial planning,
as an API.

Maven is a deterministic, multi-decade planning engine you can call over HTTP. Monthly projections, full tax engine, Monte Carlo, Roth-ladder optimization, and asset-location rebalancing — with an integrated AI agent that answers natural-language questions about any specific case. No UI, no per-advisor seats, no per-plan vendor lock-in.

Request access See the API

1 reqfull multi-decade plan

Deterministicsame seed, same answer

AI agentnatural-language Q&A on any case

# Run a full multi-decade plan in one call.
$ curl https://api.mavenfin.tech/v1/projections \
    -H "Authorization: Bearer mvn_live_••••" \
    -H "Content-Type: application/json" \
    -d @household.json

{
  "projectionId":     "prj_01J9PXR2A4QWZB3VKM8YH7C1FE",
  "succeeded":        true,
  "longevityMonths":  348,
  "longevityPercent": 1.00,
  "endingAssets": {
    "totalValue":     440944000,
    "npvTotalValue":  228390000
  },
  "_links": {
    "annualResults": "/v1/projections/prj_…/years",
    "monteCarlo":    "/v1/projections/prj_…/monteCarlo",
    "rothLadder":    "/v1/projections/prj_…/rothLadder",
    "rebalance":     "/v1/projections/prj_…/rebalance/preview"
  }
}

# Same seed, same answer. Try it.
POST /v1/projections/prj_…/monteCarlo
{
  "iterations": 1000,
  "rng":        "well1024a",
  "seed":       42
}

HTTP/1.1 200 OK
{
  "successRate":   0.962,
  "longevityPercentiles": {
    "p5":  273,  "p50": 348,  "p95": 348
  },
  "endingNetWorthPercentiles": {
    "p5":   12400000,
    "p50":  441200000,
    "p95": 1820600000
  },
  "reproducible": true,
  "rerunHash":    "sha256:6fa9c2…"
}

Built for

RIAs & advisor platforms Direct-to-consumer fintech Custodians & TAMPs CPA & tax-software vendors

01 — Capabilities

What the engine does today.

A complete monthly cash-flow planning engine — every account type, every tax wrinkle, every named withdrawal strategy. Production-grade, deterministic, audit-ready.

Multi-decade monthly projection

Monthly cash-flow across taxable, tax-deferred, Roth, and HSA accounts — typically projection start through latest life-expectancy, capped at +70 years.

Full tax engine

Federal AGI, AMT, NIIT, IRMAA tiers, all 7 federal brackets, state tax, taxable Social Security, capital gains, qualified dividends, standard vs. itemized.

Every withdrawal sequence

ConventionalWisdom, OppositeCW, CW-with-Roth, TaxDeferredFirst, TaxDeferredWithLimit, and Custom — with phase-switching at the retirement-age boundary.

RMDs, Roth conversions & rebalancing

IRS Uniform Lifetime & Joint Life tables, threshold-fill Roth solver, and asset-location-aware rebalancing across every account class.

Deterministic Monte Carlo

Same seed → same hash, every time. Required for compliance, plan archives, and reproducible audits — most planners can't say this.

Built-in AI agent

Ask plain-English questions about any plan over the API — “why does CW-with-Roth beat CW here?”, “where does this plan break under a 2008 sequence?”. Answers cite the exact year-records.

Survivor & household lifecycle

Wage, pension, spending streams with survivor-amount reductions; HSA and account transitions on death; Married, Single, Widowed, Divorced gating.

Real-time streaming

Long projections stream per-year results back over text/event-stream — drop straight into a progress UI or pipe into your own analytics.

02 — API

One request. Full plan.

Every endpoint returns deterministic, archivable JSON. Embed the engine behind your own UI — no CRM, no per-advisor seats, no per-plan licensing.

POST /v1/projections

POST /v1/projections

{
  "household": {
    "type": "Married",
    "client": { "dob": "1962-04-15", "lifeExpectancy": 92, "state": "IL" },
    "spouse": { "dob": "1964-09-08", "lifeExpectancy": 95, "state": "IL" }
  },
  "accounts": [
    { "type": "Taxable",        "owner": "Client", "marketValue":  75000000 },
    { "type": "TraditionalIRA", "owner": "Client", "marketValue": 142500000 },
    { "type": "RothIRA",        "owner": "Spouse", "marketValue":  61000000 },
    { "type": "HealthSavings",  "owner": "Client", "marketValue":   4500000 }
  ],
  "projection": {
    "startYear": 2026,
    "withdrawalSequence": "ConventionalWisdomWithRoth",
    "discountRate": 3.0
  }
}

→ 200 OK
{
  "projectionId":    "prj_01J9PXR2A4QWZB3VKM8YH7C1FE",
  "succeeded":       true,
  "longevityMonths": 348,
  "endingAssets": {
    "totalValue":    440944000,
    "npvTotalValue": 228390000
  }
}

POST /v1/projections/prj_…/rothLadder

{
  "fillToMarginalRate": 22.0,
  "respectIrmaaTier":   1,
  "years": [2027, 2028, 2029, 2030, 2031, 2032, 2033]
}

→ 200 OK
{
  "ladder": [
    { "year": 2027, "convert": 5430000, "marginalAfter": 22.0, "irmaaTier": 1 },
    { "year": 2028, "convert": 5612000, "marginalAfter": 22.0, "irmaaTier": 1 },
    { "year": 2029, "convert": 5800000, "marginalAfter": 22.0, "irmaaTier": 1 },
    { "year": 2030, "convert": 5993000, "marginalAfter": 22.0, "irmaaTier": 1 }
  ],
  "lifetimeTaxSavings":   8420600,
  "endingNetWorthDelta": 42180000
}

POST /v1/projections/compare

{
  "baseInputs": { "$ref": "prj_01J9PXR2A4QWZB3VKM8YH7C1FE" },
  "vary": "withdrawalSequence",
  "values": [
    "ConventionalWisdom",
    "OppositeConventionalWisdom",
    "ConventionalWisdomWithRoth",
    "TaxDeferredFirst",
    "TaxDeferredWithLimit"
  ]
}

→ 200 OK
{
  "results": [
    { "label": "ConventionalWisdom",         "endingValue": 412840000, "totalTax": 48720000 },
    { "label": "OppositeConventionalWisdom", "endingValue": 387210000, "totalTax": 32940000 },
    { "label": "ConventionalWisdomWithRoth", "endingValue": 444208000, "totalTax": 41360000 },
    { "label": "TaxDeferredFirst",           "endingValue": 401118000, "totalTax": 52614000 }
  ],
  "best": {
    "byEndingValue":   "ConventionalWisdomWithRoth",
    "byLifetimeTax":   "OppositeConventionalWisdom"
  }
}

POST /v1/projections/prj_…/monteCarlo

{
  "iterations": 1000,
  "rng":        "well1024a",
  "seed":       42,
  "returnAssumptions": {
    "equity": { "mean": 7.0, "stdev": 18.0 },
    "bond":   { "mean": 4.0, "stdev":  6.0 }
  }
}

→ 200 OK
{
  "successRate": 0.962,
  "longevityPercentiles": {
    "p5": 273, "p50": 348, "p95": 348
  },
  "endingNetWorthPercentiles": {
    "p5": 12400000, "p50": 441200000, "p95": 1820600000
  },
  "reproducible": true,
  "rerunHash":    "sha256:6fa9c2…"
}
// Same seed → same hash. Most planners can't say that.

POST /v1/projections/prj_…/rebalance/preview

{
  "asOf": "2030-12",
  "targetAllocation": {
    "equity_US_large": 0.30,
    "equity_intl":     0.20,
    "bond_total":      0.30,
    "cash":            0.05
  },
  "taxLocationStrategy": "tax_efficient"
}

→ 200 OK
{
  "trades": [
    { "account": "Taxable", "sell": "bond_total",      "amount": 4200000 },
    { "account": "Taxable", "buy":  "equity_US_large", "amount": 4200000 },
    { "account": "TDA",     "sell": "equity_US_large", "amount": 3800000 },
    { "account": "Roth",    "buy":  "equity_intl",     "amount": 1100000 }
  ],
  "rationale": [
    "Bonds moved to TDA (tax-inefficient → tax-deferred)",
    "International equity preferred in Roth (max growth, no future tax)"
  ],
  "estimatedYearOneAlpha": 28400
}

GET /v1/projections/prj_…/medicare

→ 200 OK
{
  "perYear": [
    { "year": 2027, "magi": 12300000, "tier": 0, "total": 2262000 },
    { "year": 2028, "magi": 18400000, "tier": 1, "total": 3255600 },
    { "year": 2029, "magi": 22800000, "tier": 2, "total": 4822800 },
    { "year": 2030, "magi": 19200000, "tier": 1, "total": 3255600 }
  ],
  "lifetimePremiumTotal": 68400000,
  "tierBreakdown":        { "tier0": 18, "tier1": 7, "tier2": 4 },
  "warningsIfRothConvert": [
    "2027 → tier 0  (headroom $4,200)",
    "2028 → tier 1  (already in; $19,800 headroom before tier 2)"
  ]
}

POST /v1/projections/prj_…/ask

{
  "question": "Why does ConventionalWisdomWithRoth beat ConventionalWisdom by $31M in this plan?",
  "scope":    ["years", "rothLadder", "taxes"]
}

→ 200 OK
{
  "answer": "Filling the 22% bracket with Roth conversions in 2027–2033 shifts $41.9M from TDA into Roth while the client is still under IRMAA tier 2. RMDs from 2033 onward drop from $8.5M/yr to $5.1M/yr, which keeps MAGI below the tier-1 threshold for 11 additional years and avoids ~$6.4M in Medicare IRMAA. The remaining delta is the tax-free compounding on the converted Roth balance over the survivor's lifetime.",
  "citations": [
    { "year": 2029, "field": "rothConversions", "value": 5800000 },
    { "year": 2034, "field": "rmdRequired",     "value": 5108000 },
    { "year": 2038, "field": "taxes.irmaaBracket", "value": 1 }
  ],
  "followUps": [
    "What if we cap conversions at the 24% bracket instead?",
    "How does this look under a 2008-style sequence-of-returns?"
  ]
}
// Answers cite exact year-records. No hallucinated numbers — the agent
// is grounded against the deterministic projection it's reasoning over.

03 — Why API-first

No UI. No seats. No lock-in.

Most planning vendors ship a desktop application with per-advisor pricing and an exported PDF. We ship the engine — you ship the product.

⇄

Deterministic by design

Same seed, same answer — every run. Required for compliance, archives, and reproducible plan audits.

Integrated AI agent

One API call answers any plain-English question about a specific case — and grounds every claim against the underlying projection.

{}

Embed anywhere

Single JSON request → full multi-decade plan. No CRM, no per-advisor seat fees, no plan-count licensing.

Every tax wrinkle

AGI, AMT, NIIT, IRMAA, taxable SS, qualified dividends, state tax, 59½ penalty — modeled, not approximated.

→

SSE for long runs

Stream per-year results back over text/event-stream for progress UIs and large-fan-out scenarios.

⊙

SOC 2 Type II

Deterministic outputs make every plan archivable. Audit-trail, replay, and rerun-hash baked into the response envelope.

04 — Contact

Get an API key.

Tell us what you're building and we'll send credentials, docs, and a sandbox household to start with.

Email: info@mavenfin.tech
Office: 155 N. Wacker Drive
Chicago, IL 60606
Status: status.mavenfin.tech

Maven is an API-first financial planning engine. We work directly with fintech teams, RIAs, custodians, and CPA-software vendors — no advisor seats, no per-plan licensing.

Financial planning,as an API.