История изменений

История изменений контракта API (openapi.yaml), начиная с самых свежих. Все изменения ниже аддитивны и обратно совместимы, если не указано иное; существующие коды ошибок не перенумеровывались.

2026-09-26 — Выпуск API-ключей до первого депозита

• Метод POST /v1/api-keys теперь работает на аккаунтах в статусе unfunded: вы можете зарегистрироваться, сразу выпустить ключ, получить адрес депозита через GET /v1/deposit-addresses и пополнять баланс автоматически. Оформление заказов по-прежнему требует положительного баланса (4001 insufficient_funds).
• Код ошибки 3016 account_unfunded больше не возвращается ни одним эндпоинтом. Номер остается зарезервированным.

2026-09-25 — Публичный доступ к ресурсам адресов

• Эндпоинт GET /v1/resources/{address} больше не требует авторизации. Анонимный вызов тарифицируется по лимитам IP и возвращает our_active_orders: []; подписанный вызов полностью проверяется и возвращает список активных заказов данного аккаунта.
• Разрешение prices.read теперь требуется только для POST /v1/estimate/transfer.

2026-09-25 — Полное расписание периодов суток в GET /v1/prices

• Модель PriceTable получила массив schedule[]: id, label, start_utc_minute, end_utc_minute, factor_bps и стоимость 1 часа энергии price_sun_per_unit для каждого интервала дня, что позволяет клиенту отрисовать полную карту цен за один запрос.
• Поле period формируется из этой же таблицы. Обновлены идентификаторы периодов: drop, off_peak, ramp_9, ramp_11, ramp_12, peak, peak_late. Перебирайте расписание программно; не зашивайте имена периодов в код.

2026-09-19 — Публичные цены и расчет стоимости

• Запросы GET /v1/prices и GET /v1/estimate доступны без авторизации. Анонимные запросы работают в рамках лимитов на IP; подписанные запросы верифицируются и используют лимиты ключа.
• Подписанный запрос GET /v1/estimate учитывает индивидуальные условия аккаунта (корпоративные клиенты видят свои контрактные цены); анонимный запрос возвращает стандартную розничную цену.

2026-09-19 — Формат ключей, лимиты и сессии кабинета

• Формат API-ключей: ak_live_ + 24 случайных байта (base64url) для ID и sk_live_ + 256 бит для секрета; префиксы ak_test_ / sk_test_ в тестнете Nile. Префикс явно указывает на окружение, отправка ключа на чужой хост отклоняется с ошибкой 1012 key_environment_mismatch до обращения к базе. Ранее созданные ключи сохраняют действие.
• Поле label в POST /v1/api-keys стало опциональным со значением по умолчанию Key N. Правило для scopes неизменно: обязательное поле без дефолтных значений.
• Лимит активных ключей: GET /v1/api-keys возвращает поля limit и used; при превышении создание ключа возвращает новую ошибку 3017 api_key_limit_reached.
• Добавлены поля ApiKey.last_used_ip и last_used_at.
• Сессии кабинета: методы POST, GET, DELETE /v1/session и POST /v1/session/refresh с авторизацией по httpOnly-кукам и защитой через X-CSRF-Token (1013 session_expired, 1014 csrf_token_invalid).
• PATCH /v1/account позволяет задать отображаемое имя display_name.

2026-09-11 — Единая стейт-машина и регистрация по подписи кошелька

• Состояния заказов: created → paid → allocating → delegated → confirmed → active → expired | reclaimed, с терминальными ветками ошибок failed и refunded.
• Объект Order получил поля partial и delivered_amount: частичное исполнение — это атрибут подтвержденного заказа, а не отдельный статус.
• Новое событие вебхука order.refunded. Событие order.confirmed содержит поля partial, delivered_amount и refunded_amount_sun.
• Прямая отмена одиночных заказов в v1 не поддерживается; код 3002 order_not_cancellable относится к POST /v1/batches/{id}/cancel.
• Регистрация через проверку владения адресом: POST /v1/accounts/challenge, POST /v1/accounts/challenge/verify (15-минутный bootstrap-токен), POST /v1/accounts, GET /v1/accounts/deposit-address.
• Разрешения (Scopes): единый словарь area.action (ApiKeyScope). Обязателен при создании ключа.
• В раздел Окружения добавлено подробное описание отличий Nile от Mainnet.