Перейти к основному содержанию

Сначала цена, потом покупка с max_price_trx

Подключённое приложение обязано передавать max_price_trx в buy_energy и buy_bandwidth. Без него вызов завершается ошибкой MAX_PRICE_REQUIRED — суточному лимиту нужно знать, сколько вызов может стоить максимум.
  1. Вызовите quote_energy (или quote_bandwidth) с объёмом и длительностью.
  2. Покажите пользователю total_trx из котировки.
  3. Вызовите buy_energy с теми же объёмом и длительностью и max_price_trx = total_trx из котировки.
Если цена поднимется выше max_price_trx, покупка отклоняется с PRICE_CHANGED и ничего не списывается. Запросите цену снова и спросите пользователя. Для API-ключа max_price_trx необязателен, но мы рекомендуем его по той же причине.

Ключи идемпотентности

Инструменты, которые что-то создают, принимают idempotency_key — заголовок Idempotency-Key своего маршрута. Генерируйте новый UUID для каждого нового действия и используйте его повторно, когда повторяете то же действие после таймаута или потерянного ответа: сервер вернёт первый результат, а не спишет снова. Ключ живёт 24 часа, его длина — не больше 64 символов. Тот же ключ с другим запросом отклоняется с IDEMPOTENCY_KEY_REUSED; ключ, чей первый запрос ещё выполняется, отвечает IDEMPOTENT_REQUEST_IN_PROGRESS — подождите и повторите с тем же ключом.

Суточный лимит расходов

Каждое подключение может потратить заданную сумму за любые 24 часа — 100 TRX, если пользователь не выбрал другую сумму на экране согласия или в разделе Подключённые приложения. Снять лимит может только владелец аккаунта.
  • Перед вызовом, который тратит деньги, сервер резервирует максимум, который он может стоить: max_price_trx плюс активация нового адреса для покупок, цена для Smart Mode, пакетов, активаций и тарифов Node API, сумма для стейка.
  • После вызова резерв превращается в реальную сумму или снимается, если ничего не списано. Если исход неизвестен (таймаут), резерв остаётся на 24 часа — при сомнении лимит выбирает отказ.
  • Списания, которые идут сами (recurring), в лимит не входят.
  • Раздел Подключённые приложения в личном кабинете показывает, сколько каждое приложение потратило за последние 24 часа.
Вызов, который не помещается в лимит, завершается ошибкой AGENT_SPEND_CAP:
Повтор покупки с потерянным ответом снова резервирует её сумму. Рядом с лимитом проверьте list_orders перед повтором: первый вызов мог пройти.

Источник заказа

Заказы, созданные подключённым приложением, содержат "source": "agent" — в get_order, list_orders и в вебхуке order.updated. Заказы, созданные с API-ключом, содержат "source": "api".

Коды ошибок

По MCP ошибка приходит как результат инструмента с isError: true:
По REST тот же код приходит в стандартном формате ошибок. Все остальные коды — коды REST API, см. Ошибки. Истёкший или отозванный токен получает HTTP 401 с WWW-Authenticate: Bearer ... error="invalid_token" на сам запрос /mcp; MCP-клиенты тогда обновляют токен или просят пользователя войти снова.