# StableEstate API

> US real estate data API — rental listings, sale listings, property records, valuations, rent estimates, and market statistics. Powered by MLS data via RentCast. All 50 US states.

## Payment

This API uses the x402 payment protocol. All data endpoints cost $0.01 per request paid via x402 on Base mainnet.

- **Protocol:** x402 (HTTP 402 Payment Required)
- **Price:** $0.01 per request
- **Network:** Base mainnet (eip155:8453)
- **Scheme:** exact

When you call a paid endpoint without payment, you'll receive HTTP 402 with payment requirements in the response headers. Use an x402-compatible client (e.g. AgentCash) to handle payment automatically.

Free endpoints (no payment required): `/api/health`, `/llms.txt`, `/openapi.json`

## Endpoints

| Method | Path | Description | Price |
|--------|------|-------------|-------|
| POST/GET | /api/apartments/search | Search rental listings | $0.01 |
| POST/GET | /api/properties/search | Search property records (attributes, tax, ownership) | $0.01 |
| POST/GET | /api/properties/random | Get random property records | $0.01 |
| GET | /api/properties/{id} | Get property record by ID | $0.01 |
| POST/GET | /api/valuations/value | Property value estimate + comps | $0.01 |
| POST/GET | /api/valuations/rent | Rent estimate + comps | $0.01 |
| POST/GET | /api/sales/search | Search for-sale listings | $0.01 |
| POST/GET | /api/markets | Market statistics by zip code | $0.01 |
| GET | /openapi.json | OpenAPI spec for agent discovery | Free |
| GET | /api/health | Health check | Free |
| GET | /llms.txt | API documentation | Free |

---

## Rental Listings Search — /api/apartments/search

Search active rental listings across all 50 US states.

### Location (provide at least one)

| Parameter | Type | Description |
|-----------|------|-------------|
| location | string | Freeform: "Brooklyn, NY", "Austin", "10001" — parses city/state/zip automatically |
| city | string | City name (use with state) |
| state | string | Two-letter state code |
| zipCode | string | ZIP code |
| address | string | Street address |
| latitude | number | Center of radius search |
| longitude | number | Center of radius search |
| radius | number | Search radius in miles (max 100) |

### Filters

| Parameter | Type | Description |
|-----------|------|-------------|
| minBedrooms | number | Minimum bedrooms (alias: bedrooms) |
| minBathrooms | number | Minimum bathrooms (alias: bathrooms) |
| minPrice | number | Minimum monthly rent USD |
| maxPrice | number | Maximum monthly rent USD |
| minSqft | number | Minimum square footage |
| maxSqft | number | Maximum square footage |
| propertyType | string | Single Family, Condo, Townhouse, Manufactured, Multi-Family, Apartment |
| daysOld | number | Listings added within N days |
| status | string | Active (default) or Inactive |

### Pagination

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | number | 25 | Max results (1-500) |
| offset | number | 0 | Skip this many results |

### Example

```bash
curl -X POST https://stableestate.dev/api/apartments/search \
  -H "Content-Type: application/json" \
  -d '{"location": "Brooklyn, NY", "maxPrice": 3000, "minBedrooms": 1}'
```

---

## Property Records Search — /api/properties/search

Search property records with full attributes, tax assessments, ownership info, and transaction history.

### Parameters

Same location parameters as rental search, plus:

| Parameter | Type | Description |
|-----------|------|-------------|
| propertyType | string | Single Family, Condo, Townhouse, Manufactured, Multi-Family, Apartment, Land |
| bedrooms | string | Count or range (e.g. "3", "2-4") |
| bathrooms | string | Count or range |
| squareFootage | string | Sq ft range (e.g. "1000-2000") |
| lotSize | string | Lot size range in sq ft |
| yearBuilt | string | Year or range (e.g. "2000-2024") |

### Example

```bash
curl -X POST https://stableestate.dev/api/properties/search \
  -H "Content-Type: application/json" \
  -d '{"location": "Austin, TX", "propertyType": "Single Family", "yearBuilt": "2000-2024"}'
```

---

## Random Properties — /api/properties/random

Returns random property records from across the US.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | number | 5 | Number of properties (1-500) |

---

## Property by ID — /api/properties/{id}

Get a specific property record by its ID (returned from search results).

```
GET /api/properties/5500-Grand-Lake-Dr,-San-Antonio,-TX-78244
```

---

## Value Estimate — /api/valuations/value

Returns automated property value estimate (AVM) with comparable sales.

| Parameter | Type | Description |
|-----------|------|-------------|
| address | string | Full property address (required unless lat/lng provided) |
| latitude | number | Property latitude |
| longitude | number | Property longitude |
| propertyType | string | Property type |
| bedrooms | number | Number of bedrooms |
| bathrooms | number | Number of bathrooms |
| squareFootage | number | Living area in sq ft |
| maxRadius | number | Max distance for comparables (miles) |
| daysOld | number | Max days since comps were listed |
| compCount | number | Number of comparables (5-25, default 15) |

### Response

```json
{
  "price": 245000,
  "priceRangeLow": 230000,
  "priceRangeHigh": 260000,
  "subjectProperty": { ... },
  "comparables": [{ "formattedAddress": "...", "price": 240000, "distance": 0.1 }]
}
```

### Example

```bash
curl -X POST https://stableestate.dev/api/valuations/value \
  -H "Content-Type: application/json" \
  -d '{"address": "5500 Grand Lake Dr, San Antonio, TX 78244"}'
```

---

## Rent Estimate — /api/valuations/rent

Returns estimated monthly rent with comparable rentals. Same parameters as value estimate.

### Response

```json
{
  "rent": 1850,
  "rentRangeLow": 1700,
  "rentRangeHigh": 2000,
  "subjectProperty": { ... },
  "comparables": [{ "formattedAddress": "...", "price": 1900, "distance": 0.1 }]
}
```

### Example

```bash
curl -X POST https://stableestate.dev/api/valuations/rent \
  -H "Content-Type: application/json" \
  -d '{"address": "5500 Grand Lake Dr, San Antonio, TX 78244"}'
```

---

## Sale Listings Search — /api/sales/search

Search for-sale property listings. Same location and pagination parameters as rental search.

### Additional Filters

| Parameter | Type | Description |
|-----------|------|-------------|
| propertyType | string | Includes "Land" in addition to residential types |
| bedrooms | string | Count or range |
| bathrooms | string | Count or range |
| squareFootage | string | Sq ft range |
| minPrice | number | Minimum listing price USD |
| maxPrice | number | Maximum listing price USD |
| daysOld | string | Days on market filter |

### Example

```bash
curl -X POST https://stableestate.dev/api/sales/search \
  -H "Content-Type: application/json" \
  -d '{"location": "Austin, TX", "maxPrice": 500000, "bedrooms": "3"}'
```

---

## Market Statistics — /api/markets

Get aggregate market statistics and listing trends for a US zip code.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| zipCode | string | (required) | 5-digit US zip code |
| dataType | string | All | All, Sale, or Rental |
| historyRange | number | 12 | Historical data range in months |

### Example

```bash
curl -X POST https://stableestate.dev/api/markets \
  -H "Content-Type: application/json" \
  -d '{"zipCode": "78701", "dataType": "All"}'
```

---

## Notes

- All 50 US states covered
- Responses are fast (~1-2 seconds)
- Data sourced from MLS feeds via RentCast
- 140+ million property records available
- NYC boroughs: use ZIP codes for best results
- All paid endpoints accept both POST (JSON body) and GET (query params)
- Property type "Land" available for property records, value estimates, and sale listings (not rent estimates)