Skip to main content

​
Overview

All API models use Pydantic for validation and serialization. Models support both snake_case (Python) and camelCase (JavaScript) field names.

​
Request Models

​
SimulationRequest

Top-level request object for Monte Carlo simulations.
​
financial_profile
FinancialProfile
required
User’s current financial state (assets, debts, spending)
​
user_inputs
UserInputs
required
User-provided information (income, age, risk tolerance)
​
goal
Goal
required
Financial goal to simulate (target amount, timeline)
​
simulation_params
SimulationParams
Optional simulation parameters. Defaults to medium risk profile if not provided.

​
FinancialProfile

Current financial snapshot.
​
liquid_assets
float
required
Total liquid assets (checking, savings, brokerage accounts)
​
credit_debt
float
default:"0.0"
Total credit card debt
​
loan_debt
float
default:"0.0"
Total loan balances (student, auto, mortgage, personal)
​
monthly_loan_payments
float
default:"0.0"
Total monthly loan payments across all loans
​
monthly_spending
float
required
Average monthly spending
​
spending_by_category
dict[str, float]
default:"{}"
Spending breakdown by category (housing, food, transportation, etc.)
​
spending_volatility
float
default:"0.15"
Spending variance (0.05-0.40). Higher values = more unpredictable expenses.

​
UserInputs

​
monthly_income
float
required
Monthly gross income
​
age
int
required
Current age
​
risk_tolerance
Literal['low', 'medium', 'high']
required
Investment risk tolerance. Affects expected returns:
  • low: 4% return, 8% volatility (conservative)
  • medium: 7% return, 15% volatility (balanced)
  • high: 10% return, 20% volatility (aggressive)

​
Goal

Financial goal definition.
​
target_amount
float
required
Target dollar amount. Must be positive.
​
timeline_months
int
required
Timeline in months. Must be positive.
​
goal_type
str
default:"custom"
Goal category (e.g., “savings”, “retirement”, “house”, “emergency_fund”)
​
goal_text
str
Original goal text if parsed from natural language
​
confidence
float
default:"1.0"
Parser confidence score (0-1) for AI-parsed goals

​
SimulationParams

Simulation configuration and assumptions.
​
n_simulations
int
default:"100000"
Number of Monte Carlo simulations to run
​
income_volatility
float
default:"0.05"
Monthly income variance (standard deviation)
​
expense_volatility
float
default:"0.15"
Monthly expense variance
​
emergency_probability
float
default:"0.08"
Monthly probability of emergency expense (0.08 = 8%)
​
emergency_min
float
default:"500"
Minimum emergency expense amount
​
emergency_max
float
default:"3000"
Maximum emergency expense amount
​
annual_return_mean
float
default:"0.07"
Expected annual investment return (7%)
​
annual_return_std
float
default:"0.15"
Investment return volatility (15%)
​
inflation_rate
float
default:"0.025"
Annual inflation rate (2.5%)
​
inflation_volatility
float
default:"0.01"
Inflation variance (± 1%)
​
annual_raise_mean
float
default:"0.03"
Average annual salary raise (3%)
​
annual_raise_volatility
float
default:"0.015"
Raise variance
​
promotion_probability
float
default:"0.15"
Semi-annual promotion probability (15% every 6 months)
​
promotion_raise_mean
float
default:"0.08"
Average promotion raise (8%)
​
promotion_raise_volatility
float
default:"0.03"
Promotion raise variance
​
credit_cards
List[CreditCardParams]
default:"[]"
Credit card accounts for account-aware simulation
​
loans
List[LoanParams]
default:"[]"
Loan accounts for account-aware simulation
​
use_account_aware_simulation
bool
default:"false"
Enable per-account interest and payment modeling

​
CreditCardParams

Credit card configuration for account-aware mode.
​
id
str
required
Unique card identifier
​
balance
float
required
Current balance
​
apr
float
required
Annual percentage rate (e.g., 18.99 for 18.99%)
​
minimum_payment
float
required
Minimum monthly payment

​
LoanParams

