Guias de TRON

Como comprar energia TRON em Python (API TronSave, 2026)

Por TronSave Publicado 7 min de leitura
Nesta página

Se o seu backend em Python envia USDT (TRC-20) — um bot, uma exchange, um serviço de pagamentos —, o ideal é comprar energia TRON em Python de forma automática, e não manualmente. Este é um exemplo completo e pronto para rodar com a API TronSave: ele consulta o seu saldo, cria uma ordem de energia e fica verificando até a energia ser entregue.

Antes de começar

  • Gere uma chave de API no painel da TronSave (ela gasta do seu saldo interno na TronSave — nunca a exponha no lado do cliente).
  • Instale o cliente HTTP: pip install requests. Prefere um wrapper tipado? Use o SDK oficial: pip install tronsave — veja a visão geral do SDK.
  • Deposite na conta interna. O depósito mínimo é de 10 TRX por transação, e o primeiro depósito precisa de cerca de 1 TRX a mais para ativar o novo endereço. O saldo é atualizado em uns 3 segundos.

Os endpoints

O script usa quatro endpoints v2, autenticados com o header apikey:

  • GET /v2/user-info — o saldo da sua conta interna.
  • GET /v2/order-book — liquidez disponível e preços.
  • POST /v2/buy-resource — cria a ordem e retorna um orderId.
  • GET /v2/order/{orderId} — consulte até fulfilledPercent chegar a 100.

Todos têm limite de 15 requisições por segundo. E todos retornam o mesmo envelope: error, message e um objeto data. Escreva o parsing uma vez e ele funciona em todos.

Exemplo completo em Python

import time, requests

API_KEY = "your_api_key"
TRONSAVE_API_URL = "https://api.tronsave.io"   # testnet: https://api-dev.tronsave.io
RECEIVER_ADDRESS = "your_receiver_address"
BUY_AMOUNT = 65000          # ~1 USDT (TRC-20) transfer
DURATION = 3600             # rental duration, in seconds (1 hour)
MAX_PRICE_ACCEPTED = 100    # max price in SUN per unit
RESOURCE_TYPE = "ENERGY"    # ENERGY or BANDWIDTH

HEADERS = {"apikey": API_KEY}

def get_account_info():
    return requests.get(f"{TRONSAVE_API_URL}/v2/user-info", headers=HEADERS).json()

def get_order_book():
    return requests.get(f"{TRONSAVE_API_URL}/v2/order-book",
                        headers=HEADERS,
                        params={"address": RECEIVER_ADDRESS}).json()

def buy_resource():
    body = {
        "resourceType": RESOURCE_TYPE,
        "unitPrice": "MEDIUM",          # a price in SUN, or SLOW / MEDIUM / FAST
        "resourceAmount": BUY_AMOUNT,
        "receiver": RECEIVER_ADDRESS,
        "durationSec": DURATION,
        "options": {
            "allowPartialFill": True,
            "maxPriceAccepted": MAX_PRICE_ACCEPTED,
            "preventDuplicateIncompleteOrders": True,
        },
    }
    return requests.post(f"{TRONSAVE_API_URL}/v2/buy-resource",
                         headers={**HEADERS, "Content-Type": "application/json"},
                         json=body).json()

def get_order(order_id):
    return requests.get(f"{TRONSAVE_API_URL}/v2/order/{order_id}", headers=HEADERS).json()

def main():
    print(get_order_book()["data"])      # [{"price": 54, "availableResourceAmount": 2403704}, ...]

    balance = int(get_account_info()["data"]["balance"])
    if balance < MAX_PRICE_ACCEPTED * BUY_AMOUNT:
        raise SystemExit("Insufficient TronSave balance")

    order = buy_resource()
    if order["error"]:
        raise SystemExit(f"Buy failed: {order['message']}")

    order_id = order["data"]["orderId"]
    while True:                          # poll until the energy is delivered
        time.sleep(3)
        detail = get_order(order_id)["data"]
        if detail["fulfilledPercent"] == 100 or detail["remainAmount"] == 0:
            print(f"Energy delivered - paid {detail['payoutAmount'] / 1e6} TRX")
            for d in detail["delegates"]:
                print(d["delegator"], d["amount"], d["txid"])
            break
        print(f"Waiting for fill... {detail['fulfilledPercent']}%")

if __name__ == "__main__":
    main()

Como funciona

  1. Leia o mercado primeiro. get_order_book() retorna uma lista de níveis {price, availableResourceAmount} — com a oferta mais barata primeiro. Se você precisa de 500.000 de energia e os dois níveis mais baratos somam só 300.000, o seu preço de preenchimento é definido pelo terceiro nível. É por isso que um maxPriceAccepted baixo e fixo no código falha silenciosamente nos dias de mercado movimentado.
  2. Verifique o saldo. get_account_info() retorna balance, depositAddress e representAddress — os valores vêm em SUN, como string, então converta. 1 TRX = 1.000.000 SUN. Um retorno "50000000" equivale a 50 TRX.
  3. Crie a ordem. buy_resource() faz um POST em /v2/buy-resource. Defina sua API_KEY, o RECEIVER_ADDRESS e quanta energia comprar — 65.000 cobrem uma transferência de USDT, e cerca de 130.000 se o destinatário nunca recebeu USDT (veja quanta energia uma transferência de USDT precisa). Se você omitir durationSec, o padrão é 259.200 (3 dias). Em caso de sucesso, você recebe de volta apenas um orderId — e isso é o esperado.
  4. Acompanhe o preenchimento. get_order() retorna a ordem em tempo real: fulfilledPercent (0 = ainda pendente, 1–99 = parcial, 100 = completa), remainAmount, o price efetivamente pago em SUN, payoutAmount em SUN e um array delegates com o endereço do provedor, a quantidade e o txid on-chain de cada correspondência. Registre esses txids em log — eles são o seu comprovante, verificável no Tronscan.

