Quote, then buy with max_price_trx
A connected app must pass max_price_trx to buy_energy and buy_bandwidth. Without it the call fails with MAX_PRICE_REQUIRED — the daily cap needs to know the most a call can cost.
- Call
quote_energy(orquote_bandwidth) with the volume and duration. - Show the user
total_trxfrom the quote. - Call
buy_energywith the same volume and duration andmax_price_trx= the quote’stotal_trx.
max_price_trx, the purchase is refused with PRICE_CHANGED and nothing is charged. Quote again and ask the user.
For an API key max_price_trx is optional, but we recommend it for the same reason.
Idempotency keys
Tools that create something takeidempotency_key — the Idempotency-Key header of their route. Generate a new UUID for every new action and reuse it when you retry the same action after a timeout or a lost answer: the server returns the first result instead of charging again. A key lives 24 hours and is at most 64 characters.
The same key with a different request is refused with
IDEMPOTENCY_KEY_REUSED; a key whose first request is still running answers IDEMPOTENT_REQUEST_IN_PROGRESS — wait and retry with the same key.
The daily spending cap
Each connection may spend a set amount in any 24 hours — 100 TRX unless the user chose another amount on the consent screen or in Connected apps. Only the account owner can remove the cap.- Before a call that spends, the server reserves the most it can cost:
max_price_trxplus the activation of a new address for purchases, the price for Smart Mode, packages, activations and Node API plans, the amount for a stake. - After the call the reserve becomes the real amount, or is released if nothing was charged. If the outcome is unknown (a timeout), the reserve stays for 24 hours — the cap errs on the side of refusing.
- Spending that runs by itself (
recurring) is outside the cap. - Connected apps in the dashboard shows what each app spent in the last 24 hours.
AGENT_SPEND_CAP:
A retry of a lost purchase reserves its amount again. Near the cap, check
list_orders before retrying: the first call may have gone through.Order source
Orders placed by a connected app carry"source": "agent" — in get_order, list_orders and the order.updated webhook. Orders placed with an API key carry "source": "api".
Error codes
Over MCP an error comes as a tool result withisError: true:
All other codes are those of the REST API — see Errors.
An expired or revoked token gets HTTP
401 with WWW-Authenticate: Bearer ... error="invalid_token" on the /mcp request itself; MCP clients then refresh the token or ask the user to sign in again.