# HomePulse

> Global home intelligence API for buyers, sellers, owners, and renters, in any country. Value estimates, neighborhood analysis, improvement ROI, contractor vetting, energy efficiency, seasonal maintenance, smart home advice, and rental market data — via x402 micropayments on Base mainnet. Pass `location` (postal code or city) and `country` (e.g. US, UK, CA, DE, AU) on any endpoint for jurisdiction-correct currency, incentive programs, licensing authorities, and legal terminology; `zip` is accepted as a legacy alias for `location`.

## Endpoints

GET /api/home/value?address={address}&location={location}&country={country}
- Returns: estimated value range (low/mid/high) in local currency, confidence rating, market trend, comparable sales, best time to act, key value factors
- At least one of address or location required; zip accepted as legacy alias for location
- Optional: country (e.g. US, UK, CA, DE, AU), lang
- Price: $0.10

GET /api/home/neighborhood?location={location}&city={city}&state={state}&country={country}
- Returns: overall score, school rating, relative safety, walkability, neighborhood character, HOA-equivalent intelligence, flood-risk intelligence (jurisdiction-correct authority), best-for/not-ideal-for, nearby highlights
- At least one of location or city required; zip accepted as legacy alias for location
- Optional: state (province/region), country, lang
- Price: $0.10

GET /api/home/improve?project={project}&home_value={value}&location={location}&country={country}
- Returns: ROI summary (cost range, value added, recoup rating) in local currency, permit/planning-permission guidance for the stated jurisdiction, best-for (selling/staying/both/neither), DIY vs contractor analysis, materials list with Amazon links, pro tips, top ROI projects
- project examples: kitchen-remodel, bathroom-remodel, deck-addition, new-roof, finished-basement
- Optional: home_value (in local currency), location, country, zip (legacy alias), lang
- Price: $0.10

GET /api/home/roi?project={project}&region={region}&country={country}&home_value={value}
- Returns: cost-vs-value resale return using US NAR Cost vs Value data (or the closest local benchmark for non-US countries, clearly labeled), recoup percentage, DIY-vs-contractor savings, comparable projects
- Optional: region, country (e.g. US, UK, CA, DE, AU), home_value (in local currency), lang
- Price: $0.10

GET /api/home/contractor?trade={trade}&location={location}&country={country}
- Returns: licensing/registration authority for the trade and jurisdiction (US state board, UK Gas Safe/NICEIC, Canada provincial board, Germany Handwerkskammer, Australia state licensing), insurance requirements, red flags, contract checklist, payment-schedule guidance
- trade required (e.g. plumber, electrician, roofer)
- Optional: location, country, zip (legacy alias), lang
- Price: $0.10

GET /api/home/energy?home_type={type}&location={location}&country={country}&age={age}&sqft={sqft}
- Returns: efficiency improvements ranked by payback period with the country-correct incentive program applied (US IRA 25C/25D, UK ECO4/Boiler Upgrade Scheme, Germany BEG, Canada Greener Homes, Australia state rebates), cost estimates, annual savings, climate guidance
- Optional: home_type, location, country, zip (legacy alias), age, sqft, lang
- Price: $0.10

GET /api/home/maintain?region={region}&season={season}&country={country}
- Returns: prioritized task list with urgency/cost/DIY/time, tools and supplies list with Amazon links, total season cost estimate in local currency, critical task warning, next season preview
- season: spring | summer | fall | winter (defaults to current season, hemisphere-corrected when country is given — seasons run six months opposite south of the equator)
- Optional: region, country (e.g. US, UK, CA, DE, AU), lang
- Price: $0.08

GET /api/home/maintenance?region={region}&home_age={age}&season={season}&features={features}&country={country}
- Returns: a full personalized seasonal maintenance calendar tailored by region, country, home age, and features (pool, fireplace, deck, basement), with cost estimates in local currency and DIY-vs-pro guidance
- region required
- Optional: country, home_age, season (spring|summer|fall|winter|all, default: all), features, lang
- Price: $0.08

GET /api/home/smart?ecosystem={ecosystem}&room={room}&budget={budget}&country={country}
- Returns: device recommendations with Matter certification status, ecosystem fit (Alexa/Google Home/HomeKit), plug type/voltage and regional availability notes for the stated country, setup guidance
- Optional: ecosystem, room, budget (in local currency), country, lang
- Price: $0.08

GET /api/home/rent?location={location}&city={city}&state={state}&bedrooms={n}&country={country}
- Returns: market trend, rent ranges by bedroom count (studio through 3BR) in local currency, official government fair-market-rent benchmark where one exists (US HUD FMR only — HUD FMR does not apply outside the US), best neighborhoods to rent, renting vs buying comparison, renter tips
- At least one of location or city required; zip accepted as legacy alias for location; state required for HUD data (US only)
- Optional: bedrooms, county (US HUD FMR matching), country, lang
- Price: $0.08

## Payment

All endpoints use x402 protocol. No payment header → HTTP 402 with PAYMENT-REQUIRED header (0.08–0.10 USDC on Base mainnet). Send valid PAYMENT-SIGNATURE → 200 with structured JSON.

## Data Sources

- HUD Fair Market Rent API (huduser.gov) — official US-only FMR data, free token required
- Tavily — real-time market data, neighborhood research, contractor licensing, comparable sales, jurisdiction-aware queries (portal/source selection adapts to the country param)
- Claude — synthesis and plain-English, jurisdiction-correct analysis

## Affiliate Disclosure

Improvement and maintenance responses include Amazon affiliate links (tag: pulsenetwork7-20) for recommended parts, tools, and supplies.

## Disclaimer

For informational purposes only. Value estimates are not formal appraisals. Regulatory, licensing, and incentive-program details vary by country and change over time — always verify current local requirements with a qualified professional before acting.