# Pequi
> AI-powered real estate platform for Ibagué, Bogotá, and Colombia
> https://xpequi.xyz

## Bogotá Data Sources
- Neighborhoods: 212 barrios, 20 localidades, 4 zones (Norte/Centro/Occidente/Sur)
- UPZ Boundaries: 117 UPZs with bbox, land use, height limits, TransMilenio coverage
- Cadastral Valuation: IGAC reference value/m² by localidad+estrato (2025-2026)
- Mortgage Rates: 34 products from 10 banks (Superfinanciera data, April 2026)

## Important Pages

- Home: https://xpequi.xyz/
- Property Search: https://xpequi.xyz/busca — Map + list, filters by city, type, price
- AI Chat: https://xpequi.xyz/ai — Conversational agent with legal + market tools
- Pricing: https://xpequi.xyz/precios — FREE, PREPAGO (c402), AGENTE API, CONJUNTO API
- Developer Portal: https://xpequi.xyz/developers — API docs, keys, monitoring, c402 section
- API Reference: https://xpequi.xyz/developers/api-ref — Swagger UI playground
- Agents Guide: https://xpequi.xyz/developers/agents — MCP setup, structured errors
- Blog: https://xpequi.xyz/blog — Real estate guides (arriendo, Ley 820, barrios, c402)
- c402 Protocol: https://xpequi.xyz/blog/c402-pagos-ia-colombia — HTTP 402 monetization
- c402 Spec: https://xpequi.xyz/blog/c402-protocol-open-standard — Open standard spec published CC-BY-SA 4.0
- About: https://xpequi.xyz/about
- Dashboard: https://xpequi.xyz/dashboard (auth required)
- Contracts: https://xpequi.xyz/contracts (auth required)
- Legal: https://xpequi.xyz/legal — Terms, privacy, Ley 820, Ley 1581, Decreto 0368
- Docs: https://xpequi.xyz/docs

## Public API

### SDK & Open Source
- GitHub: https://github.com/MCPVOT/xpequi-api — SDK + MCP server + full SYSTEM.md (366 lines)
- TypeScript SDK: `@MCPVOT/api-client` (v0.3.1) — 31 methods, PequiApiError, full types, c402 support
- Python SDK: `pip install pequi-api-client` — 16 sub-APIs, zero external deps, PequiApiError
- MCP Server: `npx @MCPVOT/mcp-server` — 7 tools for Claude Desktop, Cursor, Copilot, ChatGPT
- README: 536 lines, 29 endpoints across 8 categories, Quick Start, Error Handling, c402 protocol

### Agent-Friendly Features
- All errors return structured JSON: `{ error, code, recoverable, suggestedAction, retryAfter, requestId }`
- Error codes: INVALID_API_KEY, RATE_LIMIT_EXCEEDED, PAYMENT_REQUIRED, QUOTA_EXCEEDED, BAD_REQUEST, INTERNAL_ERROR, SERVICE_UNAVAILABLE, NOT_FOUND, INSUFFICIENT_SCOPE
- c402 response status: `'pay'` = HTTP 402 payment challenge (FREE tier exceeded), `'blocked'` = rate limited (paid tier exceeded, no payment needed)
- Agents should check `recoverable` to decide whether to retry; use `retryAfter` for backoff
- HTTP 402 Payment Required with `X-402-Challenge` header for exceeded FREE tier limits
- Prepaid credits and monthly subscriptions available (AGENTE API $30K/mo, CONJUNTO API $150K/mo)
- MCP server supports 7 tools: search_properties, get_barrios, get_benchmarks, geocode, get_uvr, get_ipc, calculate_rent_increase

### Monetization (c402 Protocol)
- **FREE tier:** 30 req/min, 150/day — no API key needed for GET endpoints
- **PREPAGO (c402):** Pay-as-you-go credits via Wompi (PSE/Nequi/card). Packs: 50 ($2,500 COP), 200 ($8,000), 1,000 ($30,000). Never expire.
- **AGENTE API:** $30K COP/mo — 100 req/min, 1,000/day. Monthly via Wompi.
- **CONJUNTO API:** $150K COP/mo — 300 req/min, 5,000/day. Monthly via Wompi.
- **ENTERPRISE:** Custom pricing for banks, fintechs, govtech.
- HTTP 402 flow: Rate limited FREE tier → X-402-Challenge with nonce + Wompi checkout URL → payment → credits auto-added → retry with X-402-Payment-Id

### REST Endpoints (v1)
- `GET /api/v1/properties` — Search properties with filters (city, tipo, precio, barrio, estrato, cuartos, banos, operacion)
- `GET /api/v1/barrios?city=ibague` — 64 neighborhoods with estrato and GIS coords (Ibagué)
- `GET /api/v1/barrios?city=bogota` — 212 neighborhoods across 20 localities (Bogotá)
- `GET /api/v1/benchmarks` — Price per m² benchmarks by barrio, tipo, estrato
- `GET /api/v1/geocode` — Address to lat/lng geocoding
- `GET /api/v1/avm` — Automated Valuation Model (POST)
- `GET /api/v1/uvr` — Current UVR value (daily, from Banco de la República)
- `GET /api/v1/ipc` — Current IPC inflation rate (trailing 12-month)
- `POST /api/v1/rent-increase` — Calculate max legal rent increase under Ley 820/2003
- `POST /api/v1/contracts` — Generate Ley 820 rental contracts
- `GET /api/v1/contracts` — List user contracts
- `POST /api/v1/payments` — Create Wompi payment for subscriptions
- `GET /api/v1/payments/{id}` — Check payment status
- `GET /api/v1/complexes` — List residential complexes
- `GET /api/v1/complexes/{slug}` — Complex details
- `POST /api/v1/visits` — Schedule property visits
- `POST /api/v1/chat` — AI chat with streaming
- `POST /api/v1/upload` — File upload (PDF, images, max 5MB)
- `POST /api/v1/bank-verification` — Verify Colombian bank accounts via Prometeo (Open Finance)
- `GET /api/v1/credits` — Check prepaid credit balance (c402)
- `POST /api/v1/credits/purchase` — Buy prepaid credits via Wompi (PSE/Nequi/card)
- `POST /api/v1/subscriptions/api-checkout` — Buy monthly API tier (AGENTE $30K or CONJUNTO $150K)
- `GET /api/v1/monitoring/usage` — Hourly usage, credits remaining, tier
- `GET /api/v1/monitoring/latency` — P50/P95/P99 latency
- `GET /api/v1/monitoring/errors` — 4xx/5xx errors per endpoint
- `GET /api/v1/monitoring/uptime` — Availability statistics
- `POST /api/v1/webhooks/endpoints` — Create webhook endpoints
- `GET /api/v1/webhooks/endpoints` — List webhooks

### AI Agent Tools (via /api/chat)
The Pequi AI agent has 20+ tools including:
- Property search, analysis, neighborhood info, market trends
- Contract generation, analysis, PDF download, digital signatures
- Legal database search (Ley 820, Ley 675, Ley 142)
- UVR and IPC lookup for rent adjustments
- Bank account verification (Prometeo)
- Complex metrics, subscription management
- Investment recommendations

## Stack

Next.js 16.2.6 · React 19 · TypeScript · Prisma 6 · PostgreSQL (Neon)
Clerk auth · DeepSeek V4 Flash + Ring-2.6-1T + Groq + OpenRouter · Wompi payments
c402 Protocol · Prometeo Open Finance · BanRep MCP · Tailwind CSS v4