Guias de TRON

Como comprar energia TRON com código: o SDK da TronSave (Node.js, Python e mais)

Por TronSave Publicado 7 min de leitura
Nesta página

Se o seu app, exchange ou bot envia USDT (TRC-20) em grande escala, você não quer comprar energia manualmente. O SDK oficial da TronSave permite estimar, comprar, estender e acompanhar ordens de energia direto do seu backend, em Node.js, Python, Rust, Java ou PHP. Este guia leva você da instalação até a sua primeira ordem de energia on-chain.

Os SDKs

Todos os SDKs usam a API v2 e encapsulam os mesmos endpoints, então você tem as mesmas operações em qualquer linguagem:

Linguagem Pacote Instalação Requisitos
TypeScript / JS tronsave-sdk npm install tronsave-sdk Node.js 18+
Python tronsave pip install tronsave Python 3.9+
Rust tronsave cargo add tronsave —
Java io.tronsave:sdk Maven / Gradle —
PHP tronsave/sdk composer require tronsave/sdk PHP 8.1+

Os pacotes de Rust, Python, Java e PHP estão todos na versão 2.0.0. Para Java, as coordenadas são io.tronsave:sdk:2.0.0: adicione ao pom.xml como dependência ou ao build.gradle como implementation 'io.tronsave:sdk:2.0.0'.

O que cada SDK cobre

A superfície é propositalmente pequena. Seja qual for a linguagem escolhida, você tem as mesmas sete operações:

  • Estimate Buy Resource: calcula o preço de uma compra antes de você se comprometer.
  • Buy Resource: cria a ordem de energia ou largura de banda; retorna um ID de ordem.
  • Get Order / Get Orders: consulta o status de uma ordem ou o seu histórico de ordens.
  • Get Order Book: lê a oferta ao vivo por níveis de preço, do mais barato ao mais caro.
  • Get User Info: saldo da conta interna e endereço de depósito.
  • Get Extendable Delegates: lista as delegações que podem ser renovadas.
  • Extend Request: renova uma delegação existente em vez de comprar uma ordem nova.

Esse último par importa mais do que parece. Se um destinatário já tem energia delegada e você só precisa que ela dure mais, estender é o caminho certo: veja o guia da função Extend.

Início rápido (Node.js)

O caminho mais rápido é o fluxo com API key: crie uma instância do SDK, estime o custo e depois crie a ordem. Pegue uma API key no painel da TronSave (veja Autenticação).

import { TronsaveSDK } from "tronsave-sdk";

const main = async () => {
  const sdk = new TronsaveSDK({ network: "mainnet", apiKey: "your_api_key" });

  const userInfo = await sdk.getUserInfo();

  // Estimate cost for 65,000 ENERGY for 1 hour (one USDT transfer)
  const estimate = await sdk.estimateBuyResource({
    receiver: "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    resourceType: "ENERGY",
    durationSec: 3600,
    resourceAmount: 65000,
  });
  if (estimate.estimateTrx > Number(userInfo.balance)) throw new Error("Insufficient balance");

  const { orderId } = await sdk.buyResource({
    receiver: "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    resourceType: "ENERGY",
    durationSec: 3600,
    resourceAmount: 65000,
  });

  await new Promise((r) => setTimeout(r, 5000)); // wait ~5s to fill
  const order = await sdk.getOrder(orderId);
  console.log(order.fulfilledPercent < 100 ? "Not filled" : "Filled");
};

main();

Dica: use network: "testnet" (Nile) para desenvolver sem TRX real e depois mude para "mainnet" em produção.

Dois detalhes que vale saber antes de rodar. userInfo.balance volta em SUN como string (1 TRX equivale a 1.000.000 SUN), por isso a comparação converte o valor. E durationSec é opcional: se você omitir, a ordem usa o padrão de 259.200 segundos, ou seja, 3 dias.

A mesma tarefa em Python

O pacote Python é instalado com pip install tronsave e oferece o mesmo fluxo estimar → comprar → acompanhar; as assinaturas dos métodos de cada linguagem estão na referência do SDK. Se você prefere ver exatamente quais chamadas HTTP acontecem por baixo, aqui está a mesma tarefa (estimar, comprar e consultar) escrita direto contra os endpoints v2:

import time, requests

