Tovanix
Tovanix

API de alquiler de energía TRON

Alquila energía TRON por programa en lugar de quemar TRX en comisiones: un 70–80 % más barato por transferencia TRC-20.

  • Pedidos: indica la dirección receptora, la cantidad de energía y el periodo de alquiler; la delegación se completa en segundos
  • Consulta de pedidos: revisa el estado de la delegación y su vencimiento por id de pedido o por dirección
  • Precios: precio unitario en vivo y tramos para planificar costos
  • Webhooks: eventos de delegación exitosa y de vencimiento, firmados con HMAC

GET / POST /api/v1/energy/*

Autenticación

La API de alquiler de energía usa la clave API del comercio para autenticarse. Incluye los siguientes encabezados en cada solicitud:

Inicia sesión en la consola → Herramientas y ajustes → Gestión de API, crea y activa una clave API para obtener X-API-Key y X-Secret-Key.

Llamadas firmadas a endpoints con cargo

Crear un pedido, crear una orden única y recuperar energía son endpoints con cargo. Las claves API nuevas exigen por defecto solicitudes firmadas para ellos (X-Key-ID / X-Timestamp / X-Nonce / X-Sign-Version / X-Signature); abajo tienes un ejemplo completo para crear un pedido. Los endpoints de consulta siguen aceptando solo X-API-Key + X-Secret-Key. Si desactivas «Exigir firma en cobros y datos sensibles» en la configuración de la clave, los endpoints con cargo también aceptan la X-Secret-Key en texto plano, pero no lo recomendamos.

Resumen

Las transferencias de USDT en la cadena TRON consumen energía. Las direcciones sin TRX congelado pagan ~6.5-13 TRX de gas por transacción. Con energía alquilada, la transferencia usa esa energía en lugar de quemar TRX; cuánto ahorras depende del precio del alquiler al hacer el pedido.

Transferir USDT a una dirección que ya tiene saldo USDT: ~65,000 de energía

Transferir USDT a una dirección que nunca recibió USDT: ~135,000 de energía

Obtener información de la plataforma

GET /api/v1/energy/info

Obtén la información pública del servicio de alquiler de energía, incluidos la energía disponible, los niveles de precio y los límites.

Consultar el saldo

GET /api/v1/energy/balance

Consulta el saldo de la cuenta a la que pertenece esta API key. El alquiler de energía es un flujo de alta frecuencia y bajo importe donde quedarse sin saldo es habitual: consúltalo antes de pedidos en lote y configura una alerta de saldo bajo.

Listar periodos de alquiler (endpoint)

GET /api/v1/energy/periods

Devuelve los valores admitidos de period. Cualquier otro valor se rechaza con 400 y no se crea ningún pedido.

Estimación de precio

GET /api/v1/energy/price

Estima el costo del alquiler para un período y una cantidad de energía dados. Devuelve el precio específico de la API (TRX).

Estimar el consumo de energía

GET /api/v1/energy/estimate-energy

Estima cuánta energía se necesita para transferir USDT a una dirección dada.

Crear orden de alquiler

POST /api/v1/energy/order

Crea una orden de alquiler de energía; la comisión se deduce del saldo de la cuenta (USD).

Campos de la respuesta

Devuelve code: 400, message: "Insufficient account balance, please top up first" cuando el saldo es insuficiente

Orden de energía única

POST /api/v1/energy/order/onetime

Crea una orden individual con la estrategia por transacción; el sistema asigna automáticamente energy_amount.

Consultar lista de órdenes

GET /api/v1/energy/orders

Consulta tus órdenes de alquiler de energía.

Consultar una orden

GET /api/v1/energy/order/:serial

Consulta el detalle de la orden y sincroniza el estado más reciente.

Consultar un pedido por tu propio número

GET /api/v1/energy/order/by-trade-no/:out_trade_no

Busca un pedido por tu out_trade_no — no necesitas nuestro serial.

⚠️ Cuando se agota el tiempo, el endpoint de creación devuelve 504 y en ese momento solo tienes el out_trade_no (el serial lo generamos nosotros y no viene en esa respuesta). Este endpoint existe precisamente para ese caso: con el mismo out_trade_no consultas el resultado final.

Recuperar orden

POST /api/v1/energy/order/reclaim

Recupera anticipadamente una orden de alquiler de energía que aún no ha vencido.

Callback del resultado del pedido

En los pedidos creados con callback_url (incluidas las órdenes únicas), la plataforma envía una vez el resultado a esa URL cuando el pedido se resuelve por primera vez como exitoso (status=40) o fallido (status=41). Ya sea que el estado se confirme por la notificación de estado en tiempo real, la consulta periódica, la conciliación o la recuperación de un pedido que no se pudo guardar, cada pedido se envía una sola vez, y los envíos fallidos se reintentan automáticamente. La excepción son los pedidos cuya creación devolvió 504 con un resultado desconocido (registrados internamente como un marcador cuyo serial empieza por LOCAL-): se resuelven manualmente y no se envían de forma automática, así que confirma su resultado con la consulta por tu propio número. La plataforma emite y firma el callback; el formato de callback anterior ya no se usa, así que las integraciones existentes deben ajustar el análisis y la verificación de la firma según esta sección.

La solicitud es un POST con Content-Type: application/json. El cuerpo es un objeto JSON plano en el que todos los valores son cadenas (incluidos status, energy_amount y timestamp) y no incluye ningún campo de precio. La plataforma no sigue redirecciones y cada solicitud expira a los 10 segundos.

Verificación de la firma

El algoritmo es el mismo que en los callbacks de pedidos de cobro: toma todos los campos con valor no vacío excepto sign, ordénalos por nombre en orden ASCII, únelos como k1=v1&k2=v2&… y calcula HMAC-SHA256; el resultado es hexadecimal en minúsculas. La clave es la Secret Key de la clave API con la que se creó el pedido; en los pedidos creados con credenciales de una app de cobro, es el Secreto de notificaciones de esa app (WebhookSecret, visible en el detalle de la app en la consola; es la misma clave que usan los callbacks de pedidos de cobro); las apps antiguas que nunca generaron ese secreto usan la App Key.

El envío no incluye sign cuando el pedido lo creó el soporte de la plataforma en tu nombre (no hay una clave asociada) o cuando la clave API o la app de cobro usada para crearlo ya se eliminó. Si recibes un envío sin sign, confirma el estado con el endpoint de consulta antes de procesarlo.

Respuesta y reintentos

Cualquier código de estado 2xx cuenta como entregado; el cuerpo de la respuesta no se revisa. Un estado distinto de 2xx, un tiempo de espera agotado, un fallo de conexión o una redirección cuentan como fallo, y la plataforma reintenta a los 30 segundos, 1 minuto, 2 minutos y 5 minutos, y después cada 10 minutos, hasta 10 reintentos (se detiene a los 70 minutos aproximadamente). Los reintentos reenvían exactamente el mismo cuerpo, incluidos notify_id y sign.

Si la red falla después de que tu servidor procesó el envío pero antes de que la plataforma reciba el 2xx, el mismo pedido se enviará otra vez. Elimina duplicados por notify_id o serial y asegúrate de que procesarlo dos veces no tenga efectos secundarios. El envío es un aviso, no la única fuente de verdad: si no te llega o falla definitivamente, confirma el resultado con GET /api/v1/energy/order/:serial o con la consulta por tu propio número.

Períodos de alquiler

Estos son todos los períodos admitidos actualmente. También puedes obtenerlos con GET /api/v1/energy/periods. Cualquier otro valor devuelve 400 y no se crea ninguna orden.

Preguntas frecuentes

¿Cuánto ahorra realmente la API de alquiler de energía?

Quemar TRX directamente en una transferencia de USDT TRC-20 suele costar entre 13 y 27 TRX. Alquilar energía reduce ese costo un 70–80 %, y la diferencia crece en transferencias por lote.

¿Qué tan rápida es la delegación y puedo enviarla a otra dirección?

La delegación se completa en segundos y la dirección receptora es la que indiques en la solicitud; no tiene que ser la cuenta que hace el pedido, así que puedes abastecer de energía cualquier dirección de tu negocio en lote.

Páginas relacionadas: Alquiler de energía TRON · Documentación de la API · Pagos cripto multicadena

Cargando…