# WealthPulse

> Personal finance intelligence API with global coverage. 14 endpoints covering financial health snapshots, retirement projections, debt payoff, credit cards, mortgage affordability, DIY debt negotiation, Social Security claiming strategy, year-end tax optimization, Roth vs Traditional decision, emergency fund sizing, inherited IRA rules, Trump Account (IRC §530A) eligibility/strategy/rules, FDIC Call Report bank-safety checks, and financial advisor intelligence — via x402 micropayments on Base mainnet.

Grounded in live FRED rate data (US) and official FDIC BankFind Suite Call Report data. Global coverage for UK ISA/SIPP, Canada RRSP/TFSA, Australia Super, India PPF/NPS. Handles equity compensation (RSU, QSBO, 83b, solo 401k) and international retirement accounts.

## Endpoints

GET /api/wealth/snapshot?age={age}&income={annual_income}
- Financial health score (fair/okay/good/strong), strengths, concerns, key ratios (savings rate, DTI, emergency fund months), and highest-leverage action plan ranked by effort vs impact
- Optional: savings, debt, expenses, lang
- Price: $0.15

GET /api/wealth/retire?age={age}&income={annual_income}
- Retirement readiness projection, nest egg estimate, 4% rule income, gap analysis, on-track assessment, 2026 contribution limits, Roth vs Traditional strategy, ranked action plan
- Supports: 401k/IRA/Roth (US), ISA/SIPP (UK), RRSP/TFSA (Canada), Super (Australia), PPF/NPS (India)
- Optional: savings, retire_at (default 65), target_income, lang
- Price: $0.15

GET /api/wealth/debt?debts={name:balance:rate,...}
- Avalanche vs snowball comparison (total interest, months to payoff), recommended strategy, consolidation check at current FRED rates, extra payment impact
- Format: debts=credit-card:8500:24,car-loan:12000:6.5
- Optional: extra (extra monthly payment), lang
- Price: $0.10

GET /api/wealth/cards?spend_profile={profile}
- Top 3-5 credit cards ranked by net annual value (rewards minus fees), current signup bonuses, multi-card pairing strategy, live APR context from FRED
- Optional: monthly (default 3000), credit_score, lang
- Price: $0.10

GET /api/wealth/mortgage?income={annual}&down={down_payment}
- Max home price (28% and 36% DTI), monthly payment at current FRED rates, buy vs. wait recommendation, cost-of-waiting analysis, first-time buyer programs
- Optional: location (default US), debt, lang
- Price: $0.10

GET /api/wealth/debt-negotiate?creditor={creditor}
- Settlement range (realistic %), step-by-step negotiation scripts, FDCPA rights, statute of limitations warning, what to get in writing, what to do if sued
- Optional: balance, type (credit_card|medical|personal|auto|student), state, lang
- Price: $0.15

GET /api/wealth/advisor?action={action}
- action=find: fee-only fiduciary advisor search — NAPFA/XYPN/CFP Board directories, fee expectations, red flags, interview questions. Required: specialty. Optional: location, situation
- action=compare: side-by-side comparison with decisive recommendation, comparison table, deciding factors. Required: advisors
- action=vet: BrokerCheck + SEC IAPD vetting protocol, ADV Part 2 guide, fiduciary test, 8-10 interview questions. Required: name. Optional: firm
- Price: find/compare $0.10 | vet $0.15

GET /api/wealth/ssa?birth_year={year}
- Social Security claiming strategy — optimal age analysis, break-even math (62 vs FRA vs 70), spousal/survivor benefits, taxation threshold, and clear recommendation
- Optional: income, marital_status (single|married|divorced|widowed), health (good|fair|poor), lang
- Price: $0.15

GET /api/wealth/tax?income={annual}
- Year-end tax optimization — Roth conversion opportunities, tax-loss harvesting, contribution deadlines (Dec 31 vs April 15), charitable strategies, ranked moves with savings estimates
- Optional: filing_status, situation (RSU_vesting,home_sale,bonus,capital_gains), state, lang
- Price: $0.15

GET /api/wealth/roth?income={annual}&age={age}
- Roth vs Traditional IRA/401k decision — income limit check, tax math, backdoor Roth eligibility (with pro-rata warning), mega backdoor Roth eligibility, 2026 contribution limits
- Optional: filing_status, employer_match, state, lang
- Price: $0.10

GET /api/wealth/emergency?income={annual}
- Emergency fund sizing — recommended months (based on job stability and dependents), dollar target, monthly savings plan, best current HYSA rates and account options
- Optional: expenses, job_type (stable|variable|entrepreneur), dependents, current_fund, lang
- Price: $0.10

GET /api/wealth/inheritance?relationship={type}
- Inherited IRA rules under SECURE Act 2.0 — 10-year rule, RMD requirements, spousal rollover options, step-up in basis for taxable inherited assets, distribution strategy to minimize taxes
- Valid relationships: spouse|non-spouse|minor-child|disabled|trust|charity
- Optional: account_type (traditional|roth), balance, your_age, original_owner_age, lang
- Price: $0.10

