Buy Energy or Bandwidth
POST/buy
Rent Energy (default) or Bandwidth for one hour for a receiver address; set resource_type to choose. The cost is deducted from your account balance immediately — including a one-time account-activation fee (activation_fee_sun) when the receiver is not yet activated on TRON. The order starts as PENDING; the resource is typically delegated within seconds. Use the Get Order endpoint to poll for completion.
receiver_address is checked before anything is charged: an invalid address returns 400 invalid_address.
Send an Idempotency-Key header so that a retry after a timeout returns the original order instead of placing a second one — see Idempotency.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 500
- 503
Successful Response
Purchase rejected; nothing was charged:
insufficient_balance— your balance is below the order total (nomessage; carriescurrent_balanceandrequired_amountin SUN)order_amount_below_minimum/order_amount_above_maximum— keyed bycode, withmin/maxinvalid_address—receiver_addressis not a valid TRON addressinvalid_idempotency_key—Idempotency-Keylonger than 128 charactersunsupported_resource— only Energy or Bandwidth is offered; a Bandwidth order from an account that can buy Energy only is also refused
The X-API-Key header is missing, invalid or revoked. detail is a plain string: API key required, Invalid API key or User not found.
The account is blocked (plain-string detail: Account is blocked), or ip_not_allowed — the request's source IP is outside this key's IP allowlist. Or reseller_suspended (no message) — purchasing is suspended for your account; contact support.
duplicate_request — a request with the same Idempotency-Key is still being processed. Retry with the same key after a few seconds. If it keeps returning 409, check GET /orders before retrying with a new key.
Request body validation failed (e.g. a missing field, resource_amount not above 0, or a duration other than 1h) — detail is an array of field errors.
Rate limit exceeded — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). detail is a plain string; wait the number of seconds in Retry-After, then retry.
Response Headers
Seconds until the rate-limit window resets.
internal_error — unexpected error; the order was not placed. Retry later.
service_unavailable — purchasing the requested resource is temporarily unavailable; or reseller_activation_balance_low (no message) — purchasing is temporarily unavailable for your account. Retry later.