Si tu app, exchange o bot envía USDT (TRC-20) a gran escala, no quieres comprar energía a mano. El SDK oficial de TronSave te permite estimar, comprar, extender y seguir órdenes de energía directamente desde tu backend, en Node.js, Python, Rust, Java o PHP. Esta guía te lleva desde la instalación hasta tu primera orden de energía on-chain.
Los SDK
Todos los SDK usan la API v2 y envuelven los mismos endpoints, así que tienes las mismas operaciones en cada lenguaje:
| Lenguaje | Paquete | Instalación | 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+ |
Los paquetes de Rust, Python, Java y PHP están todos en la versión 2.0.0. Para Java, las coordenadas son io.tronsave:sdk:2.0.0: agrégalo a pom.xml como dependencia o a build.gradle como implementation 'io.tronsave:sdk:2.0.0'.
Qué cubre cada SDK
La superficie es pequeña a propósito. Elijas el lenguaje que elijas, tienes las mismas siete operaciones:
- Estimate Buy Resource: calcula el precio de una compra antes de comprometerte.
- Buy Resource: crea la orden de energía o ancho de banda; devuelve un ID de orden.
- Get Order / Get Orders: consulta el estado de una orden o tu historial de órdenes.
- Get Order Book: lee la oferta en vivo por niveles de precio, del más barato al más caro.
- Get User Info: saldo de la cuenta interna y dirección de depósito.
- Get Extendable Delegates: lista las delegaciones que se pueden renovar.
- Extend Request: renueva una delegación existente en lugar de comprar una orden nueva.
Ese último par importa más de lo que parece. Si un receptor ya tiene energía delegada y solo necesitas que dure más, extenderla es la opción correcta: consulta la guía de la función Extend.
Inicio rápido (Node.js)
La ruta más rápida es el flujo con API key: crea una instancia del SDK, estima el costo y luego crea la orden. Obtén una API key en el panel de TronSave (consulta Autenticación).
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();
Consejo: usa network: "testnet" (Nile) para desarrollar sin TRX reales y luego cambia a "mainnet" para producción.
Dos detalles que conviene saber antes de ejecutarlo. userInfo.balance llega en SUN como string (1 TRX equivale a 1.000.000 SUN), por eso la comparación lo convierte. Y durationSec es opcional: si lo omites, la orden dura por defecto 259.200 segundos, es decir, 3 días.
La misma tarea en Python
El paquete de Python se instala con pip install tronsave y ofrece el mismo flujo estimar → comprar → seguir; las firmas de los métodos de cada lenguaje están en la referencia del SDK. Si prefieres ver exactamente qué llamadas HTTP se hacen por debajo, aquí tienes la misma tarea (estimar, comprar y consultar) escrita directamente contra los 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")
Los mismos tres pasos, los mismos nombres de campo, el mismo formato de respuesta. El valor del SDK está en el tipado y los reintentos, no en una API distinta, así que elige lo que mejor encaje con tu stack. Para un script de Python más completo, con dimensionamiento según el libro de órdenes y manejo de errores, consulta cómo comprar energía TRON con Python.
Estima antes de comprar
La llamada de estimación merece un párrafo propio, porque su respuesta te dice dos cosas distintas. estimateTrx es el costo en SUN. availableResource es cuánto puede suministrar realmente el mercado en este momento. Si availableResource es menor que el resourceAmount que pediste, la orden no puede completarse del todo en ese momento, y tú decides qué hacer mediante options: allowPartialFill: true para aceptar lo que haya, u onlyCreateWhenFulfilled: true para rechazar cualquier cosa que no sea una ejecución completa. En bots con muchos reintentos, preventDuplicateIncompleteOrders: true evita que una llamada repetida acumule órdenes abiertas idénticas.
Errores y límites
Los endpoints permiten 15 solicitudes por segundo; si lo superas, recibes HTTP 429 con "Rate limit reached", y basta con un backoff simple de 1 s/2 s/4 s. Los errores de la aplicación llegan como error: true con un código legible por máquina dentro de message: INVALID_API_KEY, INTERNAL_BALANCE_ACCOUNT_TOO_LOW, PRICE_EXCEED_MAX_PRICE_REQUIRED, CANNOT_FULFILLED. Ramifica según el código; el texto puede cambiar.
Controlar TronSave desde un agente de IA
Si tu integración es un agente y no un servicio, TronSave también publica un servidor MCP, alojado en https://mcp.tronsave.io/mcp mediante Streamable HTTP (con https://mcp.tronsave.io/testnet/mcp para la testnet). Expone 53 herramientas MCP (versión del servidor 1.3.0, noviembre de 2026), como tronsave_estimate_buy_resource, tronsave_list_order_books, tronsave_internal_order_create y el resto, con sesiones por API key o por firma de billetera. Conecta cualquier cliente compatible con MCP al endpoint; nuestra guía del servidor MCP de TronSave explica el inicio de sesión, las dos familias de herramientas y el modelo de seguridad.
¿Prefieres HTTP directo? Los SDK envuelven los mismos endpoints de la API: consulta nuestra guía de automatización con la API, la explicación de los tipos de orden de TronSave y, para grandes volúmenes, comprar energía al por mayor.
Preguntas frecuentes (FAQ)
¿Necesito una API key?
El flujo con API key es el más sencillo; también puedes firmar con una clave privada. Obtén una key en el panel. La diferencia está en la custodia: una API key gasta de una cuenta interna de TronSave con fondos previos, mientras que el flujo con transacciones firmadas paga desde tu propia billetera en cada compra y necesita TronWeb.
¿Qué lenguajes son compatibles?
Node.js/TypeScript, Python, Rust, Java y PHP, todos sobre la API v2. Hay guías específicas para Python, Java, PHP y Rust.
¿Cuánta energía necesita una transferencia de USDT?
Unas 65.000 (≈130.000 si el destinatario nunca ha tenido USDT). Más detalles en cuánta energía necesita una transferencia de USDT.
¿Puedo probar sin gastar TRX reales?
Sí. Configura network: "testnet" (o apunta la URL base a https://api-dev.tronsave.io) para trabajar contra Nile. Las keys, los saldos y las órdenes son independientes en cada entorno, así que genera una key de Nile en testnet.tronsave.io: una key de mainnet será rechazada. Shasta no es compatible.
Empieza a construir: lee la documentación de TronSave y obtén una API key en el panel del mercado.
¿Desarrollas en Python? Consulta la guía específica: cómo comprar energía TRON con Python (script completo y ejecutable).


