Accounts
Account types, allocations, ownership, and creation.
list_account_types
Section titled “list_account_types”List all valid account types with short descriptions.
Parameters: None
Returns: account_types.
get_allowed_asset_classes_for_account
Section titled “get_allowed_asset_classes_for_account”Get the asset classes allowed for a specific account type.
| Parameter | Type | Default | Description |
|---|---|---|---|
account_type |
string | required | Account type (e.g., ‘taxable_brokerage’, ‘hsa’) |
Returns: account_type, allowed_asset_classes, is_cash_only, and supports_equities.
get_account_limits
Section titled “get_account_limits”Get the limits and restrictions for an account type, including its contribution limit.
| Parameter | Type | Default | Description |
|---|---|---|---|
account_type |
string | required | Account type |
birth_year |
int | null | Optional account owner’s birth year. Sets the applicable RMD start age, and the age for the contribution-limit catch-up when age is omitted. When omitted, a default RMD start age is returned. |
year |
int | null | Optional tax year for the contribution limit, 2024 or later; defaults to the current year. For a year past the published IRS table the contribution limit is indexed and flagged is_projected; 529 gift-tax figures are held flat at the latest published year. |
age |
int | null | Optional owner’s age attained by December 31 of the year, which sets the catch-up tier. Overrides birth_year for the catch-up. Omit both for the limit without catch-up. |
hsa_coverage |
string | null | HSA only: the HDHP coverage tier. Defaults to ‘family’. |
simple_small_employer |
bool | null | SIMPLE IRA only: true when the employer has 25 or fewer employees (or 26-100 and elects the higher contribution), which raises the limit. Defaults to whichever of the two limits has the higher total. |
Returns FDIC insurance, RMD requirements, purchase limits and early-withdrawal penalty age under limits. Under contribution_limit it returns the annual contribution limit for a 401(k), IRA, Roth IRA, HSA, SEP-IRA or SIMPLE IRA: the base limit, the catch-up tier the owner’s age falls in and its amount, the total, and is_projected when the year is past the published IRS table. It is null for a type with no contribution limit. For a 529 it returns plan_529_gift_tax instead: the per-donor annual gift-tax exclusion and the five-year superfunding election.
create_account
Section titled “create_account”Create a financial account with balance, ownership, and allocation.
| Parameter | Type | Default | Description |
|---|---|---|---|
account_type |
string | required | Account type |
balance_cents |
int | required | Current account balance in cents |
ownership_json |
object | required | Ownership structure as JSON. Must include: ownership_type (‘individual’, ‘joint’, or ‘beneficiary’), owner_ids (list of person IDs), and optionally beneficiary_id (required for beneficiary type). A ‘plan_529’ account must use ‘beneficiary’ ownership: ask the user who the 529 is for and name that student as beneficiary_id, adding them as a dependent first if needed. If there is no student yet, the owner may name themselves (beneficiary_id equal to their own owner id) and change it later, though a change may restart the 15-year clock for rolling the 529 into a Roth IRA; tell the user. Examples: {“ownership_type”: “individual”, “owner_ids”: [“person-123”]}; for a 529, {“ownership_type”: “beneficiary”, “owner_ids”: [“person-123”], “beneficiary_id”: “dependent-456”} |
allocation_json |
object | null | Optional asset allocation as JSON. Supports stocks_pct, bonds_pct, cash_pct, crypto_pct, real_estate_pct, and other_pct (all integers 0-100 that sum to 100); the non-standard fields default to 0 if omitted. Example: {“stocks_pct”: 60, “bonds_pct”: 30, “cash_pct”: 10}. If omitted, defaults to 100% cash for cash-only account types (cash accounts, mortgage) and 100% real estate for real estate accounts; it is required for every other type. |
tax_treatment |
string | null | Tax treatment for the account. Options: pre_tax, post_tax_deferred, taxable, or tax_advantaged |
name |
string | null | Human-readable account name |
institution |
string | null | Financial institution name |
account_number_last4 |
string | null | Last 4 digits of account number |
is_current_employer |
bool | null | For 401k accounts, whether this is current employer’s plan |
employer_match_json |
object | null | Employer matching configuration. Only valid on a current-employer 401k (account_type is traditional_401k/roth_401k and is_current_employer is true); rejected otherwise. Must include formula_type (‘basic_safe_harbor’, ‘enhanced_safe_harbor’, ‘tiered’, ‘non_elective’, or ‘discretionary’). ‘basic_safe_harbor’ uses its fixed statutory tiers. For ‘tiered’ and ‘enhanced_safe_harbor’, add tiers, e.g. [{“match_rate”: 0.5, “up_to_deferral_pct”: 6.0}]; for “non_elective”, set non_elective_pct. Optional: discretionary_pct, vesting_schedule, annual_match_cap_cents, is_qaca, true_up. Example: {“formula_type”: “basic_safe_harbor”}. |
mortgage_terms_json |
object | null | Loan terms for a ‘mortgage’ account (required for that type, ignored otherwise). Must include: original_principal_cents, interest_rate (annual decimal, e.g. 0.0675 for 6.75%), term_months, origination_date (ISO 8601, e.g. ‘2024-01-15’), and monthly_payment_cents (principal + interest only). Optionally is_fixed_rate (default true). Example: {“original_principal_cents”: 45000000, “interest_rate”: 0.0675, “term_months”: 360, “origination_date”: “2024-01-15”, “monthly_payment_cents”: 291500} |
property_details_json |
object | null | Property details for a ‘real_estate’ account (required for that type, ignored otherwise). Must include: property_type (‘primary_residence’, ‘investment_property’, ‘vacation_home’, or ‘rental_property’), purchase_price_cents, and purchase_date (ISO 8601). Optional: estimated_value_cents (defaults to purchase price), appreciation_rate (annual decimal, e.g. 0.03 for 3%; defaults to 3%), building_type, city, state, zip, linked_mortgage_account_id. Example: {“property_type”: “primary_residence”, “purchase_price_cents”: 50000000, “purchase_date”: “2020-06-01”} |
loan_terms_json |
object | null | Loan terms for a non-mortgage liability account — ‘credit_card’, ‘student_loan’, ‘auto_loan’, ‘personal_loan’, or ‘other_loan’ (required for those types, ignored otherwise). Must include: apr (annual decimal, e.g. 0.2499 for 24.99%) and minimum_payment_cents. Optionally term_months (set for an amortizing installment loan; omit for revolving debt like a credit card). Example: {“apr”: 0.2499, “minimum_payment_cents”: 7500} |
goal_id |
string | null | Optional Goal ID to earmark this account to. The goal’s funded amount then derives from this account’s balance. |
monthly_contribution_cents |
int | null | Optional explicit monthly contribution earmarked to this account, in cents. Set it when the honest per-account contribution is known (e.g. an IRA at its annual cap, a taxable account taking no new money) so a whole-plan projection (project_plan) honors it as a fixed monthly amount instead of deriving the account’s share of the household surplus by balance; the remaining surplus is split by balance across the accounts without a pin. Non-negative; omit to let the balance-weighted split apply. Inert on liability and real-estate accounts, which a projection does not project. A pin that annualizes above the account type’s contribution limit (401(k), IRA, HSA, SEP or SIMPLE IRA) is saved with a warning, and project_plan caps it at the limit. Mutually exclusive with contribution_schedule_json. |
plan_state |
string | null | 529 only: two-letter code of the state sponsoring the plan, which decides eligibility for an in-state-only state tax benefit. |
opened_date |
string | null | 529 only: ISO date (YYYY-MM-DD) the current beneficiary’s Roth-rollover clock started — when the account was opened, or the last change of beneficiary if later. |
plan_max_balance_cents |
int | null | 529 only: the plan’s aggregate balance limit per beneficiary, in cents, from the plan disclosure. Positive. |
contribution_basis_cents |
int | null | 529 only: the account’s remaining contribution basis in cents — contributions less basis already returned by earlier distributions — from the plan statement or plan provider. Omit when unknown; never estimate it. |
donor_count |
int | null | 529 only: how many people contribute to the account (e.g. parents plus grandparents). Omit to count the account owners, plus the spouse on a joint household. At least 1. |
contribution_schedule_json |
object | null | Optional time-varying monthly contribution pin, as JSON — the start/stop/grow counterpart to monthly_contribution_cents (mutually exclusive with it). Use it for an earmark like “max the IRA at $583/mo until 2035, then stop”. Fields: monthly_amount_cents (required, non-negative base amount); start_date and end_date (optional ISO ‘YYYY-MM-DD’ bounds — before start_date and after end_date the account contributes nothing; end_date must follow start_date); annual_growth_rate (optional annual escalation, 0-1, e.g. 0.03 for 3%/yr, compounded from the projection start; on a real_terms schedule this is growth above inflation); real_terms (optional bool — when true the amount is in today’s dollars and a projection grosses it up by inflation so it holds purchasing power). A bare schedule ({“monthly_amount_cents”: N}) is identical to the scalar pin of the same amount. Example: {“monthly_amount_cents”: 58333, “end_date”: “2035-12-31”, “annual_growth_rate”: 0.03} |
Returns the created account as JSON including auto-generated ID, plus warnings when its contribution pin (monthly_contribution_cents, or a contribution_schedule’s base monthly_amount_cents) exceeds this year’s contribution limit for the account type (checked without an age catch-up, since no household is given here).