Skip to main content

​
Auto Refill

Auto Refill watches a TRON address and tops it up whenever its energy or bandwidth falls below a level you set. You choose the threshold, how much to add each time, and the rental duration. Every refill is an ordinary order paid from your balance.

​
How it works

  1. Create a rule for an address with a threshold, an add_volume and a duration.
  2. We check how much energy (or bandwidth) the address has available once a minute, and right after every outgoing USDT transfer from that address.
  3. If the level is below the threshold, we buy add_volume for the address and charge your balance at your price.
  4. The rental ends after its duration. When the level falls below the threshold again, the rule buys again. That is how the rule keeps the address supplied: there is no separate renewal step.
If a check cannot read the address, it buys nothing; the rule shows the time in last_read_error_at, and the next check tries again. Creating a rule does not buy anything on the spot. The first refill happens at the next check, usually within a minute. The create response says whether it will happen (will_refill_now) and how much the address has right now.
Auto Refill reacts after the level drops; it does not wait in front of a transfer. Set the threshold to at least what your next transaction needs, so that the transaction is already covered when it is sent.

​
Energy and bandwidth

The two resources have their own endpoints and their own rules. One address can have an energy rule and a bandwidth rule at the same time; each is checked against its own threshold. Energy is rented for one hour. When it runs out or expires, the level falls and the rule buys the next hour. Bandwidth counts everything the address can pay for a transaction with: the free 600 bandwidth every account gets per day, plus any staked or delegated bandwidth. A threshold of 600 or less is therefore met by the free allowance alone until the address has spent it.

​
Choosing the numbers

Keep add_volume at or above the threshold. A refill adds add_volume to whatever is left on the address. If add_volume is smaller than the threshold, one refill on a nearly empty address can leave it still below the threshold, and the rule will buy again after every spend — up to several times a minute, not once an hour. Each of those refills is a full order with its own fixed fee. Rule responses flag this case with volume_below_threshold: true.
A USDT transfer uses about 65,000 energy when the recipient already holds USDT and about 131,000 when it does not, plus roughly 345 bandwidth. For example, threshold_energy: 65000 with add_volume: 131000 buys two transfers’ worth whenever less than one is left.

​
Cost

Each refill is a regular order: the rental at your rate plus the fixed fee, which is charged on every refill. estimated_cost_per_refill_trx in the list and create responses is the full price of one refill for your account, fixed fee included. To see that price before you create a rule, use the quote endpoint: energy, bandwidth. A small add_volume refilled often pays the fixed fee many times; a larger one pays it less often. A rule created with an API key is priced like a purchase made with that API key; a rule created on the website is priced like a website purchase. estimated_cost_per_refill_trx already reflects this. If the address does not exist on-chain yet, the first refill also activates it, the same as a regular purchase. The activation is charged on top and is not part of estimated_cost_per_refill_trx; the order shows it in activation_cost_trx. There is no daily spending cap: a rule buys whenever the level is below its threshold and your balance covers a refill.

​
Orders and webhooks

Every refill appears in your order history (List Orders) with source: "autorefill". To list only refill orders, call GET /orders?source=autorefill; to export them as a file, use the autorefill report. Rules created with an API key send order.updated webhooks for their refill orders, the same as orders you place through the API. Rules created without an API key do not.

​
Rule status

Paused after failures. A failed refill is refunded like any failed order. After 5 failed refills in a row the rule is paused and stopped_reason gives the reason of the last failure. consecutive_failures shows how close a rule is to that limit; it goes back to 0 after a successful refill and when you resume the rule. A paused rule never resumes by itself: fix the cause, then set status: "active". Stopped for balance. When your balance cannot cover one refill, the rule stops with stopped_insufficient_balance. Once a deposit brings the balance up to the price of one refill, the rule returns to active automatically. You can also set status: "active" yourself; if the balance is still short, the rule stops again at the next check. If your Telegram account is linked, you get a message on the first refill of a rule and when a rule is paused, stopped for balance or resumed.

​
Limits

  • One rule per address and resource on an account. Creating a second energy rule (or a second bandwidth rule) for the same address returns 409 AUTOREFILL_ADDRESS_TAKEN — edit the existing rule instead.
  • 20 energy rules and 20 bandwidth rules per account. Deleted rules do not count. Over the limit: 409 AUTOREFILL_LIMIT_REACHED.
  • No contract addresses, such as the USDT token contract: TRON does not allow delegating resources to them.
  • Creating rules is limited to 10 requests per minute per account, for each resource. See Rate Limits.

​
Editing and deleting

Changes apply from the next check. While a refill for the rule is being bought, PATCH and DELETE return 409 AUTOREFILL_IN_PROGRESS — retry in a minute. Deleting a rule does not take back energy or bandwidth already bought; those rentals run until the end of their term.

​
Compared with Smart Mode and auto-renew rentals

​
Endpoints