Loan configuration for account-aware mode.
​
id
str
required
Unique loan identifier
​
balance
float
required
Current principal balance
​
interest_rate
float
required
Annual interest rate (e.g., 4.5 for 4.5%)
​
monthly_payment
float
required
Fixed monthly payment amount

​
Response Models

​
SimulationResults

​
success_probability
float
Probability of achieving the goal (0.0 to 1.0)
​
median_outcome
float
Median final balance (50th percentile)
​
percentiles
Percentiles
Distribution percentiles
​
mean
float
Mean final balance
​
std
float
Standard deviation
​
worst_case
float
Minimum outcome across all simulations
​
best_case
float
Maximum outcome across all simulations
​
simulations_run
int
Total simulations executed
​
workers_used
int
Parallel workers used
​
assumptions
Assumptions
Simulation assumptions for transparency

​
Percentiles

​
p10
float
10th percentile outcome
​
p25
float
25th percentile outcome
​
p50
float
50th percentile (median) outcome
​
p75
float
75th percentile outcome
​
p90
float
90th percentile outcome

​
Assumptions

Simulation assumptions returned for transparency.
​
annual_return_mean
float
Expected annual return used
​
annual_return_std
float
Return volatility used
​
inflation_rate
float
Inflation rate assumption
​
inflation_volatility
float
Inflation variance
​
annual_raise_mean
float
Average annual raise
​
annual_raise_frequency
str
Raise frequency description (e.g., “Annual (every 12 months)”)
​
promotion_probability_semi_annual
float
Semi-annual promotion probability
​
promotion_raise_mean
float
Average promotion raise
​
emergency_probability_monthly
float
Monthly emergency probability
​
emergency_amount_range
str
Emergency expense range (e.g., “500−500 - 3,000”)
​
income_volatility
float
Income variance used
​
expense_volatility
float
Expense variance used

​
Helper Methods

​
SimulationParams.from_risk_tolerance()

Create parameters adjusted for risk tolerance. 
from models import SimulationParams

params = SimulationParams.from_risk_tolerance("high")
print(params.annual_return_mean)  # 0.10 (10%)
print(params.annual_return_std)   # 0.20 (20%)

​
SimulationParams.from_financial_profile()

Generate parameters dynamically from enhanced account data. 
from models import SimulationParams, EnhancedFinancialProfile

# Enhanced profile from Plaid
profile = EnhancedFinancialProfile(
    depository=[...],
    credit=[...],
    loans=[...],
    investments=[...],
    income=IncomeProfile(monthly_amount=6000, stability_score=0.9),
    spending=SpendingProfile(monthly_amount=3500, volatility=0.12)
)

params = SimulationParams.from_financial_profile(profile, risk_tolerance="medium")
# Automatically extracts:
# - Investment returns from actual portfolio allocation
# - Income volatility from stability score
# - Expense volatility from spending patterns
# - Credit card APRs and minimum payments
# - Loan balances and payment schedules

​
Example Request

from models import (
    SimulationRequest,
    FinancialProfile,
    UserInputs,
    Goal,
    SimulationParams,
    CreditCardParams
)

request = SimulationRequest(
    financial_profile=FinancialProfile(
        liquid_assets=15000,
        credit_debt=4500,
        loan_debt=22000,
        monthly_loan_payments=450,
        monthly_spending=3200,
        spending_volatility=0.18
    ),
    user_inputs=UserInputs(
        monthly_income=5500,
        age=26,
        risk_tolerance="medium"
    ),
    goal=Goal(
        target_amount=30000,
        timeline_months=24,
        goal_type="emergency_fund"
    ),
    simulation_params=SimulationParams(
        n_simulations=100000,
        use_account_aware_simulation=True,
        credit_cards=[
            CreditCardParams(
                id="discover",
                balance=2500,
                apr=19.99,
                minimum_payment=75
            ),
            CreditCardParams(
                id="chase",
                balance=2000,
                apr=22.49,
                minimum_payment=60
            )
        ]
    )
)

Build docs developers (and LLMs) love

Get started for freeTalk to us