Quickstart
Four steps from zero to a complete plan: authenticate, list households, fetch a projection, and run a Monte Carlo. Each step shows cURL, JavaScript, and Python with a copy button and inline notes.
1. Authenticate
Mint a bearer token via the OAuth2 password grant. The token is good for ~12 hours
(expires_in: 43199); use the refresh-token to mint a new one without re-prompting the user.
Default sandbox creds are pre-filled.
curl -u app1:4d1b3c8e-07a0-457d-8f70-09b354e8e5a9 \
-d "grant_type=password&username=marbach&password=r3t1r3&scope=read+write" \
https://legacy.mavenfin.tech/isauthorize19/oauth/token
# → { "access_token": "eyJhbGc…", "expires_in": 43199, "refresh_token": "…", "scope": "read write" }
const creds = btoa('app1:4d1b3c8e-07a0-457d-8f70-09b354e8e5a9');
const res = await fetch('https://legacy.mavenfin.tech/isauthorize19/oauth/token', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + creds,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'password',
username: 'marbach',
password: 'r3t1r3',
scope: 'read write',
}),
});
const { access_token } = await res.json();
import requests
r = requests.post(
'https://legacy.mavenfin.tech/isauthorize19/oauth/token',
auth=('app1', '4d1b3c8e-07a0-457d-8f70-09b354e8e5a9'),
data={
'grant_type': 'password',
'username': 'marbach',
'password': 'r3t1r3',
'scope': 'read write',
},
timeout=10,
)
r.raise_for_status()
token = r.json()['access_token']
2. List households
Every plan lives inside a household. Paginate with page (default 0) and size
(default 25). Sandbox seeds approximately 50 households across a mix of single, married,
early-retirement, and high-net-worth profiles.
curl -H "Authorization: Bearer $BEARER" \
"https://legacy.mavenfin.tech/isrestapi19/api/v1/households?page=0&size=25"
const res = await fetch(
'https://legacy.mavenfin.tech/isrestapi19/api/v1/households?page=0&size=25',
{ headers: { Authorization: 'Bearer ' + token } },
);
const households = await res.json();
r = requests.get(
'https://legacy.mavenfin.tech/isrestapi19/api/v1/households',
params={'page': 0, 'size': 25},
headers={'Authorization': f'Bearer {token}'},
timeout=30,
)
households = r.json()
3. Run a projection
Each household ships with one or more plans (scenarios). The projection endpoint runs the full deterministic forward simulation: monthly cash-flow, account balances, tax events, withdrawals, RMDs, Social Security, pensions, capital-gains realization, and net portfolio value through end of plan.
For UI charts, request granularity=yearly (rows ≈ 30 years). For audit trails or per-month
debugging, request monthly (rows ≈ 360).
curl -H "Authorization: Bearer $BEARER" \
"https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/projection?granularity=yearly"
const res = await fetch(
'https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/projection?granularity=yearly',
{ headers: { Authorization: 'Bearer ' + token } },
);
const { rows } = await res.json();
console.log(`${rows.length} years; terminal net portfolio:`, rows.at(-1).netPortfolio);
r = requests.get(
f'https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/projection',
params={'granularity': 'yearly'},
headers={'Authorization': f'Bearer {token}'},
timeout=60,
)
rows = r.json()['rows']
print(f'{len(rows)} years; terminal net: {rows[-1]["netPortfolio"]:,.0f}')
4. Monte Carlo
The deterministic projection answers what happens under the assumed return curve. Monte Carlo
re-rolls returns to answer how likely is success across thousands of paths. Pass a
seed for reproducible results; pass equity/bond mean & vol to override the defaults.
curl -X POST \
-H "Authorization: Bearer $BEARER" \
-H "Content-Type: application/json" \
-d '{"runs":1000,"seed":42,"equityReturn":0.07,"equityVol":0.18,"bondReturn":0.03,"bondVol":0.05}' \
https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/montecarlo
const res = await fetch(
'https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/montecarlo',
{
method: 'POST',
headers: {
'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json',
},
body: JSON.stringify({
runs: 1000, seed: 42,
equityReturn: 0.07, equityVol: 0.18,
bondReturn: 0.03, bondVol: 0.05,
}),
},
);
const mc = await res.json();
console.log(`success rate: ${(mc.successRate * 100).toFixed(1)}%`);
r = requests.post(
'https://legacy.mavenfin.tech/isrestapi19/api/v1/households/1/plans/1/montecarlo',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
},
json={
'runs': 1000, 'seed': 42,
'equityReturn': 0.07, 'equityVol': 0.18,
'bondReturn': 0.03, 'bondVol': 0.05,
},
timeout=120,
)
mc = r.json()
print(f'success rate: {mc["successRate"]*100:.1f}% p50: {mc["p50"]:,.0f}')