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 umorderId.GET /v2/order/{orderId}— consulte atéfulfilledPercentchegar 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
- 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 ummaxPriceAcceptedbaixo e fixo no código falha silenciosamente nos dias de mercado movimentado. - Verifique o saldo.
get_account_info()retornabalance,depositAddresserepresentAddress— os valores vêm em SUN, como string, então converta. 1 TRX = 1.000.000 SUN. Um retorno"50000000"equivale a 50 TRX. - Crie a ordem.
buy_resource()faz um POST em/v2/buy-resource. Defina suaAPI_KEY, oRECEIVER_ADDRESSe 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ê omitirdurationSec, o padrão é 259.200 (3 dias). Em caso de sucesso, você recebe de volta apenas umorderId— e isso é o esperado. - Acompanhe o preenchimento.
get_order()retorna a ordem em tempo real:fulfilledPercent(0 = ainda pendente, 1–99 = parcial, 100 = completa),remainAmount, opriceefetivamente pago em SUN,payoutAmountem SUN e um arraydelegatescom o endereço do provedor, a quantidade e otxidon-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 seumaxPriceAccepted. Leia o livro de ofertas de novo e tente outra vez com um teto maior, ou aguarde.CANNOT_FULFILLED— você definiuonlyCreateWhenFulfilled: truee o mercado não consegue preencher 100% agora. Remova essa flag ou ativeallowPartialFill.MUST_BE_WAIT_PREVIOUS_ORDER_FILLED— você enviou parâmetros idênticos enquanto uma ordem anterior ainda está aberta. É opreventDuplicateIncompleteOrders: truefazendo 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.
Mãos à obra: gere uma chave de API no mercado da TronSave e leia a documentação para desenvolvedores.


