# IVPools — AI Engineering API

> AI-native engineering platform for swimming pools, PV systems, saunas, and irrigation.
> AI agents can access structured quotes, real-time pricing, real inventory, and engineering optimization
> via paid API endpoints + MCP server. Primary billing via Stripe, secondary via USDC on Base L2.

## Quick Start for AI Agents

1. Get an API key: POST /api/agent-keys
   Body: {"agent_type":"openai","agent_name":"my-agent","email":"you@example.com","plan":"free"}
   Returns: {"api_key":"av_live_xxx"}
   NOTE: API key is shown only once — store securely.

2. Make a price lookup (cheapest):
   GET /api/v1/price?category=pump&volume=20
   Header: Authorization: Bearer av_live_xxx
   Cost: $0.001 USD

3. Generate a full engineering quote:
   POST /api/v1/quote
   Header: Authorization: Bearer av_live_xxx
   Header: Idempotency-Key: <uuid> (optional, for safe retries)
   Body: {"category":"pool","type":"overflow_pool","length":8,"width":4,"depth":1.5}
   Cost: $0.005 USD
   Response includes confidence.status ("preliminary"|"final"|"requires_review") — if requires_review, human engineer verification needed.

4. Optimize within budget + constraints (most powerful):
   POST /api/v1/optimize
   Body: {"type":"overflow_pool","length":8,"width":4,"depth":1.5,"budget_max":15000,"constraints":{"min_flow_m3h":18,"min_heating_kw":7,"require_cover":true},"preferences":{"prioritize":"cost"}}
   Cost: $0.020 USD
   Returns multiple candidate configurations ranked by score + recommended winner with reasoning.

## API Endpoints

### Public REST API (require API key in header)

- POST /api/v1/price — $0.001 — Price + specs + real availability (14 categories)
- POST /api/v1/products — $0.002 — List products in category with stock levels
- POST /api/v1/quote — $0.005 — Full engineering quote with BOM via unified AQUA VITAE engine
- POST /api/v1/repair — $0.004 — Pool problem diagnosis from natural language
- POST /api/v1/availability — $0.001 — Real inventory check (stock qty + lead time + warehouse)
- POST /api/v1/optimize — $0.020 — Engineering Optimization API (best config within budget)

### MCP Server (Streamable HTTP, JSON-RPC 2.0)

- POST /api/mcp — MCP endpoint, protocol version 2025-03-26
  - Method: initialize — returns server info + creates session
  - Method: tools/list — 7 tools with cost annotations
  - Method: tools/call — invokes tool (goes through full withMetering pipeline)
  - Method: ping — keep session alive (1 hour TTL)
- GET /api/mcp — server info (no auth, public discovery)

Tools (all metered):
- ivpools_get_price — $0.001
- ivpools_list_products — $0.002
- ivpools_create_quote — $0.005
- ivpools_diagnose_repair — $0.004
- ivpools_calculate_pool — $0.001
- ivpools_check_availability — $0.001
- ivpools_optimize_solution — $0.020

### Self-Service (no auth for signup)

- POST /api/agent-keys — Create API key (rate-limited: 5/IP/hour, 3/email)
- GET /api/agent-keys — View key + usage stats (header auth only, NOT ?key=)
- DELETE /api/agent-keys — Revoke key (header auth only)

### Billing

- GET /api/billing/plans — Public pricing plans list
- POST /api/billing/stripe/create-checkout — Stripe Checkout (primary)
- POST /api/billing/stripe/webhook — Stripe webhook receiver
- POST /api/wallet/charge — USDC verification (secondary, MetaMask on Base L2)

### Admin

- GET /api/admin/agent-commerce?password=ADMIN_PASSWORD — Dashboard data
- POST /api/admin/agent-commerce — Admin actions (revoke_key, add_credit, etc.)

### Discovery (no auth required)

- GET /llms.txt — This file
- GET /.well-known/ai-plugin.json — ChatGPT plugin manifest
- GET /api/openapi.json — OpenAPI 3.0 spec

## Authentication

