Skip to content

Goals

Create, track, and project financial goals.

create_goal

Create a financial goal with specified targets.

Parameter Type Default Description
name string required Goal name (1-200 characters)
goal_type string required Kind of financial goal being created.
importance float required Success probability target (0.01-0.99, e.g., 0.90 = 90% confidence)
target_amount_cents int null Target amount in cents (for goals with a fixed savings target)
target_date string null Target date in YYYY-MM-DD format (optional)
target_date_flexibility string null How firm the target date is.
contribution_amount_cents int null Fixed monthly contribution in cents
contribution_percentage float null Contribution as % of income (e.g., 0.15 = 15%)
months_expenses int null Number of months of expenses to save (for emergency_fund goals)
status string "active" Lifecycle status of the goal.
tax_advantaged bool false Prefer tax-advantaged accounts for this goal
notes string null Additional notes about the goal
description string null Optional longer description of the goal (max 1000 chars)
target_price_level object null Price level of target_amount_cents. Omit for today's dollars (real purchasing power at creation). For future nominal dollars: {"adjustment": "nominal"}. For a specific reference purchasing power: {"adjustment": "real", "reference_year": 2026, "reference_month": 1}.
payout_schedule list null Scheduled payouts for multi-year goals (e.g. education), each {"payout_date": "YYYY-MM-DD", "amount_cents": int}.
precondition_goal_id string null ID of a goal that must reach precondition_threshold before this goal is funded
precondition_threshold float null Fraction (0.0-1.0) of the precondition goal that must be met first

Returns the created goal as JSON including auto-generated ID and validation results.

get_goal_progress

Calculate current progress toward a goal.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); "emergency_fund" goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal's funded balance (the linked account's balance) — the goal's own current_balance_cents is often 0 because funding is account-derived.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the goal's funded balance; otherwise goal_json.current_balance_cents is used.

Returns progress percentage, remaining amount, and completion status. Pass state_json to derive the funded balance from accounts linked to the goal's id; otherwise the goal_json current_balance_cents value is used.

project_goal_progress

Project goal progress forward with compound growth.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); "emergency_fund" goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal's funded balance (the linked account's balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the projection's starting funded balance; otherwise goal_json.current_balance_cents is used.
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
annual_volatility float 0.0 Annual return volatility (standard deviation) as a decimal (e.g., 0.15 = 15%). When > 0, the projection spreads into a percentile band (p10/p25/p50/p75/p90) so return uncertainty is visible: p10 < p50 < p90, and the median (p50) reflects volatility drag (it sits below the zero-volatility expected path). Leave 0 for a single deterministic figure.
months_ahead int null Number of months to project forward. If omitted, the projection runs to the goal's own target_date (or today if the goal has no target_date), so the result answers the question the goal defines rather than an arbitrary horizon. Pass a value only to override with a fixed horizon.
monthly_income_cents int 0 Caller's monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise. Leave 0 if the goal has no income-percentage contribution.
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to the projection date's nominal value before progress is computed.

Returns: goal_id, goal_name, balance_source, current_balance_cents, current_balance_dollars, projection_date, months_ahead, projection_basis, annual_return_rate, and annual_volatility, and more.

project_goal_series

Project a goal's balance and progress as a year-by-year (or N-month) series in one call.

Parameter Type Default Description
goal_json object required Goal as a JSON dict. Required keys: name, goal_type, importance (0.01-0.99); "emergency_fund" goals also require months_expenses. current_balance_cents is optional (defaults to 0) but should be set to the goal's funded balance (the linked account's balance). With state_json, the funded balance is resolved from accounts linked to goal_json.id; without it, passing the raw goal (often 0) projects from $0.
state_json object null Optional full user state JSON. When its accounts include one or more accounts whose goal_id matches goal_json.id, their integer balance_cents values are summed and used as the series' starting funded balance; otherwise goal_json.current_balance_cents is used.
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
annual_volatility float 0.0 Annual return volatility (standard deviation) as a decimal. When > 0, each point spreads into a percentile band (p10/p25/p50/p75/p90); leave 0 for a single deterministic path per point.
months_ahead int null Horizon to project through. If omitted, runs to the goal's own target_date (or today if it has none). The series is sampled from today to this horizon.
step_months int 12 Sampling cadence in months (default 12 = annual points). Use 1 for a monthly series. Today (month 0) and the exact horizon are always included.
monthly_income_cents int 0 Caller's monthly income in cents. Only used for goals funded by contribution_percentage (PERCENTAGE_INCOME); ignored otherwise.
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, a real-terms target is inflated to each point's nominal value before progress is computed.

Returns: goal_id, goal_name, balance_source, annual_return_rate, annual_volatility, step_months, point_count, target_amount_cents, target_amount_dollars, and series, and more.

required_monthly_cashflow

Calculate the monthly contribution needed to reach a goal.

Parameter Type Default Description
target_amount_cents int required Target goal amount in cents
time_horizon_months int required Number of months until target date
initial_balance_cents int 0 Current savings toward goal in cents
annual_return_rate float 0.07 Expected annual return rate (e.g., 0.07 = 7%)
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, the target is assumed to be in today's dollars and is inflated to the target date's nominal value before solving.

Returns: target_amount_cents, target_amount_dollars, initial_balance_cents, initial_balance_dollars, time_horizon_months, annual_return_rate, inflation, inflation_adjusted_target_cents, inflation_adjusted_target_dollars, and cashflow_cents, and more.