# WealthPulse

> Personal finance intelligence API with global coverage. 12 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, and financial advisor intelligence — via x402 micropayments on Base mainnet.

Grounded in live FRED rate data (US). 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

## 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
- 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 audit: /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)

## Disclaimer

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