GET /api/wealth/trump-account?action={action}
- New IRC §530A child savings account (Trump Account), launching 2026-07-04. Verified against 26 USC §530A, §6434 (pilot), IRS Notice 2025-68, and Rev. Proc. 2026-25 — proposed regulations are NOT final (hearing scheduled 2026-07-16), and this data corrects several commonly-misreported facts (e.g. no citizenship requirement for the account itself; employer $2,500 contributions count INSIDE the $5,000/yr cap, not on top; growth is tax-deferred not tax-free, earnings taxed as ordinary income; the account IS a §408(a) traditional IRA from inception, it does not "convert" at 18; no education/hardship withdrawal carve-outs before age 18; the "≥90% US-weighted" investment rule is a proposed safe harbor, not statute).
- action=eligibility: deterministic account-eligibility AND $1,000 pilot-eligibility verdict (computed in code, not by the model), citing sources, with exact Form 4547 enrollment paths and a scam warning. Params: birth_year (or birth_date) required; has_ssn, ssn_work_valid, us_citizen, prior_election optional (each yes/no — omit for "unknown" and the verdict will say what's missing).
- action=strategy: Trump Account vs 529 vs Roth IRA for kids vs UTMA/UGMA comparison and a decisive allocation recommendation. Params: goal (education|general|retirement, default general), child_age, employer_program (yes/no), budget_yearly — all optional.
- action=rules: current verified rules reference, flags which points are commonly misreported online, always notes proposed-regs-pending status. Params: topic (contributions|investments|distributions|tax|enrollment) optional — omit for full coverage.
- Optional on all actions: lang
- Price: $0.15
- Free companion FAQ (no payment): https://wealthpulse.theaslangroupllc.com/trump-accounts

GET /api/wealth/bank-health?bank={bank_name_or_cert}
- Is my bank safe? Bank-health check computed directly from official FDIC quarterly Call Report data (banks.data.fdic.gov) — no LLM math. Capital adequacy: Tier 1 leverage ratio, CET1 ratio, Tier 1 and Total risk-based capital ratios, checked against the FDIC's own Prompt Corrective Action "well capitalized"/"adequately capitalized" thresholds (12 CFR 324.403). Earnings: ROA, ROE, net interest margin (FDIC-reported). Asset quality: noncurrent-loans-to-gross-loans ratio and a loan-loss reserve coverage ratio computed from raw allowance and noncurrent-loan dollar figures. Commercial real estate: noncurrent-loan asset-quality ratios by CRE category (construction, multifamily, nonfarm-nonresidential) — explicitly NOT a CRE concentration ratio, which this public dataset doesn't publish. Liquidity: year-over-year deposit growth (only computed when a true year-ago quarter is available — never diffed against a mismatched period) and the FDIC's own estimated uninsured-deposit share. Includes an 8-quarter trend and the exact FDIC report date (data_as_of).
- Required: bank (bank name, e.g. "Wells Fargo Bank, National Association", or an FDIC certificate/CERT number, e.g. "3511")
- Optional: state (2-letter code, disambiguates a common bank name like "First National Bank"), lang
- Returns a 404 with suggested matches if no institution is found (no charge); if the matched institution is inactive/closed/merged, the response leads with that fact rather than a stale safety read
- Price: $0.25

## Payment

All endpoints use x402 protocol. No payment header → HTTP 402 with PAYMENT-REQUIRED header (0.10–0.15 USDC on Base mainnet). Send valid PAYMENT-SIGNATURE → 200 with structured JSON.

## Data Sources

- FRED (Federal Reserve Economic Data) — mortgage rates, savings rates, credit card APR, inflation, Fed funds rate
- FDIC BankFind Suite (banks.data.fdic.gov) — official quarterly Call Report institution and financial data, no API key required
- Tavily — real-time credit card offers, HYSA rates, Social Security rule updates, tax strategy research
- Claude Sonnet — synthesis and personalized analysis

## Affiliate Disclosure

Responses may include Amazon book links (tag: pulsenetwork7-20) and LendingTree referral links. These are affiliate links that support the service.

## Agent Workflow Examples

- Full financial review: /snapshot → /retire → /emergency → /roth
- Retirement planning: /retire → /ssa (timing) → /tax (Roth conversion window) → /roth
- Debt resolution: /debt → /debt-negotiate → /snapshot (check progress)
- Advisor hire: /advisor?action=find → /advisor?action=vet → /advisor?action=compare
- Inheritance planning: /inheritance → /tax (distribution tax impact)
- New child savings: /trump-account?action=eligibility → /trump-account?action=strategy → /roth (once child has earned income)
- Where to bank: /bank-health?bank={bank} → /emergency (where to park the emergency fund) → /snapshot

## Disclaimer

For informational purposes only. Not financial, tax, or legal advice. Projections are estimates. Consult a licensed professional for personalized guidance.