# 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

GET /api/wealth/bank-check?bank={bank_name_or_cert}
- The deterministic COMPONENT behind bank-health, at the component price: the exact same code-computed FDIC Call Report block (PCA capital category per 12 CFR 324.403, ROA/ROE/NIM, noncurrent-loan and reserve-coverage ratios, CRE asset-quality ratios, YoY deposit growth, uninsured-deposit share, 8-quarter trend) with NO plain-language synthesis layer. Closed/failed institutions are included with their charter-end date — "did this bank fail" is a first-class answer, not an error. No LLM, no key, public domain.
- Required: bank (bank name or FDIC certificate/CERT number, e.g. "628")
- Optional: state (2-letter code, disambiguates a common bank name)
- Returns a 404 with suggested matches if no institution is found (no charge)
- Price: $0.02

GET /api/wealth/unclaimed?states={CA,TX,NY}&countries={CH,CA}&situations={former_pension,...}
- Find money you are owed but never claimed. DETERMINISTIC router (no LLM) across US state unclaimed-property programs (NAUPA/MissingMoney), federal sources matched to your situation (PBGC pensions, FDIC/NCUA failed institutions, HUD/FHA MIP refunds), and international registers (Bank of Canada, UK My Lost Account, Switzerland NARILO, Australia SRO/ASIC). Returns the exact official FREE portals to search IN ORDER, the claim-documentation package (ID, SSN, address-link proof), federal sources matched to life events, and an honest coverage block distinguishing openly-searchable sources (NCUA, Swiss NARILO, AU-VIC) from route-only ones. It is a router, NOT a scraper — it never queries automation-restricted or bot-defended sites; the consumer's own search on every official portal is free. Discontinued sources (Treasury Hunt, ended 2025-09-30) are honestly flagged, not linked to dead pages.
- Optional (provide at least one): states (comma-separated US codes), countries (CA|GB|CH|AU|AU-VIC|AU-NSW), situations (former_pension|failed_bank|failed_credit_union|fha_mortgage|savings_bonds|deceased_relative|old_employer|moved_states|former_business), name (personalizes instructions only, never stored)
- Returns: search_plan (ordered), federal_matches, claim_package, coverage (openly_searchable / route_only / documented_no / problems)
- Price: $0.50

### GET /api/wealth/card-benefit — Credit-Card Benefit Coverage Check ($0.05)
NEW: your card probably covers that broken laptop / stolen phone / delayed trip — checked against ISSUER-verified published benefit guides (Chase Sapphire, Amex Gold/Platinum, Capital One, Citi, HSBC World Elite, Amex UK, RBC Canada — plus authoritative negative facts: Discover carries nothing; Capital One World MC gutted 2025-01-01). Extended warranty, purchase protection, trip delay, cell phone, return protection. Caps, deductibles, eligibility windows, recoverable estimate, and the 20-90-day notify deadlines that kill late claims — computed, not guessed. Same-tier caps vary 20x by issuer, so we never use network defaults. No LLM.
Params: issuer + card + benefit (required); purchase_date, incident_date, item_price, warranty_years, delay_hours, phone_paid_on_card
Example: /api/wealth/card-benefit?issuer=chase&card=sapphire-reserve&benefit=purchase_protection&purchase_date=2026-06-10&incident_date=2026-07-01&item_price=2000
Example: /api/wealth/card-benefit?issuer=amex&card=platinum&benefit=cell_phone&incident_date=2026-07-01&item_price=1000&phone_paid_on_card=true

### GET /api/wealth/card-benefit-preview — Card-Benefit Coverage PREVIEW ($0.25)
Agent-tier preview for buyers whose per-call spend cap sits under the $2.00 pack: scans one card across all 5 protections (extended warranty, purchase protection, trip delay, cell phone, return protection) from the same issuer-verified registry — which likely apply, which need more info, which are ineligible right now, which the card doesn't carry at all. No LLM.
Params: issuer + card (required); purchase_date, incident_date, item_price, warranty_years, delay_hours, phone_paid_on_card (optional, sharpen the scan)
Example: /api/wealth/card-benefit-preview?issuer=chase&card=sapphire-reserve&purchase_date=2026-06-10&item_price=2000

### GET /api/wealth/card-benefit-pack — Card-Benefit Claim Pack ($2.00)
The coverage check PLUS the complete filing kit: administrator-specific steps (Asurion/Sedgwick/Assurant/Amex in-house), citation-locked cover note, evidence checklist, denial counters, deadline calendar. Honest-no: no pack sold on expired windows or uncovered cards.
Params: same + item_description, cardholder_name, lang

## 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

## Card Benefits guides

Free, answer-first GEO pages generated directly from the same issuer-verified registry the paid card-benefit endpoints use — no page states a fact the registry doesn't contain. Start at https://wealthpulse.theaslangroupllc.com/cards/

- https://wealthpulse.theaslangroupllc.com/cards/purchase-protection-by-card.html — purchase protection caps compared across cards ($500–$50,000)
- https://wealthpulse.theaslangroupllc.com/cards/extended-warranty-by-card.html — extended warranty terms compared (+12 to +24 months)
- https://wealthpulse.theaslangroupllc.com/cards/trip-delay-by-card.html — trip delay triggers and caps compared (6h vs 12h)
- https://wealthpulse.theaslangroupllc.com/cards/cell-phone-protection-by-card.html — cell phone protection compared, and the condition that voids every claim
- https://wealthpulse.theaslangroupllc.com/cards/return-protection-by-card.html — return protection compared (nearly extinct on US cards)
- https://wealthpulse.theaslangroupllc.com/cards/amex-platinum-card-benefits.html — Amex Platinum full benefit profile
- https://wealthpulse.theaslangroupllc.com/cards/same-tier-20x-variance.html — why the same issuer's cards can carry 20x different caps
- https://wealthpulse.theaslangroupllc.com/cards/amex-uk-rbc-canada-card-benefits.html — global card benefits (UK, Canada)
- https://wealthpulse.theaslangroupllc.com/cards/discover-no-benefits.html — honest answer: Discover carries none
- https://wealthpulse.theaslangroupllc.com/cards/capital-one-world-mastercard-gutted.html — honest answer: Capital One removed all benefits 2025-01-01

## Disclaimer

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