API = "https://api.tronsave.io"          # testnet: https://api-dev.tronsave.io
HEADERS = {"apikey": "your_api_key", "Content-Type": "application/json"}
ORDER = {
    "receiver": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "resourceType": "ENERGY",
    "resourceAmount": 65000,
    "durationSec": 3600,
    "unitPrice": "MEDIUM",
}

estimate = requests.post(f"{API}/v2/estimate-buy-resource", json=ORDER).json()["data"]
print(estimate["estimateTrx"] / 1e6, "TRX", estimate["availableResource"], "available")

order = requests.post(f"{API}/v2/buy-resource", headers=HEADERS,
                      json={**ORDER, "options": {"allowPartialFill": True,
                                                 "maxPriceAccepted": 100}}).json()
order_id = order["data"]["orderId"]

time.sleep(5)
detail = requests.get(f"{API}/v2/order/{order_id}", headers=HEADERS).json()["data"]
print("Filled" if detail["fulfilledPercent"] == 100 else "Not filled")

Os mesmos três passos, os mesmos nomes de campos, o mesmo formato de resposta. O valor do SDK está na tipagem e nas novas tentativas, não em uma API diferente, então escolha o que combina com a sua stack. Para um script Python mais completo, com dimensionamento pelo livro de ordens e tratamento de erros, veja como comprar energia TRON com Python.

Estime antes de comprar

A chamada de estimativa merece um parágrafo próprio, porque a resposta diz duas coisas diferentes. estimateTrx é o custo em SUN. availableResource é quanto o mercado realmente consegue fornecer agora. Se availableResource vier menor que o resourceAmount pedido, a ordem não pode ser preenchida por completo naquele momento, e você decide o que fazer por meio de options: allowPartialFill: true para aceitar o que houver, ou onlyCreateWhenFulfilled: true para recusar qualquer coisa abaixo de um preenchimento total. Em bots com muitas novas tentativas, preventDuplicateIncompleteOrders: true impede que uma chamada repetida acumule ordens abertas idênticas.

Erros e limites

Os endpoints permitem 15 requisições por segundo; acima disso, você recebe HTTP 429 com "Rate limit reached", e um backoff simples de 1 s/2 s/4 s é suficiente. Erros da aplicação chegam como error: true com um código legível por máquina dentro de message: INVALID_API_KEY, INTERNAL_BALANCE_ACCOUNT_TOO_LOW, PRICE_EXCEED_MAX_PRICE_REQUIRED, CANNOT_FULFILLED. Trate pelo código; o texto pode mudar.

Controlar a TronSave a partir de um agente de IA

Se a sua integração é um agente e não um serviço, a TronSave também publica um servidor MCP, hospedado em https://mcp.tronsave.io/mcp via Streamable HTTP (com https://mcp.tronsave.io/testnet/mcp para a testnet). Ele expõe 53 ferramentas MCP (versão do servidor 1.3.0, novembro de 2026), como tronsave_estimate_buy_resource, tronsave_list_order_books, tronsave_internal_order_create e as demais, com sessões por API key ou por assinatura da carteira. Aponte qualquer cliente compatível com MCP para o endpoint; o nosso guia do servidor MCP da TronSave explica o login, as duas famílias de ferramentas e o modelo de segurança.

Prefere HTTP puro? Os SDKs encapsulam os mesmos endpoints da API: veja o nosso guia de automação com a API, a explicação dos tipos de ordem da TronSave e, para alto volume, comprar energia em grande quantidade.

Perguntas frequentes (FAQ)

Preciso de uma API key?
O fluxo com API key é o mais simples; você também pode assinar com uma chave privada. Pegue uma key no painel. A diferença está na custódia: uma API key gasta de uma conta interna da TronSave com saldo pré-carregado, enquanto o fluxo com transações assinadas paga da sua própria carteira a cada compra e exige TronWeb.

Quais linguagens são suportadas?
Node.js/TypeScript, Python, Rust, Java e PHP, todas na API v2. Há guias específicos para Python, Java, PHP e Rust.

Quanta energia uma transferência de USDT precisa?
Cerca de 65.000 (≈130.000 se o destinatário nunca teve USDT). Mais detalhes em quanta energia uma transferência de USDT precisa.

Posso testar sem gastar TRX real?
Sim. Defina network: "testnet" (ou aponte a URL base para https://api-dev.tronsave.io) para rodar na Nile. Keys, saldos e ordens são separados por ambiente, então gere uma key da Nile em testnet.tronsave.io: uma key da mainnet será rejeitada. A Shasta não é suportada.

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