Сначала цена, потом покупка с max_price_trx
Подключённое приложение обязано передавать max_price_trx в buy_energy и buy_bandwidth. Без него вызов завершается ошибкой MAX_PRICE_REQUIRED — суточному лимиту нужно знать, сколько вызов может стоить максимум.
- Вызовите
quote_energy(илиquote_bandwidth) с объёмом и длительностью. - Покажите пользователю
total_trxиз котировки. - Вызовите
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 API, см. Ошибки.
Истёкший или отозванный токен получает HTTP
401 с WWW-Authenticate: Bearer ... error="invalid_token" на сам запрос /mcp; MCP-клиенты тогда обновляют токен или просят пользователя войти снова.