{
  "openapi": "3.1.0",
  "info": {
    "title": "WealthPulse API",
    "description": "Personal finance intelligence API. 14 endpoints grounded in live FRED rate data and official FDIC Call Report data — financial health, retirement, debt, credit cards, mortgage, Social Security, tax optimization, Roth vs Traditional, emergency fund, inherited IRA, debt negotiation, Trump Account (IRC §530A) eligibility/strategy/rules, bank-safety/FDIC Call Report checks, and financial advisor intelligence. All endpoints require x402 payment (USDC on Base mainnet).",
    "version": "2.3.0",
    "contact": {
      "name": "The Aslan Group LLC",
      "url": "https://pulsenetwork.theaslangroupllc.com",
      "email": "info@theaslangroupllc.com"
    },
    "x-guidance": "# WealthPulse API (x402 pay-per-call)\n\nPersonal finance intelligence API. 14 endpoints: 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 (find, vet, compare). Global coverage — US, UK, Canada, Australi\n\nBase URL: https://wealthpulse.theaslangroupllc.com\n\n## Payment\nAll paid endpoints use the x402 protocol (HTTP 402): USDC on Base mainnet (eip155:8453). No API keys, no accounts, no subscriptions — pay per call.\n\n## Agent workflow\n1. Request the endpoint. Unpaid requests receive a 402 challenge with exact price and pay-to details (the challenge is returned before request validation).\n2. Settle with any x402 client (agentcash fetch, x402-fetch, x402-axios) and retry with the X-PAYMENT header.\n3. Responses are JSON. Prices below are fixed per call.\n\n## Paid endpoints\n- GET /api/wealth/snapshot — $0.15 — Financial health snapshot — health score, strengths, concerns, key ratios (savings rate, DTI, emergency fund months), and highest-leverage action plan ranked by\n- GET /api/wealth/retire — $0.15 — Retirement readiness projection — nest egg estimate, gap analysis, on-track assessment, 2026 contribution limits, global account support (401k/IRA, ISA/SIPP, RR\n- GET /api/wealth/debt — $0.1 — Debt payoff strategy — avalanche vs snowball with total interest cost, months to payoff, consolidation check at current FRED rates, extra payment impact.\n- GET /api/wealth/cards — $0.1 — Credit card optimization — top cards for any spend profile ranked by net annual value, current signup bonuses, pairing strategy.\n- GET /api/wealth/mortgage — $0.1 — Mortgage affordability — max home price at current FRED rates, buy vs. wait recommendation, cost of waiting, first-time buyer programs.\n- GET /api/wealth/debt-negotiate — $0.15 — DIY debt settlement protocol — settlement percentage ranges, negotiation scripts, FDCPA rights, statute of limitations warning, what to do if sued.\n- GET /api/wealth/advisor — $0.1 — Financial advisor intelligence — action=find (NAPFA/XYPN/CFP search guide + interview questions), action=vet (BrokerCheck + SEC IAPD due diligence), action=comp\n- GET /api/wealth/ssa — $0.15 — Social Security claiming strategy — optimal age (62 vs FRA vs 70), break-even analysis, spousal/survivor benefits, taxation threshold, clear recommendation.\n- GET /api/wealth/tax — $0.15 — Year-end tax optimization — Roth conversion opportunities, tax-loss harvesting, contribution deadlines, charitable strategies, ranked moves with savings estimat\n- GET /api/wealth/roth — $0.1 — Roth vs Traditional IRA/401k decision — income limit check, tax math, backdoor Roth eligibility (pro-rata warning), mega backdoor Roth, 2026 contribution limits\n- GET /api/wealth/emergency — $0.1 — Emergency fund sizing — recommended months (job stability + dependents), dollar target, monthly savings plan, best current HYSA rates and account options.\n- GET /api/wealth/inheritance — $0.1 — Inherited IRA rules under SECURE Act 2.0 — 10-year rule, RMD requirements, spousal rollover options, step-up in basis, distribution strategy to minimize taxes.\n- GET /api/wealth/trump-account — $0.15 — Trump Account (IRC §530A) intelligence — action=eligibility (deterministic account + $1,000 pilot eligibility verdict, Form 4547 next steps), action=strategy (T\n- GET /api/wealth/bank-health — $0.25 — Is my bank safe? FDIC Call Report bank-health check — capital adequacy (Tier 1 leverage, CET1, Tier 1/Total risk-based ratios vs. FDIC Prompt Corrective Action \n- GET /api/wealth/bank-check — $0.02 — FDIC bank-health check, deterministic — the raw component behind bank-health at the component price: PCA capital category (12 CFR 324.403), ROA/ROE/NIM, noncurr\n- GET /api/wealth/unclaimed — $0.5 — Find unclaimed money owed to you — routes to the official FREE US state (NAUPA/MissingMoney), federal (PBGC/FDIC/NCUA/HUD), and international (Canada/UK/Switzer\n- GET /api/wealth/card-benefit — $0.05 — Credit-Card Benefit Coverage Check — Extended warranty, purchase protection, trip delay, cell phone, return protection — checked against ISSUER-verified publish\n- GET /api/wealth/card-benefit-pack — $2 — Card-Benefit Claim Pack — Everything in the coverage check PLUS the complete filing kit: administrator-specific steps, citation-locked cover note, evidence chec\n\nMore APIs from this provider: https://pulsenetwork.theaslangroupllc.com (grouped catalog, all x402)."
  },
  "servers": [
    {
      "url": "https://wealthpulse.theaslangroupllc.com"
    }
  ],
  "paths": {
    "/api/wealth/snapshot": {
      "get": {
        "summary": "Financial health snapshot",
        "description": "How healthy are my finances right now, and what should I fix first? Personalized financial position analysis: health score, strengths, concerns, key ratios (savings rate, DTI, emergency fund months), and highest-leverage action plan ranked by effort vs impact.",
        "operationId": "wealthSnapshot",
        "parameters": [
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual income in USD"
          },
          {
            "name": "savings",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Total savings/investments in USD"
          },
          {
            "name": "debt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Total non-mortgage debt in USD"
          },
          {
            "name": "expenses",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Monthly expenses in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Financial health snapshot with action plan"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/retire": {
      "get": {
        "summary": "Retirement readiness projection",
        "description": "Will I have enough to retire, and what do I need to change? Nest egg projection, gap analysis vs. target income, on-track assessment, 2026 contribution limits, global account support (US 401k/IRA, UK ISA/SIPP, Canada RRSP/TFSA, Australia Super, India PPF/NPS).",
        "operationId": "wealthRetire",
        "parameters": [
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Your current age"
          },
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual income in USD"
          },
          {
            "name": "savings",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Current retirement savings in USD"
          },
          {
            "name": "retire_at",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 65
            }
          },
          {
            "name": "target_income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Retirement projection with gap analysis and action plan"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/debt": {
      "get": {
        "summary": "Avalanche vs snowball debt payoff strategy",
        "description": "Avalanche or snowball — which pays off my debt faster and cheaper? Comparison of both strategies with total interest cost, months to payoff, and a consolidation check at current FRED rates.",
        "operationId": "wealthDebt",
        "parameters": [
          {
            "name": "debts",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "name:balance:rate format, comma-separated (e.g. credit-card:8500:24,car-loan:12000:6.5)"
          },
          {
            "name": "extra",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Extra monthly payment available in USD (optional)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Debt strategy comparison with recommended approach"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/cards": {
      "get": {
        "summary": "Best credit card for your spending profile",
        "description": "Which credit card is actually worth it for my spending? Ranks cards by net annual value (rewards minus fees) for any spending profile. Includes current signup bonuses and multi-card pairing strategy.",
        "operationId": "wealthCards",
        "parameters": [
          {
            "name": "spend_profile",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Required. Free text, e.g. travel, dining, groceries, gas, cashback."
          },
          {
            "name": "monthly",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 3000
            },
            "description": "Monthly spend in USD (default: 3000)"
          },
          {
            "name": "credit_score",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "very_good",
                "excellent"
              ]
            },
            "description": "Approximate credit tier"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top credit card recommendations with net annual value"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/mortgage": {
      "get": {
        "summary": "How much house can I afford",
        "description": "How much house can I actually afford? Home affordability at current FRED mortgage rates, buy vs. wait recommendation, cost-of-waiting analysis, and first-time buyer programs.",
        "operationId": "wealthMortgage",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual gross income in USD"
          },
          {
            "name": "down",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Down payment in USD"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "debt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Existing monthly debt payments in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Affordability analysis with buy vs. wait recommendation"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/debt-negotiate": {
      "get": {
        "summary": "Can I settle this debt for less",
        "description": "Can I settle this debt for less than I owe, and how do I negotiate it myself? DIY debt-negotiation protocol with settlement percentage ranges, creditor scripts, FDCPA rights, statute-of-limitations warning, what to get in writing, and what to do if sued.",
        "operationId": "wealthDebtNegotiate",
        "parameters": [
          {
            "name": "creditor",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The collector or original creditor name"
          },
          {
            "name": "balance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Balance owed in USD"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "credit_card | medical | personal | auto | student"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Negotiation protocol with scripts and FDCPA rights"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/advisor": {
      "get": {
        "summary": "Financial advisor finder, comparison, and background check",
        "description": "Where do I find, compare, or vet a financial advisor? Multi-action financial advisor intelligence. action=find: NAPFA/XYPN/CFP Board search guide with interview questions ($0.10). action=compare: side-by-side comparison with decisive recommendation ($0.10). action=vet: BrokerCheck + SEC IAPD due diligence protocol ($0.15).",
        "operationId": "wealthAdvisor",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "find",
                "compare",
                "vet"
              ]
            },
            "description": "Required. One of: find, compare, vet."
          },
          {
            "name": "specialty",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=find (e.g. retirement planning, tax, estate, investment)"
          },
          {
            "name": "advisors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=compare (e.g. \"Advisor A 1% AUM, Advisor B flat fee\")"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=vet (advisor name)"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional; sharpens action=find directory results (e.g. Denver, CO)"
          },
          {
            "name": "situation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional free-text context about your situation"
          },
          {
            "name": "firm",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional firm name; used alongside name for action=vet"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Advisor intelligence report (find/compare/vet)"
          },
          "400": {
            "description": "Invalid or missing action parameter"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/ssa": {
      "get": {
        "summary": "Social Security claiming strategy",
        "description": "What age should I claim Social Security? Optimal claiming-age analysis with benefit estimates at 62, full retirement age, and 70, break-even math, spousal and survivor benefits, and taxation threshold.",
        "operationId": "wealthSSA",
        "parameters": [
          {
            "name": "birth_year",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Year of birth (used to calculate Full Retirement Age)"
          },
          {
            "name": "income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Annual earnings (for benefit estimate context)"
          },
          {
            "name": "marital_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "married",
                "divorced",
                "widowed"
              ],
              "default": "single"
            }
          },
          {
            "name": "health",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "fair",
                "poor"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Social Security claiming strategy with break-even analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/tax": {
      "get": {
        "summary": "Year-end tax optimization",
        "description": "What tax moves should I make before December 31st? Ranked list of tax-saving moves before December 31st (and April 15 deadline moves). Covers Roth conversions, tax-loss harvesting, contribution deadlines, charitable strategies, with savings estimates per move.",
        "operationId": "wealthTax",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual gross income in USD"
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "married_filing_jointly",
                "married_filing_separately",
                "head_of_household"
              ],
              "default": "single"
            }
          },
          {
            "name": "situation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated: RSU_vesting,home_sale,bonus,capital_gains,inherited_assets"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Year-end tax optimization opportunities ranked by savings"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/roth": {
      "get": {
        "summary": "Roth vs Traditional IRA/401k decision",
        "description": "Should I contribute to a Roth or Traditional IRA/401(k)? Income limit check, tax math, backdoor Roth eligibility (with pro-rata rule warning), mega backdoor Roth eligibility, 2026 contribution limits.",
        "operationId": "wealthRoth",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual gross income in USD"
          },
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Your current age"
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "married_filing_jointly"
              ],
              "default": "single"
            }
          },
          {
            "name": "employer_match",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "Whether your employer offers a 401k match (yes/no)"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Roth vs Traditional recommendation with tax math"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/emergency": {
      "get": {
        "summary": "Emergency fund sizing",
        "description": "How big should my emergency fund be, and how do I build it? Recommended emergency fund target (months and dollars) based on job stability and dependents, monthly savings plan to reach it, and best current HYSA accounts with live rates.",
        "operationId": "wealthEmergency",
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "Annual income in USD"
          },
          {
            "name": "expenses",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Monthly expenses in USD"
          },
          {
            "name": "job_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "stable",
                "variable",
                "entrepreneur"
              ],
              "default": "stable"
            }
          },
          {
            "name": "dependents",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Number of dependents"
          },
          {
            "name": "current_fund",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Existing emergency fund in USD"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Emergency fund target with funding plan and HYSA recommendations"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/inheritance": {
      "get": {
        "summary": "Inherited IRA and estate rules",
        "description": "I inherited an IRA — what are the rules and how do I minimize taxes? Inherited IRA rules under SECURE Act 2.0: 10-year rule, RMD requirements, spousal rollover options, step-up in basis for inherited taxable assets, and optimal distribution strategy to minimize taxes.",
        "operationId": "wealthInheritance",
        "parameters": [
          {
            "name": "relationship",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "spouse",
                "non-spouse",
                "minor-child",
                "disabled",
                "chronically-ill",
                "not-more-than-10-years-younger",
                "trust",
                "charity"
              ]
            }
          },
          {
            "name": "account_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "traditional",
                "roth"
              ],
              "default": "traditional"
            }
          },
          {
            "name": "balance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "Inherited account balance in USD"
          },
          {
            "name": "your_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Your current age"
          },
          {
            "name": "original_owner_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Original owner's age at time of death"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inherited IRA rules and distribution strategy"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/trump-account": {
      "get": {
        "summary": "Trump Account (IRC §530A) eligibility, strategy, and rules",
        "description": "Is my child eligible for the $1,000 Trump Account pilot? Trump Account vs 529? What are the current contribution, investment, and distribution rules? Multi-action Trump Account intelligence, verified against 26 USC §530A, §6434, IRS Notice 2025-68, and Rev. Proc. 2026-25. action=eligibility: deterministic account + $1,000 pilot eligibility verdict with Form 4547 next steps. action=strategy: Trump Account vs 529 vs Roth-for-kids vs UTMA comparison by goal. action=rules: current verified rules by topic, flagging commonly-misreported points and proposed-regs-pending status (hearing 2026-07-16).",
        "operationId": "wealthTrumpAccount",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "eligibility",
                "strategy",
                "rules"
              ],
              "default": "rules"
            },
            "description": "Which analysis to run. Defaults to rules."
          },
          {
            "name": "birth_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Required for action=eligibility unless birth_date is given. The child's birth year."
          },
          {
            "name": "birth_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alternative to birth_year for action=eligibility (e.g. 2026-03-15)"
          },
          {
            "name": "has_ssn",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "For action=eligibility: does the child have a Social Security Number"
          },
          {
            "name": "ssn_work_valid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "For action=eligibility: is that SSN valid for employment, issued before election"
          },
          {
            "name": "us_citizen",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "For action=eligibility: is the child a US citizen. Required for the $1,000 pilot only — NOT required for the account itself."
          },
          {
            "name": "prior_election",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "For action=eligibility: has an account already been elected for this child"
          },
          {
            "name": "goal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "education",
                "general",
                "retirement"
              ],
              "default": "general"
            },
            "description": "For action=strategy: the savings goal for this child"
          },
          {
            "name": "child_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "For action=strategy: the child's current age"
          },
          {
            "name": "employer_program",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            },
            "description": "For action=strategy: does an employer offer a Trump Account matching program"
          },
          {
            "name": "budget_yearly",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "For action=strategy: how much can be contributed per year, in USD"
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "contributions",
                "investments",
                "distributions",
                "tax",
                "enrollment"
              ]
            },
            "description": "For action=rules (optional): focus the rules answer on this topic"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trump Account eligibility verdict, strategy comparison, or rules reference"
          },
          "400": {
            "description": "Missing required parameter (birth_year/birth_date) for action=eligibility"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/bank-health": {
      "get": {
        "summary": "Is my bank safe? FDIC Call Report bank-health check",
        "description": "Bank-safety check computed directly from official FDIC quarterly Call Report data (banks.data.fdic.gov): capital adequacy (Tier 1 leverage, CET1, Tier 1 and Total risk-based ratios vs. FDIC Prompt Corrective Action thresholds, 12 CFR 324.403), earnings (ROA, ROE, net interest margin), asset quality (noncurrent loans, loan-loss reserve coverage), commercial real estate asset-quality ratios, year-over-year deposit growth, and estimated uninsured-deposit share — plus an 8-quarter trend. All ratios are computed deterministically in code, not by the model; the response includes the exact FDIC report date (data_as_of) and cites which figures are FDIC's own published ratios vs. computed here from raw dollar fields.",
        "operationId": "wealthBankHealth",
        "parameters": [
          {
            "name": "bank",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Bank name or FDIC certificate (CERT) number"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code, disambiguates a common bank name"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank health computed ratios, 8-quarter trend, and plain-language read"
          },
          "400": {
            "description": "Missing required parameter (bank)"
          },
          "402": {
            "description": "Payment required"
          },
          "404": {
            "description": "No FDIC-insured institution matched the given name/state (suggestions included)"
          }
        },
        "x-price-usd": 0.25,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.250000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/bank-check": {
      "get": {
        "summary": "FDIC bank-health check — deterministic Call Report primitive",
        "description": "The raw deterministic component behind bank-health, at the component price: resolves a US bank by name or FDIC certificate number, then computes from FDIC quarterly Call Reports (banks.data.fdic.gov) the PCA capital category (Tier 1 leverage, CET1, Tier 1 and Total risk-based ratios vs. 12 CFR 324.403 thresholds), ROA/ROE/net interest margin, noncurrent-loan and loan-loss-reserve-coverage ratios, CRE asset-quality ratios, year-over-year deposit growth, estimated uninsured-deposit share, and an 8-quarter trend. Closed/failed institutions are included with their charter-end date. No LLM, no key, public domain. The $0.25 /api/wealth/bank-health adds a plain-language multilingual read on top of these exact figures.",
        "operationId": "wealthBankCheck",
        "parameters": [
          {
            "name": "bank",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Bank name or FDIC certificate (CERT) number",
            "example": "628"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code, disambiguates a common bank name"
          }
        ],
        "responses": {
          "200": {
            "description": "Deterministic bank-health block: capital, earnings, asset quality, liquidity, 8-quarter trend"
          },
          "400": {
            "description": "Missing/invalid parameter (no payment settled)"
          },
          "402": {
            "description": "Payment required"
          },
          "404": {
            "description": "No FDIC-insured institution matched the given name/state (suggestions included; no payment settled)"
          },
          "502": {
            "description": "FDIC BankFind unavailable — transport failure, not a statement about the bank"
          }
        },
        "x-price-usd": 0.02,
        "x-agent-use-case": "component",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/unclaimed": {
      "get": {
        "summary": "Find unclaimed money owed to you",
        "description": "Deterministic router across US state unclaimed-property programs (NAUPA/MissingMoney), federal sources matched to your situation (PBGC pensions, FDIC/NCUA failed institutions, HUD/FHA refunds), and international registers (Canada, UK, Switzerland, Australia). Returns the exact official FREE portals to search in order, the claim-documentation package, and an honest coverage block distinguishing openly-searchable sources from route-only ones. No LLM — a routing machine, not a scraper; never queries automation-restricted sites.",
        "operationId": "wealthUnclaimed",
        "x-price-usd": 0.5,
        "parameters": [
          {
            "name": "states",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated US state codes you have lived/worked in (e.g. CA,TX,NY)"
          },
          {
            "name": "countries",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated non-US jurisdictions: CA (Canada), GB, CH, AU, AU-VIC, AU-NSW"
          },
          {
            "name": "situations",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Life events unlocking federal/special sources: former_pension | failed_bank | failed_credit_union | fha_mortgage | savings_bonds | deceased_relative | old_employer | moved_states | former_business"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional — personalizes search instructions only; never transmitted or stored"
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered search plan, federal matches, claim package, coverage-honesty block"
          },
          "400": {
            "description": "Provide at least one of states, countries, or situations"
          },
          "402": {
            "description": "Payment required (x402)"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/card-benefit": {
      "get": {
        "summary": "Credit-Card Benefit Coverage Check",
        "description": "Extended warranty, purchase protection, trip delay, cell phone, return protection — checked against ISSUER-verified published benefit guides (never network defaults: same-tier caps vary 20x by issuer). Caps, deductibles, eligibility windows, recoverable estimate, and the notify/document deadlines that kill late claims. Includes authoritative negative facts (Discover: nothing; Capital One World MC: gutted 2025). No LLM. $0.10.",
        "operationId": "cardBenefitCheck",
        "parameters": [
          {
            "name": "issuer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card issuer slug (chase, amex, capital-one, citi, hsbc, discover, amex-uk, rbc)"
          },
          {
            "name": "card",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card slug (sapphire-reserve, platinum, venture-x, ...)"
          },
          {
            "name": "benefit",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "extended_warranty",
                "purchase_protection",
                "trip_delay",
                "cell_phone",
                "return_protection"
              ]
            },
            "description": "Benefit to check"
          },
          {
            "name": "purchase_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Item/ticket purchase date YYYY-MM-DD (eligibility windows + warranty math)"
          },
          {
            "name": "incident_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Damage/theft/delay date YYYY-MM-DD — filing deadlines computed from this"
          },
          {
            "name": "item_price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Item price — recoverable estimate = min(price, cap) - deductible"
          },
          {
            "name": "warranty_years",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Extended warranty: original manufacturer warranty length"
          },
          {
            "name": "delay_hours",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Trip delay: hours delayed (triggers are 6h or 12h by card tier)"
          },
          {
            "name": "phone_paid_on_card",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Cell phone: was the prior month's wireless bill paid on this card"
          }
        ],
        "responses": {
          "200": {
            "description": "Coverage verdict, deadlines, administrator, filing guidance"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/card-benefit-preview": {
      "get": {
        "summary": "Card-Benefit Coverage PREVIEW",
        "description": "Agent-tier $0.25 preview of the card-benefit registry: scans one card across all 5 protections (extended warranty, purchase protection, trip delay, cell phone, return protection) and reports which likely apply, which need more info, which are ineligible now, and which the card does not carry. Same deterministic registry as the $0.05 single-benefit check and $2.00 claim pack. No LLM.",
        "operationId": "cardBenefitPreview",
        "parameters": [
          {
            "name": "issuer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card issuer slug (chase, amex, capital-one, citi, hsbc, discover, amex-uk, rbc)"
          },
          {
            "name": "card",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card slug (sapphire-reserve, platinum, venture-x, ...)"
          },
          {
            "name": "purchase_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Item/ticket purchase date YYYY-MM-DD (sharpens purchase/return-protection and warranty results)"
          },
          {
            "name": "incident_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Damage/theft/delay date YYYY-MM-DD (sharpens deadline eligibility)"
          },
          {
            "name": "item_price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Item price"
          },
          {
            "name": "warranty_years",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Extended warranty: original manufacturer warranty length"
          },
          {
            "name": "delay_hours",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Trip delay: hours delayed"
          },
          {
            "name": "phone_paid_on_card",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Cell phone: was the prior month's wireless bill paid on this card"
          }
        ],
        "responses": {
          "200": {
            "description": "Per-benefit likely-covered scan, counts, and upsell to the full check/pack"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.25,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.250000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/wealth/card-benefit-pack": {
      "get": {
        "summary": "Card-Benefit Claim Pack",
        "description": "Everything in the coverage check PLUS the complete filing kit: administrator-specific steps, citation-locked cover note, evidence checklist, denial counters, deadline calendar. Honest-no: no pack sold on expired windows, uncovered cards, or unmet conditions. $2.00.",
        "operationId": "cardBenefitPack",
        "parameters": [
          {
            "name": "issuer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card issuer slug (chase, amex, capital-one, citi, hsbc, discover, amex-uk, rbc)"
          },
          {
            "name": "card",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Card slug (sapphire-reserve, platinum, venture-x, ...)"
          },
          {
            "name": "benefit",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "extended_warranty",
                "purchase_protection",
                "trip_delay",
                "cell_phone",
                "return_protection"
              ]
            },
            "description": "Benefit to check"
          },
          {
            "name": "purchase_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Item/ticket purchase date YYYY-MM-DD (eligibility windows + warranty math)"
          },
          {
            "name": "incident_date",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Damage/theft/delay date YYYY-MM-DD — filing deadlines computed from this"
          },
          {
            "name": "item_price",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Item price — recoverable estimate = min(price, cap) - deductible"
          },
          {
            "name": "warranty_years",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Extended warranty: original manufacturer warranty length"
          },
          {
            "name": "delay_hours",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Trip delay: hours delayed (triggers are 6h or 12h by card tier)"
          },
          {
            "name": "phone_paid_on_card",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Cell phone: was the prior month's wireless bill paid on this card"
          },
          {
            "name": "item_description",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "What the item/trip is (cover note)"
          },
          {
            "name": "cardholder_name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Name for the cover note (placeholder if omitted)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pack language (default English)"
          }
        ],
        "responses": {
          "200": {
            "description": "Engine result + filing pack JSON"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 2,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "2.000000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    }
  }
}