Skip to main content

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.
  1. Call quote_energy (or quote_bandwidth) with the volume and duration.
  2. Show the user total_trx from the quote.
  3. Call buy_energy with the same volume and duration and max_price_trx = the quote’s total_trx.
If the price moves above 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 take idempotency_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_trx plus 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.
A call that does not fit fails with 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 with isError: true:
Over REST the same code comes in the standard error format. 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.