POST

Create a flash order

/api/v1/energy/flash_orders

Create a flash charge order (energy or bandwidth). Unlike a rental order, a flash order has no duration: it top-ups the target address with a resource buffer, and the actual amount is settled asynchronously from real usage. Your balance is frozen for an estimate at order time and the remainder is refunded when the order settles.

Flash orders support energy and bandwidth and are the recommended flow for accounts that continuously need energy. They appear in your order history with order_type: "FLASH".

To preview the price and freeze before committing, use estimate flash order.

Limits

energy_num must be within the product's range:
1. Flash energy: 100000 to 500000000.
2. Flash bandwidth: 50000 to 1000000.
The exact orderable range for a given target address depends on current availability. Query POST /api/v1/energy/flash_limits for the live minimum/maximum before ordering.

Orderable range (flash_limits) — POST /api/v1/energy/flash_limits returns the current orderable range for a target address. It takes product (TRON_ENERGY, default, or TRON_BANDWIDTH) and target_address.
{
  "product": "TRON_BANDWIDTH",
  "target_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}
{
  "data": {
    "product": "TRON_BANDWIDTH",
    "target_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "enabled": true,
    "min_quantity": 50000,
    "max_quantity": 1000000
  },
  "request_id": "…"
}
enabled: false means this product is not currently available for the address.

min_quantity / max_quantity are omitted when the current range is unknown.

Request body

Field	Type	Required	Description
`energy_num`	integer	yes	Resource buffer to top up (1 ≤ energy_num ≤ 500000000). Energy units for `TRON_ENERGY`, bandwidth units for `TRON_BANDWIDTH`.
`target_address`	string	yes	TRON address to top up.
`product`	string	no	`TRON_ENERGY` (default) or `TRON_BANDWIDTH`. Bandwidth flash is currently available to enabled accounts only.
`idempotency_key`	string	yes	Your unique key for safe retries (≤ 200 chars).

{
  "product": "TRON_ENERGY",
  "energy_num": 200000,
  "target_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "idempotency_key": "idem-0001"
}

Response

{
  "data": {
    "order_id": "ord_9c2b7f0a",
    "status": "PENDING",
    "product": "TRON_ENERGY",
    "order_type": "FLASH",
    "amount": 200000,
    "duration_minutes": null,
    "target_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "customer_price": "6.500",
    "currency": "TRX",
    "created_at": "2026-09-22T12:00:00.000Z",
    "completed_at": null,
    "failure_reason": null
  },
  "request_id": "…"
}

Field	Type	Description
`order_id`	string	The order id.
`order_type`	string	`FLASH` for flash orders (rental orders return `RENTAL`).
`status`	string	`PENDING`, `COMPLETED`, `FAILED`, or `RECONCILIATION_REQUIRED`.
`customer_price`	string	The estimate at creation; overwritten with the actual settled price once the order completes. In TRX (decimal string, not SUN; 1 TRX = 10^6 SUN).
`duration_minutes`	null	Flash orders have no duration.

Settlement semantics

At creation the balance is frozen for the estimate plus a safety margin (never a price promise).
We delegate energy to the target address and later reclaim unused energy and settle on actual usage.
On completion, you are charged the actual settled amount and the freeze remainder is returned to your available balance.
Poll the flash order (or subscribe to webhooks) to observe COMPLETED/FAILED.

Errors

INVALID_ADDRESS — target_address is not a valid TRON address.
INVALID_REQUEST — product is neither TRON_ENERGY nor TRON_BANDWIDTH, bandwidth flash is not enabled for your account, or energy_num is outside the supported range.
INSUFFICIENT_BALANCE — your prepaid balance cannot cover the frozen estimate.
IDEMPOTENCY_CONFLICT — the idempotency key was reused with a different payload.