# marocain.investments

> AI-graded luxury real-estate intelligence for Morocco. Every listing carries
> transparent, investment-grade scores (window-view, structural, World Cup 2030
> catalyst proximity), an M-Value AVM estimate, ROI projections and agent-claim
> trust signals — built for international investors and local agents.

Coverage: Tangier, Casablanca, Marrakech, Rabat, Agadir, Essaouira, Tetouan, Fes.
Listings are scored by AI (vision: Gemini 2.5 Flash · condition: Gemini 2.5 Flash)
and translated on demand (Claude Haiku 4.5) into FR/ES/DE/PL/AR.

## Agent-callable API (live, no auth)

These are the endpoints an LLM/agent can call today. Full schema: [OpenAPI spec](https://marocain.investments/api/public/openapi.json).

- [Search listings](https://marocain.investments/api/public/listings/search): GET — filter by city, typology, price (USD), rooms, surface, window-view score, WC2030 score, agent availability, bbox, free-text `q`. Returns `items[]`, `total`.
- [Get listing detail](https://marocain.investments/api/public/listings/): GET `/api/public/listings/{id}` — price (USD/MAD), AI scores + methodology + confidence, M-Value AVM, price history, geo, FCR/title trust status, agent contact, source provenance.
- [Semantic search](https://marocain.investments/api/public/semantic-search): GET `?q=...&types=listing,essay&k=8` — conceptual / natural-language vector search (hybrid vector + full-text) across the catalogue AND the authored guides (Foreign Buyer's Playbook, Morocco-vs-Dubai thesis, AI-scoring methodology, residency, city theses). Use for fuzzy / lifestyle / thesis queries that don't map to exact filters. Returns `results[]` with a similarity score. Never returns agent contact details.

MCP server (Claude Desktop / Cursor): `npx @marocain/mcp-server` — exposes `search_listings`, `get_listing`, `get_gin_score`, `get_market`, `listing_derive`, `semantic_search`. Plugin manifest: [/.well-known/ai-plugin.json](https://marocain.investments/.well-known/ai-plugin.json).

## Skills catalog (33)

One-GET machine-readable manifest: [/api/public/skills.json](https://marocain.investments/api/public/skills.json) — returns the full catalog with id, name, endpoint, inputs/outputs, agent bindings (MCP/ACP/AP2/n8n), sample prompts and ROI per skill.

> Agent-callable TODAY = the two GET endpoints under "Agent-callable API" above, plus `POST /api/orders` (services). Endpoints tagged `(planned)` or `(UI only)` are roadmap or authenticated-UI features and are NOT callable by an external agent yet — do not call them. `skills.json` is the authoritative, always-current status.

Distributions: npm `@hei33enberg/luxury-skills`, HuggingFace `hei33enberg/luxury-skills`, MCP `npx @marocain/mcp-server`.

### listings
- [Search Listings](https://marocain.investments/skills/list-listings) — Search AI-graded Moroccan luxury listings by city, typology, price, rooms, surface, window-view score, WC2030 catalyst and agent availability. `GET /api/public/listings/search`
- [Get Listing Detail](https://marocain.investments/skills/get-listing) — Full detail for one listing: price (USD/MAD), AI scores, M-Value AVM, agent contact, FCR status, title verification and source provenance. `GET /api/public/listings/{id}`
- [Submit Buyer Lead](https://marocain.investments/skills/submit-lead) — Submit a qualified buyer enquiry against a listing. Routes to the listing agent and triggers the AI lead-scoring + notification pipeline. `POST /api/orders (product_type=contact)`
- [Add to Watchlist](https://marocain.investments/skills/add-to-watchlist) — Save a listing to the authenticated user's watchlist so they receive price-drop and status-change alerts. `(UI only — authenticated, no public API yet)`
- [Claim Listing (Agent)](https://marocain.investments/skills/claim-listing) — An agent claims representation of a scraped listing, opening a Stripe Pro/Premier subscription that verifies the listing and routes leads to them. `POST /functions/v1/stripe-checkout`

### valuation
- [Compute M-Value (AVM)](https://marocain.investments/skills/compute-m-value) — Comparable-based automated valuation for a listing: estimated fair value in USD/MAD with a confidence band and the comp set it was derived from. `RPC compute_m_value`
- [Price History](https://marocain.investments/skills/price-history) — Time-series of every price change observed on a listing since our crawler first saw it — the basis for price-drop detection. `GET /api/public/listings/{id} (price_history)`
- [Find Comparables](https://marocain.investments/skills/comparables-finder) — Return the most similar listings to a target — same city and typology within a ±5% price window, ranked by surface and AI scores. `GET /api/public/listings/search (price ±5%)`

### scoring
- [Window-View Score](https://marocain.investments/skills/window-view-score) — Multimodal vision score (0–100) detecting what a property actually overlooks — ocean, medina, skyline, garden — with a plain-language explanation. `functions/v1/ai-score-vision`
- [Structural-Quality Score](https://marocain.investments/skills/structural-score) — Construction-era and materials grade (0–100) — a proxy for the renovation capex a buyer will or won't have to spend. `GET /api/public/listings/{id} (structural_score)`
- [WC 2030 Catalyst Score](https://marocain.investments/skills/wc2030-catalyst-score) — Forward-looking score (0–100) measuring proximity to 2030 World Cup infrastructure — host stadiums, the TGV high-speed line and expanded airports. `RPC backfill_listing_scores → wc2030_score`
- [FCR Status Check](https://marocain.investments/skills/fcr-status-check) — Foreign Currency Repatriation eligibility for a listing — whether a clean hard-currency exit path exists for an international buyer. `GET /api/public/listings/{id} (fcr_status)`

### intelligence
- [District Profile](https://marocain.investments/skills/district-profile) — RAG-generated profile of a Moroccan district — median price, supply, infrastructure proximity and the investment thesis, grounded in live listings. `functions/v1/ai-concierge (RAG)`
- [Infrastructure Proximity](https://marocain.investments/skills/infrastructure-proximity) — Distance and travel time from a listing to WC2030 venues, TGV stations, airports, the medina and the coast. `GET /api/public/listings/{id} (geo)`
- [Subscribe to Price-Drop Alerts](https://marocain.investments/skills/price-drop-alerts) — Persist search criteria so the daily cron emails the user when a freshly-listed or price-dropped property matches. `(UI only — authenticated, no public API yet)`
- [Get Market Metrics](https://marocain.investments/skills/get-market) — Median price per m², gross rental yield band, supply count and trend per city × typology. `(planned — use Get Macro Knowledge Facts below: GET /api/public/macro/{scope})`
- [Get Macro Knowledge Facts](https://marocain.investments/skills/get-macro-facts) — Sourced, dated headline metrics about Morocco and its 8 covered cities — demographics, GDP, budget, tax, currency regime, tourism, WC2030 catalysts, heritage, weather. Every fact carries a citable source and period. `GET /api/public/macro/{scope}`
- [Get Listing AI Derive](https://marocain.investments/skills/listing-derive) — Free per-listing AI layer: cover-photo caption, f[ai]nancial-vision narrative (M-Value vs ask + trend), expanded sections (taxes, ownership cost, planned changes) — locale-aware, content-hash cached. `GET /api/public/listing-derive`

### services
- [Request a Service Order](https://marocain.investments/skills/request-service) — Create a service order against a listing — St[ai]ging, refundable reservation, on-site appraiser/visitation, AI commercialization plan, lawyer/financing intake, contact-agent thread. Instant products return a Stripe Checkout URL; request products return a tracked `order_id`. `agent_phone` is never returned. `POST /api/orders`

### finance
- [Foreign-Buyer Mortgage Check](https://marocain.investments/skills/mortgage-foreign-buyer) — Eligibility quick-check across Attijariwafa, Bank of Africa and CIH foreign-buyer mortgage products, with an FCR-compatible application path. `GET /api/public/finance/mortgage (planned)`
- [Sovereign Bond Screener](https://marocain.investments/skills/royal-bonds-screener) — Screen Bons du Trésor Marocains and Sukuk Al-Hassan — yield curve, auction calendar and FCR repatriation pathway for foreign holders. `GET /api/public/bonds (planned)`
- [Casablanca Exchange ETF Screener](https://marocain.investments/skills/mse-etf-screener) — Screen Casablanca Stock Exchange ETFs (MASI20, FTSE CSE Morocco 15) and blue-chip equity profiles with 1/3/5-year return history. `GET /api/public/etfs (planned)`
- [FM6I Fund Shelf](https://marocain.investments/skills/fm6i-fund-shelf) — Browse the Fonds Mohammed VI pour l'Investissement shelf — 14 management companies, ~MAD 19B deployed — as a verified institutional investment layer. `GET /api/public/funds (planned)`

### i18n
- [Translate Listing](https://marocain.investments/skills/translate-listing) — Translate a listing's title and description into any of six locales (EN/FR/ES/DE/PL/AR) with a luxury-grade, cached translation. `functions/v1/ai-translate`

### gov
- [Foreign-Buyer Tax Estimate](https://marocain.investments/skills/tax-estimate-foreign) — Estimate a foreign buyer's Moroccan tax exposure — transfer tax, annual property tax and capital-gains liability — by buyer country and purchase type. `GET /api/public/tax-estimate (planned)`
- [AMMC Broker Compliance](https://marocain.investments/skills/ammc-compliance-check) — Verify whether an agent or agency is registered with the Autorité Marocaine du Marché des Capitaux — a trust signal for cross-border counterparties. `GET /api/public/compliance/ammc (planned)`



## Services (transactable)

Beyond read-only intelligence, agents can transact on a buyer's behalf. Prices are
ALWAYS resolved server-side from the product registry — a client-supplied amount is
rejected. Instant products return a Stripe checkout URL; request products return an
order id with status `requested`. Full schema in the [OpenAPI spec](https://marocain.investments/api/public/openapi.json) (`POST /api/orders`).

- [Place a service order](https://marocain.investments/services): `POST /api/orders` — `product_type` one of `staging` (AI renovation visualizations + BOM + post-reno ROI), `reservation` (refundable 30-day hold), `appraiser` (bank-honored on-site valuation), `visaitation` (on-site photo/video/3D documentation), `commercialization_plan` (AI business-model + ROI), `listing_boost` (seller placement boost) — plus request-only `commercialization`, `lawyer`, `financing`, `contact`. Body: `product_type`, `variant`, `listing_id?`, `buyer_email`, `buyer_name?`, `buyer_phone?`. Returns `{ checkout_url | order_id, status, amount_eur_cents, currency }`.
- Seller AI draft: `POST /api/agent/listings/ai-draft` (agent JWT) — from one photo or a GPS point, drafts a full listing (title, description, gallery, AI vision + condition scores, M-Value AVM). Listing creation is free; St[ai]ging / boost are optional paid add-ons.

Buyer ↔ agent contact stays intermediated through the platform — `agent_phone` is never returned in any payload.

Machine-readable service catalog (schema.org `OfferCatalog`, EUR prices): [/api/public/services.jsonld](https://marocain.investments/api/public/services.jsonld).

## Key pages

- [Services & pricing](https://marocain.investments/services)
- [Interactive split-map](https://marocain.investments/map)
- [Market price indices](https://marocain.investments/market)
- [Investment thesis](https://marocain.investments/investments)
- [Insights](https://marocain.investments/insights)
- [Legal: foreign-buyer tax, residency, FCR](https://marocain.investments/legal)
- [Sitemap](https://marocain.investments/sitemap.xml)

## Notes for AI agents

- Scores labelled `vision-*` are model-generated; `v1.deterministic` is a heuristic fallback for not-yet-vision-scored listings — treat confidence accordingly.
- This is decision-support, not a certified appraisal. Prices in MAD and USD.