**Headers only — query param auth (?key=) is DISABLED for security.**

```
Authorization: Bearer av_live_xxx
# OR
X-API-Key: av_live_xxx
```

Why? Query params are logged in URLs, browser history, referrer, analytics — exposing the key.

## Idempotency (for safe retries)

For POST /api/v1/quote and POST /api/v1/optimize:

```
Idempotency-Key: <uuid>
```

Same key returns same response — **no double charge**. AI agents can safely retry on network failures.

## Rate Limits

| Plan | Per minute | Per day |
|------|-----------|---------|
| FREE | 10 | 100 |
| DEVELOPER | 60 | 5,000 |
| AGENT (PAYG) | 120 | 50,000 |
| ENTERPRISE | 600 | 500,000 |

Headers returned on every request:
- X-Request-Id — unique ID for support
- X-RateLimit-Limit — max per minute
- X-RateLimit-Remaining — remaining this minute
- X-RateLimit-Reset — Unix timestamp when limit resets
- X-Cost-USD — cost of this request (PAYG plans)
- X-API-Version — "v1"
- X-Processing-Time — server processing time in ms

## Pricing Plans

| Plan | Monthly | Price | Quote | Repair | MCP | Optimize |
|------|---------|-------|-------|--------|-----|----------|
| FREE | $0 | 100 | 10 | 5 | 50 | 2 |
| DEVELOPER | $10 | 10k | 1k | 500 | 5k | 100 |
| AGENT (PAYG) | $0 + per call | $0.001 | $0.005 | $0.004 | $0.002 | $0.020 |
| ENTERPRISE | $999 | 1M | 100k | 50k | 500k | 10k |

PAYG: $0 = monthly fee, pay per call. Stripe tops up wallet, calls deduct from balance.

## Engineering Confidence

Every quote response includes `confidence` field:

```json
{
  "confidence": {
    "status": "preliminary",
    "score": 0.92,
    "requires_human_engineer": false,
    "reason": "Standard pool configuration — auto-generated quote"
  }
}
```

Status values:
- `preliminary` — auto-generated, valid for planning
- `final` — engineer-verified
- `requires_review` — pool area > 60 m² or depth > 2.0m — human engineer must verify structural calculations

AI agents MUST NOT present `preliminary` or `requires_review` quotes as final engineering documents.

## Webhooks

Configure via POST /api/agent-keys (webhookUrl field). Events fired:

- quote.created — when a quote is generated
- repair_diagnosis.completed — when diagnosis returns
- optimize_solution.completed — when optimization finishes
- wallet.low — when PAYG spending approaches limit
- price_lookup.completed, list_products.completed, etc.

Webhook payload:
```json
{
  "event": "quote.created",
  "timestamp": "2026-08-25T10:30:00.000Z",
  "data": { "quote_id": "Q-2026-...", "total_with_vat": 28450, ... }
}
```

Headers:
- X-Webhook-Event — event name
- X-Webhook-Delivery — unique delivery ID
- X-IVPools-Signature — HMAC signature (verify with your API key prefix)

## Data Freshness

- Quote data: live calculation via AQUA VITAE engine (always current)
- Product prices: live from DB (updated via admin panel)
- Inventory: live from DB stock_qty field
- Each response includes `updated_at` timestamp

## Coverage

- Geographic: Bulgaria (all regions — Burgas, Sofia, Plovdiv, Varna)
- Languages: Bulgarian, English (UI), JSON (API responses)
- Currency: EUR (BGN available on request)
- Time zone: EET (UTC+2) / EEST (UTC+3)

## Links

- Main website: https://ivpools.eu
- OpenAPI spec: https://ivpools.eu/api/openapi.json
- MCP server info: https://ivpools.eu/api/mcp
- Pricing plans: https://ivpools.eu/api/billing/plans
- Status page: https://ivpools.eu/status (coming soon)
- Contact: ivpools@abv.bg

## Optional

- Custom integrations for construction companies and B2B platforms
- Volume discounts for >10k quotes/month
- White-label licensing available
- Enterprise SLA on request