> ## Documentation Index > Fetch the complete documentation index at: https://docs.tronrental.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar regra de largura de banda > Reabasteça a largura de banda de um endereço sempre que ela cair abaixo de um limiar ## Criar regra de largura de banda Cria uma regra de Recarga automática para um endereço. A partir da verificação seguinte, sempre que o endereço tiver menos largura de banda disponível do que `threshold_bandwidth`, compramos `add_volume` de largura de banda pela `duration` escolhida e cobramos do seu saldo. Veja a [visão geral](/pt/api-reference/auto-refill/overview) para entender como funcionam as verificações, o custo e os status. A requisição apenas cria a regra — ela mesma não compra nada. Exige o escopo `buy_bandwidth`. Para ver antes o preço de uma recarga, use [Cotação de recarga de largura de banda](/pt/api-reference/auto-refill/quote-bandwidth-refill). > [!NOTE] > > A largura de banda disponível conta **tudo** com que o endereço pode pagar uma transação: as 600 gratuitas por dia, mais qualquer largura de banda em stake ou delegada. Um limiar de 600 ou menos é atendido só pela cota gratuita, até que o endereço a gaste. ### Corpo da requisição **target\_address** `string` *required* Endereço TRON a manter abastecido (formato T..., 34 caracteres). Endereços de contrato são recusados. **threshold\_bandwidth** `number` *required* Compra quando o endereço tem menos largura de banda disponível do que este valor. De 1 a 1.000.000. **add\_volume** `number` *required* Largura de banda a comprar por recarga. De 350 a 100.000. Mantenha-o igual ou acima de `threshold_bandwidth` — veja o [aviso na visão geral](/pt/api-reference/auto-refill/overview#escolhendo-os-números). **duration** `string` (default: 1h) Duração do aluguel de cada recarga: `"1h"` ou `"1d"`. **label** `string` Um nome próprio para a regra, até 100 caracteres. Opcional. ### Resposta A nova regra — com os mesmos campos de [Listar regras de largura de banda](/pt/api-reference/auto-refill/list-bandwidth-rules) — mais dois campos sobre o estado atual do endereço: **current\_bandwidth** `number | null` Largura de banda disponível no endereço no momento em que a regra foi criada, incluindo a gratuita. `null` se não foi possível lê-la; a regra é criada de qualquer forma. **will\_refill\_now** `boolean` `true` se `current_bandwidth` já está abaixo do limiar, de modo que a próxima verificação — normalmente em até um minuto — vai comprar. `false` se o endereço tem o suficiente ou se não foi possível ler o nível. ### Exemplo ```bash cURL theme={null} 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" }' ``` ```python Python theme={null} 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()) ``` ```javascript JavaScript theme={null} 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()); ``` ```json Response theme={null} { "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 } ``` ### Erros | Status | Código | Quando | | - | - | - | | `400` | `INVALID_ADDRESS` | `target_address` não é um endereço TRON válido | | `400` | `CONTRACT_ADDRESS_NOT_SUPPORTED` | `target_address` é um contrato inteligente | | `403` | `FORBIDDEN` | A chave de API não tem o escopo `buy_bandwidth` | | `409` | `AUTOREFILL_ADDRESS_TAKEN` | A sua conta já tem uma regra de largura de banda para este endereço — edite-a | | `409` | `AUTOREFILL_LIMIT_REACHED` | A sua conta já tem 20 regras de largura de banda; o limite também vem em `error.limit` | | `422` | — | Um campo está ausente ou fora do intervalo, ou `duration` não é `"1h"` nem `"1d"` | | `429` | `RATE_LIMIT_EXCEEDED` | Mais de 10 requisições de criação em um minuto | | `503` | `AUTOREFILL_DISABLED` | A Recarga automática de largura de banda está temporariamente desativada; nenhuma regra foi criada — tente novamente mais tarde | ```json theme={null} { "detail": { "error": { "code": "AUTOREFILL_ADDRESS_TAKEN", "message": "Auto-refill for this address already exists" } } } ``` ```json theme={null} { "detail": { "error": { "code": "AUTOREFILL_DISABLED", "message": "Auto-refill is temporarily unavailable; please try again later" } } } ``` Um erro de validação vem no formato do framework, com `detail` como array: ```json theme={null} { "detail": [ { "type": "greater_than_equal", "loc": ["body", "add_volume"], "msg": "Input should be greater than or equal to 350", "input": 100, "ctx": {"ge": 350} } ] } ``` > [!TIP] > > Repetir uma criação após um timeout é seguro. Se a primeira requisição foi processada, a repetição retorna `409 AUTOREFILL_ADDRESS_TAKEN` em vez de criar uma segunda regra; [liste as suas regras](/pt/api-reference/auto-refill/list-bandwidth-rules) para obter o `id` dela. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.