{
  "openapi": "3.1.0",
  "info": {
    "title": "PropPulse API",
    "description": "Global real estate intelligence API — 10 endpoints covering the full property lifecycle. Mortgage analysis (with Rocket Mortgage/LendingTree/Better lender links), affordability, rent-vs-buy modeling, refinance opportunity, local market intelligence, investment property ROI (cap rate, cash-on-cash, 5-year projection), AVM property valuation, neighborhood intelligence (schools, safety, walkability), first-time homebuyer guide (all state/federal assistance programs), and landlord toolkit (rent pricing, tenant screening, local lease law). Powered by FRED housing data, Tavily live search, and Claude synthesis. All require x402 micropayment (USDC on Base).",
    "version": "1.2.0",
    "contact": { "url": "https://proppulse.vercel.app" }
  },
  "servers": [{ "url": "https://proppulse.vercel.app" }],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive 402 with payment requirements. Sign and retry."
      }
    }
  },
  "security": [{ "x402": [] }],
  "paths": {
    "/api/prop/mortgage": {
      "get": {
        "operationId": "propMortgage",
        "summary": "Mortgage analysis — current rates, payment breakdown, max price, lender links",
        "description": "Current rate snapshot (30yr fixed, 15yr, ARM, FHA), monthly payment breakdown (PITI + PMI), maximum affordable home price from 28% DTI rule, lender options, and rate lock advice. Response includes Rocket Mortgage, LendingTree, and Better Mortgage affiliate links for lender comparison. US and Canada primary; international mortgage markets covered on request.",
        "parameters": [
          { "name": "income", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Annual gross income" },
          { "name": "down", "in": "query", "schema": { "type": "number" }, "description": "Down payment in USD. Defaults to 20%." },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, state, zip, or country for local context" },
          { "name": "debt", "in": "query", "schema": { "type": "number" }, "description": "Existing monthly debt payments (car, student loans)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Mortgage analysis with rate snapshot, payment breakdown, affordability, and lender links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/afford for honest affordability ceiling, or /api/prop/first-buyer for down payment assistance programs"
      }
    },
    "/api/prop/afford": {
      "get": {
        "operationId": "propAfford",
        "summary": "True affordability analysis — stress-free vs. bank-qualifying ceiling",
        "description": "Honest affordability ceiling — not just what the bank approves, but what the buyer can actually sustain. Computes PITI + PMI + HOA + maintenance reserve + insurance. Shows stress-free threshold (25% income) vs. bank-qualifying limit (43% DTI). Response includes mortgage lender links for pre-approval.",
        "parameters": [
          { "name": "income", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Annual gross income" },
          { "name": "down", "in": "query", "schema": { "type": "number" }, "description": "Available down payment" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "US zip or country for property tax lookup" },
          { "name": "debt", "in": "query", "schema": { "type": "number" }, "description": "Existing monthly debt payments" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Affordability analysis with thresholds, breakdowns, and lender links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use with /api/prop/first-buyer to find down payment assistance if savings are below the floor"
      }
    },
    "/api/prop/rentbuy": {
      "get": {
        "operationId": "propRentBuy",
        "summary": "Rent vs. buy decision model — break-even, 5-year wealth comparison, recommendation",
        "description": "Full rent-vs-buy model with break-even timeline, 5-year net worth comparison (both paths), opportunity cost of down payment, equity accrual, and a clear buy/rent/wait recommendation. Accounts for market appreciation, transaction costs (closing, agent, title), and mobility premium. Global coverage — works for any currency and market.",
        "parameters": [
          { "name": "rent", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Current monthly rent in local currency" },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City or country — drives local market data" },
          { "name": "savings", "in": "query", "schema": { "type": "number" }, "description": "Available savings / potential down payment" },
          { "name": "years", "in": "query", "schema": { "type": "number" }, "description": "Planned years in home. Defaults to 5." },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Rent vs. buy analysis with break-even, wealth comparison, and recommendation" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/prop/refi": {
      "get": {
        "operationId": "propRefi",
        "summary": "Refinance opportunity analysis — break-even, monthly savings, cash-out potential",
        "description": "Honest refinance analysis: break-even timeline, monthly savings, total interest saved over loan life, and cash-out option if equity allows. Includes the 1% rate-drop rule heuristic vs. actual break-even math. Response includes current lender links for rate shopping. Works for any country where variable/fixed rate transitions are common.",
        "parameters": [
          { "name": "rate", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Current interest rate as percentage (e.g. 7.25)" },
          { "name": "balance", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Remaining loan balance" },
          { "name": "years_left", "in": "query", "schema": { "type": "number" }, "description": "Years remaining on current loan. Defaults to 25." },
          { "name": "home_value", "in": "query", "schema": { "type": "number" }, "description": "Current home value (enables cash-out analysis)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Refinance analysis with break-even, savings, and lender links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/prop/market": {
      "get": {
        "operationId": "propMarket",
        "summary": "Local market intelligence — buyer/seller conditions, price trends, inventory",
        "description": "Hyperlocal market intelligence: buyer/seller market rating, market score (0-100), price trend (appreciation/depreciation rate), days on market, months of supply, price reduction frequency, and concrete briefings for buyers and sellers. Sourced from FRED, Zillow research, NAR data, and Tavily live search.",
        "parameters": [
          { "name": "zip", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US zip code or city/country for international markets" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Market intelligence with price trends, supply/demand, and buyer/seller briefings" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/neighborhood for a complete area analysis, or /api/prop/valuate for property-specific pricing"
      }
    },
    "/api/prop/invest": {
      "get": {
        "operationId": "propInvest",
        "summary": "Investment property ROI — cap rate, cash-on-cash, 5-year projection, investment grade",
        "description": "Complete investment property analysis: cap rate estimate, cash-on-cash return (assuming 20-25% down), gross rent multiplier, price-to-rent ratio, break-even occupancy, 5-year appreciation scenarios (low/mid), and an A-D investment grade. Factors in typical expenses (1.2% property tax, 0.5% insurance, 1% maintenance, 5% vacancy, 8% management). Response includes mortgage lender links for investment financing. Best for single-family, multifamily, and short-term rental evaluation.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Austin, TX" },
          { "name": "price", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Purchase price in local currency" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "single-family / multifamily / condo / short-term", "example": "single-family" },
          { "name": "rent", "in": "query", "schema": { "type": "string" }, "description": "Expected monthly rent — estimated from market data if omitted" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Investment analysis with metrics, grade, projections, and financing links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/neighborhood for market context, or /api/prop/landlord for local regulations"
      }
    },
    "/api/prop/valuate": {
      "get": {
        "operationId": "propValuate",
        "summary": "Property valuation — AVM estimate with comparable sales and negotiation intelligence",
        "description": "AVM-style property valuation using comparable sales, FHFA HPI, Zillow research, and local market data. Returns a value range (low/mid/high) with confidence level, comparable sales analysis, price-per-sqft context, market trend, and specific negotiation advice (what to offer, how far under/over ask). Essential for buyers making offers and sellers setting list price.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Full property address (e.g. 123+Main+St+Austin+TX)" },
          { "name": "sqft", "in": "query", "schema": { "type": "string" }, "description": "Square footage (improves estimate)" },
          { "name": "beds", "in": "query", "schema": { "type": "string" }, "description": "Bed/bath description (e.g. 3/2)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Property valuation with value range, comps, trend, and negotiation advice" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Follow with /api/prop/neighborhood for area intelligence to support the offer decision"
      }
    },
    "/api/prop/neighborhood": {
      "get": {
        "operationId": "propNeighborhood",
        "summary": "Neighborhood intelligence — schools, safety, walkability, investment outlook",
        "description": "Comprehensive neighborhood profile: school ratings, safety/crime context, walkability and transit scores, amenity density, demographic character, and a gentrification-stage assessment for investment. Returns an overall score (1-10), strengths, and who the neighborhood is best for (families, investors, young professionals, retirees). Works globally — not limited to US.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Neighborhood, city district, or full address", "example": "Boerum Hill, Brooklyn, NY" },
          { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "schools / investment / walkability / safety / balanced" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Neighborhood profile with scores, school data, safety context, and investment outlook" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Chain after /api/prop/valuate for full area + property analysis before making an offer"
      }
    },
    "/api/prop/first-buyer": {
      "get": {
        "operationId": "propFirstBuyer",
        "summary": "First-time homebuyer guide — all assistance programs, loan types, step-by-step process",
        "description": "Complete first-time homebuyer guide: all federal and state/local down payment assistance programs by location and income, FHA/VA/USDA/conventional loan comparison, closing cost estimate, hidden costs, credit optimization advice, and a step-by-step purchase process timeline. Covers 50 US states + major international markets. Response includes mortgage lender links for pre-approval. The most important endpoint for first-time buyers who don't know what programs they qualify for.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "US state/city or country for program research", "example": "Colorado" },
          { "name": "income", "in": "query", "schema": { "type": "string" }, "description": "Annual household income — affects program eligibility" },
          { "name": "savings", "in": "query", "schema": { "type": "string" }, "description": "Available savings for down payment" },
          { "name": "credit", "in": "query", "schema": { "type": "string" }, "description": "Credit score range (e.g. 680)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "First-time buyer guide with all assistance programs, process timeline, and lender links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/afford to determine realistic purchase ceiling before starting the process"
      }
    },
    "/api/prop/landlord": {
      "get": {
        "operationId": "propLandlord",
        "summary": "Landlord toolkit — rent pricing, tenant screening, lease law, local regulations",
        "description": "Complete landlord reference for any US city or international jurisdiction: rent pricing recommendation (with vacancy/demand context), fair tenant screening process, legally required notice periods, eviction process and timeline, rent control status, security deposit limits, maintenance obligations, tax deduction checklist (depreciation, repairs, management fees), and tool recommendations (Avail vs. TurboTenant vs. property manager). Response includes Avail and TurboTenant landlord software links. Be specific to the jurisdiction — laws vary enormously by city.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "City and state/country — drives jurisdiction-specific legal guidance", "example": "Chicago, IL" },
          { "name": "units", "in": "query", "schema": { "type": "string" }, "description": "Number of rental units" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "long-term / short-term / furnished" },
          { "name": "situation", "in": "query", "schema": { "type": "string" }, "description": "general / finding-tenants / eviction / raising-rent / maintenance" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Landlord toolkit with rent pricing, screening process, local law, and landlord software links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/invest to evaluate a property before becoming its landlord"
      }
    }
  }
}