API для ШІ-агентів

HTTP-ендпоінти для ШІ-агентів — оплата за виклик USDC на Base

Будь-який ШІ-агент, який працює з HTTP, може використовувати калькулятор утеплення Uteplennya напряму, без браузера. Платні ендпоінти використовують відкритий протокол x402 — агент надсилає запит, отримує відповідь 402 Payment Required з деталями оплати USDC, сплачує $0.001 на Base mainnet і повторює запит для отримання результатів. Безкоштовні ендпоінти не потребують оплати.

Ендпоінти

Метод Шлях Вартість Опис
GET /api/v1 безкоштовно Схема API, список ендпоінтів та поточна конфігурація оплати
GET /api/v1/materials безкоштовно Повний каталог матеріалів — 14 типів утеплювачів + 21 стіновий матеріал з коефіцієнтами λ
GET /api/v1/climate/{region} $0.001 USDC Дані опалювального сезону (середньомісячні температури та дні). Підтримується: kyiv
POST /api/v1/calculate $0.001 USDC Повний розрахунок утеплення — економія енергії, загальна вартість, термін окупності для товщин 20–200 мм

Як працює оплата x402

1
Агент надсилає звичайний запит

Спеціальні заголовки при першому виклику не потрібні.

2
Сервер відповідає 402 Payment Required

Відповідь містить заголовок PAYMENT-REQUIRED з base64-кодованим JSON-об'єктом із сумою, адресою контракту USDC на Base mainnet, гаманцем отримувача та URL-адресою фасилітатора Coinbase x402.

3
Агент оплачує і повторює запит

Агент (або його x402 SDK) підписує USDC-транзакцію transferWithAuthorization (EIP-3009) і повторює запит із заголовком PAYMENT-SIGNATURE, що містить підтвердження оплати.

4
Сервер перевіряє та відповідає

Оплата перевіряється через фасилітатор Coinbase. Результати повертаються миттєво.

Приклад — ознайомлення з API (безкоштовно)

curl https://uteplennya.com/api/v1

Приклад — запуск розрахунку

Тіло запиту для POST /api/v1/calculate:

{
  "wall_area_m2": 120,
  "indoor_temperature": 20,
  "heating_efficiency": 0.9,
  "energy_tariff_uah_kwh": 4.32,
  "wall_layers": [
    { "material_name": "Brick", "thickness": 0.38, "lambda_value": 0.7 }
  ],
  "insulation_material": "mineral_wool"
}

Доступні значення для insulation_material: mineral_wool, eps, xps, polyurethane. За бажанням додайте climate_data (масив {month, temperature, days}) — за замовчуванням використовуються дані Києва.

Відповідь (після оплати)

{
  "success": true,
  "input": {
    "wall_area_m2": 120,
    "indoor_temperature_c": 20,
    "insulation_material": "Mineral Wool",
    "energy_tariff_uah_kwh": 4.32
  },
  "results": [
    { "thickness_mm": 20,  "energy_saved_kwh": 4741,  "money_saved_uah": 22757, "total_cost_uah": 45000, "payback_years": 1.98 },
    { "thickness_mm": 40,  "energy_saved_kwh": 7002,  "money_saved_uah": 33610, "total_cost_uah": 48000, "payback_years": 1.43 },
    { "thickness_mm": 100, "energy_saved_kwh": 9809,  "money_saved_uah": 47083, "total_cost_uah": 57000, "payback_years": 1.21 },
    ...
  ],
  "optimal_thickness": { "thickness_mm": 100, "payback_years": 1.21, ... },
  "recommendation": "100mm gives the best payback at 1.21 years."
}

SDK для агентів

x402-сумісні SDK автоматично обробляють цикл оплати (оплата → повтор). Використовуйте їх для інтеграції у вашого агента:

Валюта оплати: USDC на Base mainnet (chain ID 8453). Фасилітатор: https://x402.org/facilitator.