# SolarPulse — Full API Documentation

### GET /v1/estimate
- Price: $0.10 (100000 atomic USDC)
- Rooftop solar estimate for a US address: system size, monthly and annual production (NASA POWER), utility rate (EIA-861 2024), installed cost (LBNL Tracking the Sun), payback, 25-year savings and the 2026 federal credit status.
- Params: address, or lat + lon; optional monthly_kwh (50-10000) or monthly_bill (10-3000 USD), system_kw (1-25), tilt (0-60, default 20)

### GET /v1/irradiance
- Price: $0.10 (100000 atomic USDC)
- Solar resource for a US location: monthly and annual irradiance (horizontal and tilted), optimal tilt, air temperature and PV yield per kW, from NASA POWER 2001-2020 climatology.
- Params: lat + lon, or address; optional tilt (0-60, default 20)

### GET /v1/rates
- Price: $0.10 (100000 atomic USDC)
- Residential electricity price, typical usage and bill for a US ZIP, address or point: utilities serving it (retail service territories) with EIA-861 2024 average rates, state average and 10-year trend.
- Params: zip (5 digits), address, or lat + lon

### GET /tryit
- Free. A static, real sample estimate for 200 W Washington St, Phoenix, AZ 85003 (generated 2026-10-01).

### POST /v1/lead
- Free. JSON {address, email, name?, phone?}: records an installer quote request.

## PV model
kWh = plane-of-array irradiance x days x temperature factor x (1 - 14.08% system losses) x 96% inverter efficiency x PVWatts calibration (1.060). Cell temperature = daytime air temperature + (NOCT 49C - 20)/800 x 600 W/m2; temperature coefficient -0.37%/C. Equator-facing (south) array; shading not modeled.

## Data sources
- US Census Geocoder (TIGER/Line) and TIGERweb 2020 ZIP Code Tabulation Areas: address, point or ZIP -> location, county, state
- NASA POWER climatology 2001-2020 (CERES SYN1deg, MERRA-2; POWER data is also on the Registry of Open Data on AWS): monthly irradiance on tilted surfaces, air temperature
- Electric Retail Service Territories (HIFLD/ORNL): utilities serving the point, by EIA utility id
- EIA Form 861 2024 (final) via PUDL on the Registry of Open Data on AWS: residential price, usage and customers by utility; state averages and 2014-2024 trend
- LBNL Tracking the Sun (2024 edition) via OEDI on the Registry of Open Data on AWS: median installed price per watt by state (2023 installs)

## Limits
- Production is modeled (PVWatts-style losses on ~1-degree NASA POWER satellite climatology): typically within +/-10% for an unshaded, equator-facing roof. Shading, roof azimuth and local weather are not modeled.
- Rates are utility average revenue per kWh (fixed charges included), not your tariff. Savings assume every solar kWh offsets a purchased kWh (full net metering); under net billing (for example California NEM 3.0) exported kWh earn less.
- Federal: the Section 25D homeowner credit ended for expenditures after December 31, 2025, so owner-purchased systems installed in 2026 get no federal credit. State and utility incentives are not included.
- Installed prices are 2023 medians, the latest complete year in Tracking the Sun; 2026 quotes may differ. States with fewer than 100 sampled systems use the national median.
- Not tax, legal or financial advice.

## Errors (never charged)
- 400 bad or missing parameters (checked before payment)
- 404 location not found, or no EIA rate data for it
- 503 a public source is temporarily unavailable

## Authentication
1. x402: call without payment, read the 402 (body or PAYMENT-REQUIRED header), sign, retry with PAYMENT-SIGNATURE or X-PAYMENT.
2. API key: Authorization: Bearer sp_live_YOUR_KEY (buy at https://solarpulse.waltsoft.net)

## Provider
Waltsoft · https://waltsoft.net