TronhexAPI Docs

Energy, Pricing & Orders

This page explains the domain model: Energy, durations, pricing, the order lifecycle, and idempotency.

Energy and durations

A rental is an amount of Energy delegated to a target address for a duration. The allowed durations are fixed (see List durations); the default is 10 minutes, with other common durations of 1 hour, 1 day and 3 days.

Pricing

Prices and balances are always returned as decimal strings in TRX — never floats, and never SUN or other minor units — so no precision is lost (1 TRX = 10^6 SUN). A quote's price is only an offer; it becomes binding when you place an order from that quote.

Quotes and orders

  • A quote is a live price estimate for an amount, duration and (optionally) a target address. It expires after a short window.
  • An order reserves funds from your prepaid balance and is fulfilled asynchronously.

There are two ways to create an order:

  1. One step — post the amount, duration and target address directly; the price is resolved at order time (see Create an order).
  2. Two steps — create a quote to lock a price, then apply it. When applying a quote, the order's target_address must match the quote's.

Use the two-step flow when you want a guaranteed price before committing.

A flash charge is a third, duration-less flow for energy or bandwidth top-ups: post an energy_num and target address, and the order settles on actual usage (see Create a flash order). It is distinguished in your history by order_type: "FLASH".

Order lifecycle

PENDING ──────► COMPLETED
   │
   ├──────────► FAILED
   │
   └──────────► RECONCILIATION_REQUIRED
  • PENDING — reserved and being fulfilled.
  • COMPLETED — Energy delegated to the target address.
  • FAILED — could not be fulfilled; the reservation is released.
  • RECONCILIATION_REQUIRED — an ambiguous outcome that our team is resolving.

Webhooks are optional. If you set a callback_url on your API key, every status change is pushed to you (see Webhooks); otherwise poll GET /api/v1/energy/orders/:order_id.

Idempotency

Orders accept an idempotency_key. Reusing a key with the same payload returns the original order without charging twice; reusing it with a different payload returns an error. Generate a fresh key per logical order and keep it for safe retries.

Account activation

A quote may include target_activated — whether the target address was activated on-chain at quote time. An unactivated address consumes extra Energy on its first transfer; the API reports this so you can warn your users. It is advisory and does not change the price.