---
name: idx-listings-install
description: Add MLS/IDX real-estate listings and lead capture to a website with GalaxyIDX, the compliant way. Use when asked to "add MLS listings", "add IDX", "show my listings on my site", "add a home search", "add listing pages" or "capture buyer leads" on a real-estate agent or brokerage site built with WordPress, Next.js, Astro or any server stack. Covers keys, server-side rendering, MLS attribution, photo rules, Fair Housing, SEO schema and lead email routing.
---

# Install GalaxyIDX (MLS/IDX listings + lead capture)

Docs index: https://docs.galaxyidx.com/llms.txt · API: https://api.galaxyidx.com/v1 · MCP: https://mcp.galaxyidx.com/mcp

## 0. Before writing code

1. Find the framework: `wp-config.php` / `wp-content/` = **WordPress**; `next.config.*` = **Next.js**; `astro.config.*` = **Astro**; anything else = **other** (HTTP API).
2. Ask the user for (never invent them):
   - the **secret key** (`sk_live_…` / `sk_test_…`). They set it in the host's environment as `IDX_SECRET_KEY`; you never print, echo, log or commit it.
   - the **site id**, set as `IDX_SITE_ID`.
   - who should receive new-lead emails.
3. If they have no account: have them email support@galaxyidx.com to request an account (early access is by request). Tell them plainly that their **broker** must sign the MLS authorization before listings appear (https://docs.galaxyidx.com/docs/mls-licensing.md). You cannot do that step. Price: $10/month per site plus the MLS fee at cost.
4. If the MCP server is connected, call `install_instructions(framework)` and use its `your_sites` and steps.

## 1. Install by framework

**WordPress**
1. Install and activate the `galaxyidx` plugin (zip from the dashboard).
2. Have the user paste the secret key and site id into the plugin settings. Do not write the key into any PHP, theme or JS file.
3. Do not hand-build listing pages or add a second listings plugin.

**Next.js (App Router) / Astro**
1. Prefer the MCP tool `create_search_page(framework, site_id)`; write the returned `files` as given. Without MCP, follow https://docs.galaxyidx.com/docs/quickstart-nextjs-astro.md.
2. Keep the API helper server-only. Never use `NEXT_PUBLIC_` / `PUBLIC_` for the key.
3. Revalidate at most every hour (`export const revalidate = 3600`). Astro: on-demand rendering (`prerender = false` + an SSR adapter), or rebuild at least every 12 hours.
4. Add the lead route (`/api/idx-lead`) that forwards to `POST /v1/leads` with the secret key and `X-Forwarded-For`.
5. Optional: `create_area_page(framework, site_id, area_slug)` for each area the site covers.

**Other stacks**
1. Call `https://api.galaxyidx.com/v1` from the server with `Authorization: Bearer $` + `IDX_SECRET_KEY`. Spec: https://docs.galaxyidx.com/openapi.json.
2. Build `/homes/` (search), `/homes/<address-slug>--<listing_key>/` (detail) and a server-side lead forwarder.

## 2. Lead emails

Call `set_lead_email(email_to=[…], site_id=…)` for one site, or `set_lead_email(email_to=[…], account_default=true)` for the account default (MCP), or `PUT /v1/lead-routes` with the addresses the user gave you. Confirm them with the user before saving. The tool keeps CRM and webhook delivery; a raw PUT replaces the whole route, so send them back yourself.

## 3. Rules you must keep (the MLS can cut off the feed otherwise)

- Server-render listing HTML on the customer's own domain. No iframe, no client-only widget, no subdomain.
- Every listing display (cards too): listing firm (normal text size or larger), MLS name + logo, last-updated date, disclaimer, firm phone/email when present. All of it is in `listing.compliance`.
- Photos: `object-fit: contain` on a neutral background. Never `cover`, never crop, never text/badges/watermarks on a photo.
- Missing facts render as `—`. Never estimate, rewrite or invent listing facts, alt text or descriptions.
- `address.display === false`: no street, unit, map or coordinates anywhere (page, schema, social card).
- On 404 from the API, the listing is gone: return 404 at once; never serve a cached copy.
- `is_home === false`: link/redirect to `home_site.url`; one indexed page per listing.
- Fair Housing: objective filters only (price, beds, status, geography). No "safe", "family-friendly", school-quality, crime or demographic wording, filters or AI answers; link to official sources instead.
- Lead forms: name + email, phone optional, no SMS consent box, email opt-in unchecked by default, a hidden honeypot field.

## 4. SEO

JSON-LD `RealEstateListing` + `Offer` + `PostalAddress` (+ `GeoCoordinates` only when the address is shown) + `BreadcrumbList`, from listing facts only; canonical = `home_site.url`; separate sitemaps for listings and area pages. Details: https://docs.galaxyidx.com/docs/seo.md.

## 5. Verify before you say "done"

- [ ] `curl` a listing page: price, listing firm and `application/ld+json` are in the raw HTML.
- [ ] `grep -r "sk_live_\|sk_test_"` over the repo and the built client bundle finds nothing.
- [ ] Photos are uncropped on a narrow (phone) viewport.
- [ ] A test lead with the user's own email returns 201 and shows up in `list_leads`.
- [ ] Report to the user: site status (`pending` until the MLS approves), where leads go, and anything they still must do (broker authorization, env vars on the host).