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.
Comece a desenvolver: leia a documentação da TronSave e pegue uma API key no painel do mercado.
Desenvolve em Python? Veja o guia específico: como comprar energia TRON com Python (script completo e executável).


