Create Bandwidth Rule

POST

api

bandwidth

auto-refill

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

import requests

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

payload = {
    "target_address": "<string>",
    "threshold_bandwidth": 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_bandwidth: 123,
    add_volume: 123,
    duration: '<string>',
    label: '<string>'
  })
};

fetch('https://api.example.com/api/v1/bandwidth/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/bandwidth/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_bandwidth' => 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/bandwidth/auto-refill"

	payload := strings.NewReader("{\n  \"target_address\": \"<string>\",\n  \"threshold_bandwidth\": 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/bandwidth/auto-refill")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_address\": \"<string>\",\n  \"threshold_bandwidth\": 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/bandwidth/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_bandwidth\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}"

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

{
  "current_bandwidth": {},
  "will_refill_now": true
}

Creates an Auto Refill rule for one address. From the next check on, whenever the address has less available bandwidth than threshold_bandwidth, we buy add_volume bandwidth for the chosen duration 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_bandwidth scope. To see the price of one refill first, use Bandwidth Refill Quote.

Available bandwidth counts everything the address can pay for a transaction with: the free 600 a day plus any staked or delegated bandwidth. A threshold of 600 or less is met by the free allowance alone until the address has spent it.

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 bandwidth than this. From 1 to 1,000,000.

number

required

Bandwidth to buy per refill. From 350 to 100,000. Keep it at or above threshold_bandwidth — see the warning in the overview.

string

default:"1h"

Rental duration of each refill: "1h" or "1d".

string

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

Response

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

number | null

Bandwidth available on the address at the moment the rule was created, free bandwidth included. null if it could not be read; the rule is created either way.

boolean

true if current_bandwidth 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/bandwidth/auto-refill \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_address": "TYourRecipientAddress1234567890abc",
    "threshold_bandwidth": 1000,
    "add_volume": 5000,
    "duration": "1h",
    "label": "Payouts"
  }'

import requests

resp = requests.post(
    "https://api.tronrental.com/v1/bandwidth/auto-refill",
    headers={"X-API-Key": "your_api_key"},
    json={
        "target_address": "TYourRecipientAddress1234567890abc",
        "threshold_bandwidth": 1000,
        "add_volume": 5000,
        "duration": "1h",
        "label": "Payouts",
    },
)
print(resp.json())

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

Response

{
  "id": 15,
  "target_address": "TYourRecipientAddress1234567890abc",
  "label": "Payouts",
  "threshold_bandwidth": 1000,
  "add_volume": 5000,
  "duration": "1h",
  "status": "active",
  "stopped_reason": null,
  "consecutive_failures": 0,
  "last_checked_at": null,
  "last_available_bandwidth": null,
  "last_read_error_at": null,
  "last_refill_at": null,
  "refill_count": 0,
  "total_spent_trx": "0.000000",
  "created_at": "2026-10-14T08:15:00Z",
  "estimated_cost_per_refill_trx": "0.370000",
  "volume_below_threshold": false,
  "current_bandwidth": 600,
  "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_bandwidth` scope
`409`	`AUTOREFILL_ADDRESS_TAKEN`	Your account already has a bandwidth rule for this address — edit it instead
`409`	`AUTOREFILL_LIMIT_REACHED`	Your account already has 20 bandwidth rules; the limit is also in `error.limit`
`422`	—	A field is missing or out of range, or `duration` is not `"1h"` or `"1d"`
`429`	`RATE_LIMIT_EXCEEDED`	More than 10 create requests in a minute
`503`	`AUTOREFILL_DISABLED`	Auto Refill for bandwidth is temporarily switched off; no rule was created — try again later

{
  "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": "greater_than_equal",
      "loc": ["body", "add_volume"],
      "msg": "Input should be greater than or equal to 350",
      "input": 100,
      "ctx": {"ge": 350}
    }
  ]
}

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 Bandwidth Rule

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

import requests

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

payload = {
    "target_address": "<string>",
    "threshold_bandwidth": 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_bandwidth: 123,
    add_volume: 123,
    duration: '<string>',
    label: '<string>'
  })
};

fetch('https://api.example.com/api/v1/bandwidth/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/bandwidth/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_bandwidth' => 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/bandwidth/auto-refill"

	payload := strings.NewReader("{\n  \"target_address\": \"<string>\",\n  \"threshold_bandwidth\": 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/bandwidth/auto-refill")
  .header("Content-Type", "application/json")
  .body("{\n  \"target_address\": \"<string>\",\n  \"threshold_bandwidth\": 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/bandwidth/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_bandwidth\": 123,\n  \"add_volume\": 123,\n  \"duration\": \"<string>\",\n  \"label\": \"<string>\"\n}"

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

{
  "current_bandwidth": {},
  "will_refill_now": true
}

Core API

Bandwidth Rentals

Auto Refill

Orders

Invoices

Smart Mode

Transfer Packages

Account

Webhooks

Create Bandwidth Rule