Como escolher o unitPrice

unitPrice aceita um preço inteiro em SUN ou um de três níveis, e esses níveis são definidos a partir do livro de ofertas em tempo real, não como acréscimos fixos:

Valor Comportamento Quando usar
"SLOW" O menor preço possível para a ordem Sem pressa; economizar importa mais que a velocidade
"MEDIUM" Padrão. O menor preço que ainda obtém o preenchimento máximo do mercado; se o mercado não consegue preencher nada, MEDIUM = SLOW + 10 Praticamente sempre
"FAST" Se o mercado está 100% pronto, FAST = MEDIUM; abaixo disso, MEDIUM + 10; com 0% pronto, SLOW + 20 A transferência precisa sair agora
80 (número) Um preço fixo em SUN, controle total Você mesmo calcula o preço a partir do livro de ofertas

Como tratar os erros que realmente acontecem

Respostas fora da faixa 2xx voltam com error: true e um código embutido em message, como TSAS:106 API_KEY_REQUIRED. Trate pelo código, não pelo texto legível — a redação pode mudar. Estes são os que um bot em Python encontra em produção:

  • INTERNAL_BALANCE_ACCOUNT_TOO_LOW — recarregue a conta interna. Vale criar um alerta antes que isso aconteça, e não depois.
  • PRICE_EXCEED_MAX_PRICE_REQUIRED — o mercado subiu acima do seu maxPriceAccepted. Leia o livro de ofertas de novo e tente outra vez com um teto maior, ou aguarde.
  • CANNOT_FULFILLED — você definiu onlyCreateWhenFulfilled: true e o mercado não consegue preencher 100% agora. Remova essa flag ou ative allowPartialFill.
  • MUST_BE_WAIT_PREVIOUS_ORDER_FILLED — você enviou parâmetros idênticos enquanto uma ordem anterior ainda está aberta. É o preventDuplicateIncompleteOrders: true fazendo o seu trabalho; é essa opção que impede um loop de retentativas de comprar em dobro.
  • 429 RATE_LIMIT — use backoff exponencial (1 s, 2 s, 4 s) e fique dentro de 15 requisições por segundo.

Falhas de schema têm outra cara: vêm da camada HTTP como FST_ERR_VALIDATION e indicam o campo ausente, por exemplo "body must have required property 'receiver'". São úteis durante o desenvolvimento e indicam um bug, não uma condição de mercado.

Testnet vs. mainnet

Desenvolva na testnet com https://api-dev.tronsave.io (Nile, sem TRX real) e depois troque para https://api.tronsave.io em produção. Só o domínio muda — todos os caminhos continuam idênticos, então basta alterar uma única constante TRONSAVE_API_URL.

Obtenha uma chave da Nile em testnet.tronsave.io com uma carteira configurada na rede Nile e depois abasteça-a pelo faucet da Nile. Um ponto para planejar: chaves de API, saldos e ordens são totalmente separados entre os dois ambientes. Uma chave da mainnet retorna INVALID_API_KEY no host da testnet — o comportamento correto, mas confuso às 2 da manhã. A TronSave não oferece suporte à Shasta — use a Nile.

Trabalha com outra linguagem? O mesmo fluxo está disponível como SDK para Node.js, Rust, Java e PHP, e há também um guia geral de automação via API. Se preferir não rodar um loop de consulta, o Auto-Buy recarrega um endereço monitorado com base no limite que você definir. A referência completa está na documentação da TronSave.

Perguntas frequentes

Preciso do TronWeb?
Não para o fluxo com chave de API mostrado acima — o requests puro basta. O TronWeb só é necessário se você assinar e pagar diretamente com uma chave privada, que é o fluxo de transação assinada.

Quanta energia uma transferência de USDT consome?
Cerca de 65.000 (≈130.000 para uma carteira que nunca teve USDT).

De onde sai o pagamento?
Do seu saldo pré-pago na TronSave, recarregado no painel. Nada é assinado on-chain a cada ordem, e é por isso que o script não precisa de chave privada.

E se a ordem for preenchida só em parte?
Com allowPartialFill: true você recebe o que o mercado conseguiu casar, fulfilledPercent fica entre 1 e 99 e você paga apenas pela parte atendida. Faça um loop sobre remainAmount e crie uma nova ordem para a diferença, ou defina onlyCreateWhenFulfilled: true para que a ordem só seja criada se puder ser concluída.

TronSave
TronSave

A equipe da TronSave desenvolve o mercado de energia e largura de banda da TRON em tronsave.io e escreve estes guias com base em testes reais na rede principal da TRON.

Artigos relacionados

Usamos o Google Analytics para saber quais guias ajudam os leitores. Ele só grava cookies se você permitir a análise. O blog não exibe anúncios. Privacidade