Create Energy Rule

POST

api

energy

auto-refill

Create Energy Rule

curl --request POST \
  --url https://api.example.com/api/v1/energy/auto-refill \
  --header 'Content-Type: application/json' \
  --data '
{
  "target_address": "<string>",
  "threshold_energy": 123,
  "add_volume": 123,
  "duration": "<string>",
  "label": "<string>"
}
'

import requests

url = "https://api.example.com/api/v1/energy/auto-refill"

payload = {
    "target_address": "<string>",
    "threshold_energy": 123,
    "add_volume": 123,
    "duration": "<string>",
    "label": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    target_address: '<string>',
    threshold_energy: 123,
    add_volume: 123,
    duration: '<string>',
    label: '<string>'
  })
};

fetch('https://api.example.com/api/v1/energy/auto-refill', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/energy/auto-refill",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target_address' => '<string>',
    'threshold_energy' => 123,
    'add_volume' => 123,
    'duration' => '<string>',
    'label' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/energy/auto-refill"

	payload := strings.NewReader("{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/energy/auto-refill")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/energy/auto-refill")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "current_energy": {},
  "will_refill_now": true
}

Creates an Auto Refill rule for one address. From the next check on, whenever the address has less available energy than threshold_energy, we buy add_volume energy for one hour and charge your balance. See the overview for how checks, cost and statuses work. The request only creates the rule — it does not buy anything itself. Requires the buy_energy scope. To see the price of one refill first, use Energy Refill Quote.

Request body

string

required

TRON address to keep supplied (T… format, 34 characters). Contract addresses are rejected.

number

required

Buy when the address has less available energy than this. From 1 to 50,000,000.

number

required

Energy to buy per refill. From 32,000 to 5,000,000. Keep it at or above threshold_energy — see the warning in the overview.

string

default:"1h"

Rental duration of each refill. Only "1h" is accepted; any other value returns 422.

string

Your own name for the rule, up to 100 characters. Optional.

Response

The new rule — the same fields as in List Energy Rules — plus two fields about the address right now:

number | null

Energy available on the address at the moment the rule was created. null if it could not be read; the rule is created either way.

boolean

true if current_energy is already below the threshold, so the next check — usually within a minute — will buy. false if the address has enough, or if the level could not be read.

Example

curl -X POST https://api.tronrental.com/v1/energy/auto-refill \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_address": "TYourRecipientAddress1234567890abc",
    "threshold_energy": 65000,
    "add_volume": 131000,
    "duration": "1h",
    "label": "Hot wallet"
  }'

import requests

resp = requests.post(
    "https://api.tronrental.com/v1/energy/auto-refill",
    headers={"X-API-Key": "your_api_key"},
    json={
        "target_address": "TYourRecipientAddress1234567890abc",
        "threshold_energy": 65000,
        "add_volume": 131000,
        "duration": "1h",
        "label": "Hot wallet",
    },
)
print(resp.json())

const resp = await fetch("https://api.tronrental.com/v1/energy/auto-refill", {
  method: "POST",
  headers: { "X-API-Key": "your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({
    target_address: "TYourRecipientAddress1234567890abc",
    threshold_energy: 65000,
    add_volume: 131000,
    duration: "1h",
    label: "Hot wallet",
  }),
});
console.log(await resp.json());

Response

{
  "id": 12,
  "target_address": "TYourRecipientAddress1234567890abc",
  "label": "Hot wallet",
  "threshold_energy": 65000,
  "add_volume": 131000,
  "duration": "1h",
  "status": "active",
  "stopped_reason": null,
  "consecutive_failures": 0,
  "last_checked_at": null,
  "last_available_energy": null,
  "last_read_error_at": null,
  "last_refill_at": null,
  "refill_count": 0,
  "total_spent_trx": "0.000000",
  "created_at": "2026-10-14T08:12:05Z",
  "estimated_cost_per_refill_trx": "2.618000",
  "volume_below_threshold": false,
  "current_energy": 0,
  "will_refill_now": true
}

Errors

Status	Code	When
`400`	`INVALID_ADDRESS`	`target_address` is not a valid TRON address
`400`	`CONTRACT_ADDRESS_NOT_SUPPORTED`	`target_address` is a smart contract
`403`	`FORBIDDEN`	The API key lacks the `buy_energy` scope
`409`	`AUTOREFILL_ADDRESS_TAKEN`	Your account already has an energy rule for this address — edit it instead
`409`	`AUTOREFILL_LIMIT_REACHED`	Your account already has 20 energy rules; the limit is also in `error.limit`
`422`	—	A field is missing or out of range, or `duration` is not `"1h"`
`429`	`RATE_LIMIT_EXCEEDED`	More than 10 create requests in a minute
`503`	`AUTOREFILL_DISABLED`	Auto Refill for energy is temporarily switched off; no rule was created — try again later

{
  "detail": {
    "error": {
      "code": "AUTOREFILL_LIMIT_REACHED",
      "message": "You already hold the maximum of auto-refill rules: 20 for energy and 20 for bandwidth, counted separately. Delete one to add another.",
      "limit": 20
    }
  }
}

{
  "detail": {
    "error": {
      "code": "AUTOREFILL_ADDRESS_TAKEN",
      "message": "Auto-refill for this address already exists"
    }
  }
}

{
  "detail": {
    "error": {
      "code": "AUTOREFILL_DISABLED",
      "message": "Auto-refill is temporarily unavailable; please try again later"
    }
  }
}

A validation error comes in the framework’s format, with detail as an array:

{
  "detail": [
    {
      "type": "literal_error",
      "loc": ["body", "duration"],
      "msg": "Input should be '1h'",
      "input": "1d",
      "ctx": {"expected": "'1h'"}
    }
  ]
}

Retrying a create after a timeout is safe. If the first request went through, the retry returns 409 AUTOREFILL_ADDRESS_TAKEN instead of making a second rule; list your rules to get its id.

Create Energy Rule

curl --request POST \
  --url https://api.example.com/api/v1/energy/auto-refill \
  --header 'Content-Type: application/json' \
  --data '
{
  "target_address": "<string>",
  "threshold_energy": 123,
  "add_volume": 123,
  "duration": "<string>",
  "label": "<string>"
}
'

import requests

url = "https://api.example.com/api/v1/energy/auto-refill"

payload = {
    "target_address": "<string>",
    "threshold_energy": 123,
    "add_volume": 123,
    "duration": "<string>",
    "label": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    target_address: '<string>',
    threshold_energy: 123,
    add_volume: 123,
    duration: '<string>',
    label: '<string>'
  })
};

fetch('https://api.example.com/api/v1/energy/auto-refill', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/energy/auto-refill",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target_address' => '<string>',
    'threshold_energy' => 123,
    'add_volume' => 123,
    'duration' => '<string>',
    'label' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/energy/auto-refill"

	payload := strings.NewReader("{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/energy/auto-refill")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/energy/auto-refill")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target_address\": \"<string>\",\n  \"threshold_energy\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "current_energy": {},
  "will_refill_now": true
}

Core API

Bandwidth Rentals

Auto Refill

Orders

Invoices

Smart Mode

Transfer Packages

Account

Webhooks

Create Energy Rule