Create an order

Every business event needs a stable unique client_request_id. This is the required duplicate protection for network retries.

Request body

{"client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"expected_total_trx":"3.200000"}

Field	Type	Required	Description
client_request_id	string	yes	Your unique operation ID. Reuse it only for this exact order.
address	string	yes	Valid TRON destination address.
energy	integer	yes	Positive amount divisible by the portion size.
duration_minutes	integer	yes	Allowed duration from options, in minutes.
expected_total_trx	string	yes	Exact six-decimal total_trx from the latest quote.

Unknown JSON properties are rejected. Send Content-Type: application/json.

Response 201 or 200

{"id":"7c0c9a54-517c-4bbb-a946-bf14bf86c113","client_request_id":"order-1042","address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","energy":65000,"duration_minutes":60,"total_trx":"3.200000","status":"created","lifecycle_final":false,"delivery_final":false,"created_at":1784376000,"updated_at":1784376000,"energy_usable":false}

The response carries the full order shape described in get an order, and leaves out every field that has no value yet: a freshly created order has no rental_expires_at and no failure key rather than null ones.

• 201 Created — a new order; Location contains /v1/energy/orders/{id}.
• 200 OK — an exact idempotent replay returned the existing order.
• 409 Conflict with code: energy_order_idempotency_conflict — the same client_request_id was used with a different address, amount, or duration.
• 409 Conflict with code: energy_price_changed — fetch a new quote and submit again. No order was created and no TRX was held.
• 409 Conflict with code: insufficient_balance — the quoted total exceeds available_trx. Top up the account, then submit again. No order was created and no TRX was held.

Idempotency

After a timeout, do not generate a new ID. Replay the same body and client_request_id. Generate a new ID only for a new business event.

State fields

status describes the current stage. Automation should use lifecycle_final and delivery_final, not a hard-coded status list. See get an order.

Errors

Possible statuses are 400, 401, 409, 413, 415, 429, 500, and 503. Do not automatically retry 400, 401, 409, 413, or 415 without correcting the cause.