# HomePulse

> Home intelligence API for buyers, sellers, owners, and renters. Value estimates, neighborhood analysis, improvement ROI, seasonal maintenance, and rental market data — via x402 micropayments on Base mainnet.

## Endpoints

GET /api/home/value?address={address}&zip={zip}
- Returns: estimated value range (low/mid/high), confidence rating, market trend, comparable sales, best time to act, key value factors
- Optional: lang
- Price: $0.10

GET /api/home/neighborhood?zip={zip}&city={city}&state={state}
- Returns: overall score, school rating, relative safety, walkability, neighborhood character, best-for/not-ideal-for, nearby highlights
- At least one of zip or city required
- Optional: lang
- Price: $0.10

GET /api/home/improve?project={project}&home_value={value}
- Returns: ROI summary (cost range, value added, recoup rating), best-for (selling/staying/both/neither), DIY vs contractor analysis, materials list with Amazon links, pro tips, top national ROI projects
- project examples: kitchen-remodel, bathroom-remodel, deck-addition, new-roof, finished-basement
- Optional: home_value (integer), lang
- Price: $0.10

GET /api/home/maintain?region={region}&season={season}
- Returns: prioritized task list with urgency/cost/DIY/time, tools and supplies list with Amazon links, total season cost estimate, critical task warning, next season preview
- season: spring | summer | fall | winter (defaults to current season if omitted)
- Optional: region (e.g. Northeast, Pacific Northwest, Southeast), lang
- Price: $0.08

GET /api/home/rent?zip={zip}&city={city}&state={state}&bedrooms={n}
- Returns: market trend, rent ranges by bedroom count (studio through 3BR), HUD fair market rent (official, when available), best neighborhoods to rent, renting vs buying comparison, renter tips
- At least one of zip or city required; state required for HUD data
- Optional: bedrooms (integer), county (for HUD county matching), 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 FMR data, free token required
- Tavily — real-time market data, neighborhood research, contractor costs, comparable sales
- Claude Sonnet — synthesis and plain-English 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. Always consult qualified professionals for real estate and financial decisions.