{
  "openapi": "3.1.0",
  "info": {
    "title": "WealthPulse API",
    "description": "Personal finance intelligence API. 12 endpoints grounded in live FRED rate data \u2014 financial health, retirement, debt, credit cards, mortgage, Social Security, tax optimization, Roth vs Traditional, emergency fund, inherited IRA, debt negotiation, and financial advisor intelligence. All endpoints require x402 payment (USDC on Base mainnet).",
    "version": "2.1.0",
    "contact": {
      "url": "https://wealthpulse-phi.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://wealthpulse-phi.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive a 402 with payment requirements. Sign and retry to receive data."
      }
    }
  },
  "paths": {
    "/api/wealth/snapshot": {
      "get": {
        "summary": "Financial health snapshot",
        "description": "Personalized financial position analysis \u2014 health score, strengths, concerns, key ratios (savings rate, DTI, emergency fund months), and highest-leverage action plan ranked by effort vs impact.",
        "operationId": "wealthSnapshot",
        "security": [
          {
            "x402": []
          }
        ],
        "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"
            }
          },
          {
            "name": "debt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/retire": {
      "get": {
        "summary": "Retirement readiness projection",
        "description": "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",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "savings",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/debt": {
      "get": {
        "summary": "Debt payoff strategy",
        "description": "Avalanche vs snowball comparison with total interest cost, months to payoff, consolidation check at current FRED rates, extra payment impact.",
        "operationId": "wealthDebt",
        "security": [
          {
            "x402": []
          }
        ],
        "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"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/cards": {
      "get": {
        "summary": "Credit card optimization",
        "description": "Best credit cards for any spending profile, ranked by net annual value (rewards minus fees). Includes current signup bonuses and multi-card pairing strategy.",
        "operationId": "wealthCards",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "spend_profile",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "monthly",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 3000
            }
          },
          {
            "name": "credit_score",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "very_good",
                "excellent"
              ]
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/mortgage": {
      "get": {
        "summary": "Mortgage affordability analysis",
        "description": "Home affordability at current FRED mortgage rates, buy vs. wait recommendation, cost-of-waiting analysis, and first-time buyer programs.",
        "operationId": "wealthMortgage",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "down",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "debt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/debt-negotiate": {
      "get": {
        "summary": "DIY debt negotiation protocol",
        "description": "Settlement percentage ranges, creditor scripts, FDCPA rights, statute of limitations warning, what to get in writing, what to do if sued.",
        "operationId": "wealthDebtNegotiate",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "creditor",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "balance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/advisor": {
      "get": {
        "summary": "Financial advisor intelligence",
        "description": "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",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "find",
                "compare",
                "vet"
              ]
            }
          },
          {
            "name": "specialty",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=find"
          },
          {
            "name": "advisors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=compare"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required for action=vet"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "situation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "firm",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "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.10 (find/compare) | 0.15 (vet)",
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/wealth/ssa": {
      "get": {
        "summary": "Social Security claiming strategy",
        "description": "Optimal age to claim Social Security \u2014 FRA calculation by birth year, break-even math (62 vs FRA vs 70), spousal/survivor benefits, taxation threshold, and clear recommendation based on health and marital status.",
        "operationId": "wealthSSA",
        "security": [
          {
            "x402": []
          }
        ],
        "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"
      }
    },
    "/api/wealth/tax": {
      "get": {
        "summary": "Year-end tax optimization",
        "description": "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",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/roth": {
      "get": {
        "summary": "Roth vs Traditional IRA/401k decision",
        "description": "Determines whether to contribute to Roth or Traditional accounts \u2014 income limit check, tax math, backdoor Roth eligibility (with pro-rata rule warning), mega backdoor Roth eligibility, 2026 contribution limits.",
        "operationId": "wealthRoth",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "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"
              ]
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/emergency": {
      "get": {
        "summary": "Emergency fund sizing",
        "description": "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",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "income",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "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"
            }
          },
          {
            "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"
      }
    },
    "/api/wealth/inheritance": {
      "get": {
        "summary": "Inherited IRA and estate rules",
        "description": "Inherited IRA rules under SECURE Act 2.0 \u2014 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",
        "security": [
          {
            "x402": []
          }
        ],
        "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"
            }
          },
          {
            "name": "your_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "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"
      }
    }
  }
}