API de alquiler de energía TRON para automatizar transferencias de USDT TRC-20

Qué ofrece la API y a quién va dirigida

La API de Quick Rent permite alquilar energía TRON de forma automática. Utilizar energía puede reducir el coste de enviar USDT TRC-20 y de ejecutar otros contratos inteligentes frente a pagar quemando TRX.

Tu programa, ya sea un sitio web, un bot o un servicio, compra la energía cuando la necesita. Por ejemplo, antes de cada transferencia de USDT de un cliente.

El proceso es parecido al de una máquina expendedora: consultas el precio, pagas y recibes lo que has comprado. Con la API, es tu programa el que realiza esos pasos.

Glosario

Definiciones de los términos que aparecen en esta documentación.

Antes de empezar

Prepara lo siguiente antes de enviar tu primera solicitud.

Introducción

La API de Quick Rent permite a tu servicio alquilar energía TRON automáticamente para reducir el coste de enviar USDT TRC-20 y ejecutar otros contratos inteligentes frente a la quema de TRX.

Todos los endpoints utilizan la misma URL base.

https://tronbid.com/api/v2/quick-rent

Autenticación

Incluye tu clave de API en cada solicitud como token Bearer en la cabecera Authorization.

Guarda la clave únicamente en el servidor, por ejemplo en el backend o en los secretos del sistema de integración continua. No la incluyas en el código del navegador ni en repositorios públicos. Cada clave está vinculada a una cuenta de TronBid, cuya billetera se fija al conceder el acceso. Los pagos con saldo solo pueden cargarse a esa cuenta.

Si superas el límite de solicitudes, la API responde con HTTP 429.

Authorization: Bearer <API_KEY>

Modalidades de pago

Puedes pagar de dos formas. El pago en la blockchain está disponible por defecto y no requiere configuración. El pago con saldo es opcional y debe habilitarse para tu clave.

Si no está habilitado, una solicitud con payment_mode: balance devuelve 403 BALANCE_PAYMENT_NOT_ENABLED. Contacta con soporte de TronBid para activarlo.

Catálogo de paquetes

energy_amount y duration_minutes deben coincidir con un paquete activo de Quick Rent: habitualmente 65000 o 131000 unidades de energía y 15 o 60 minutos.

Puedes consultar el catálogo vigente en cualquier momento, sin autenticación:

curl -sS https://tronbid.com/api/public/quick-rent/skus

Inicio rápido: de la primera solicitud a la energía

Este ejemplo recorre el proceso completo con pago en la blockchain. En cuatro pasos, la billetera recibe la energía.

A continuación se explica cada paso y la respuesta de la API. Sustituye la clave, las direcciones y el ID del pedido por tus propios datos.

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

# poll every 3s until the order is done
while true; do
  STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    delegated|failed|expired|cancelled) break ;;
  esac
  sleep 3
done

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

Flujo de pago en la blockchain

Paso 1: consulta el precio con POST /quote. Paso 2: crea el pedido con POST /orders y obtén pay_address, amount_trx y expires_at. Paso 3: envía exactamente amount_trx TRX a pay_address desde payer_address. Paso 4: consulta GET /orders/:id hasta que el estado sea delegated, o termine en failed, expired o cancelled.

target_address es opcional. Si lo omites, la energía se delega a payer_address.

Solo puede haber un pedido en la blockchain pendiente de pago (pending_payment) por payer_address. De lo contrario, recibirás 409 PENDING_PAYMENT_INTENT_EXISTS. Si pagas de más o de menos, la cantidad final de energía puede variar: consulta effective_energy_amount en GET /orders/:id.

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-001",
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

Flujo de pago con saldo

Paso 1: consulta tus TRX con GET /balance. Paso 2: obtén el precio con POST /quote. Paso 3: envía POST /orders con payment_mode: balance para descontar el importe e iniciar la delegación. Paso 4: consulta GET /orders/:id hasta que el estado sea delegated. Si falla la delegación, el estado pasa a failed y los TRX se devuelven al saldo.

No necesitas payer_address: paga la cuenta vinculada a tu clave de API. El energy_amount de la respuesta puede superar la cantidad del paquete solicitado por la bonificación de la matriz de precios.

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-balance-001",
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

Custom Locked: bloqueo de 1 a 15 minutos (API de energía)

Añade custom_lock_minutes a POST /quote y POST /orders para elegir un bloqueo de energía en minutos enteros: 1, 2, 3… hasta 15. Estos pedidos requieren una clave de API y admiten pagos en la blockchain o con saldo, si está habilitado. La opción no está disponible para ancho de banda, el formulario del sitio web ni el bot de Telegram.

Mantén duration_minutes en 15: este campo selecciona el paquete de precios. custom_lock_minutes determina el bloqueo real. Utiliza un energy_amount de un paquete activo de 15 minutos. El precio y la bonificación de energía son los mismos que los de ese paquete, sin descuento proporcional por minutos. Consulta el precio actual en /quote; los ejemplos no fijan un precio.

El campo es opcional y no tiene un valor predeterminado implícito. Si lo omites, se mantienen el comportamiento de 15 o 60 minutos, los precios y el formato de respuesta existentes. Envía un entero JSON: las cadenas, los decimales, null, 0, los negativos y los valores superiores a 15 se rechazan con HTTP 400. También se rechaza Custom Locked con duration_minutes: 60 o resource_type: bandwidth.

Para pedidos en la blockchain, envía el amount_trx devuelto a pay_address desde payer_address antes de expires_at. Por defecto, target_address toma el valor de payer_address. Para pedidos con saldo, indica target_address y payment_mode: balance; tu clave debe tener habilitada esta modalidad.

El bloqueo empieza cuando la delegación se incluye en TRON, no al consultar el precio, crear el pedido o pagar. Un minuto equivale a 20 bloques de TRON, aproximadamente 60 segundos. Guardamos el vencimiento real en delegation_expires_at. El expires_at de la respuesta de pago es un plazo distinto: la fecha límite para pagar.

Consulta GET /orders/:id, por ejemplo cada 3 segundos. Las respuestas de Custom Locked incluyen custom_lock_minutes y lock_period_blocks. El endpoint de estado también devuelve delegation_expires_at, reclaim_status, txid_delegate, txid_reclaim y reclaimed_at. Las fechas y los IDs de transacción aún no disponibles tienen el valor null.

Ciclo del pedido: pending_payment (solo para pagos en la blockchain) → delegating → delegated → undelegating → completed. delegated confirma la entrega de la energía. undelegating indica que el bloqueo terminó y se está retirando la delegación; reclaim_status es pending. completed junto con reclaim_status: confirmed significa que la transacción de retirada está confirmada de forma irreversible en la blockchain. No necesitas enviar una solicitud de retirada adicional.

Estos pedidos tienen un proceso de recuperación propio que se ejecuta cada 3 segundos. La retirada se intenta en cuanto TRON indica que la delegación está desbloqueada, sin esperar a la revisión de pools de cada cinco minutos. La producción de bloques, la carga de las colas y la disponibilidad de los proveedores RPC pueden retrasar el envío; la confirmación de red requiere tiempo adicional. No retiramos la delegación antes de que venza el bloqueo de la red.

Los pedidos, las transacciones firmadas y los intentos de retirada se guardan de forma persistente. Tras un reinicio o un tiempo de espera agotado del proveedor RPC, se reanuda la misma transacción, sin crear otro alquiler. Los fallos de proveedor se reintentan automáticamente. La pareja origen–destinatario permanece reservada hasta confirmar la retirada; otro pool libre puede atender un nuevo pedido.

Reutiliza la misma idempotency_key al reintentar. Si cambias, añades o eliminas custom_lock_minutes con una clave existente, recibirás 409 IDEMPOTENCY_CUSTOM_LOCK_MISMATCH. Utiliza una clave nueva para un bloqueo distinto. Las reglas existentes sobre cambios de modalidad de pago siguen vigentes.

Los webhooks configurados conservan su firma y su mecanismo de entrega. Los eventos de Custom Locked incluyen los campos opcionales del bloqueo: quick_buy.delegated al entregar la energía; quick_buy.expired con status: completed y txid_reclaim tras confirmar la retirada; o quick_buy.failed si se verifica que la delegación falló. Elimina duplicados mediante event_id. Si el estado es incierto por un proveedor, consulta el pedido existente en lugar de crear otro.

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/quote \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5
}'

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX",
  "idempotency_key": "partner-custom-5min-balance-001"
}'

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX",
  "idempotency_key": "partner-custom-5min-onchain-001"
}'

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "delegated",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "lock_period_blocks": 100,
  "delegation_expires_at": "2026-09-27T12:05:00.000Z",
  "reclaim_status": "not_started",
  "txid_delegate": "<delegation transaction hash>",
  "txid_reclaim": null,
  "reclaimed_at": null
}

Estados del pedido

El pedido pasa por los siguientes estados. Consulta GET /orders/:id para seguir su evolución.

Idempotencia

idempotency_key es el identificador único que asignas al pedido y debe tener entre 8 y 128 caracteres. Si repites POST /orders con la misma clave para el mismo cliente de API, recibirás el mismo pedido con "duplicate": true.

No reutilices una idempotency_key con modalidades de pago distintas (onchain y balance): recibirás 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.

Disponibilidad de pools para un destinatario

Antes de enviar un pedido, puedes comprobar si al menos un pool de energía de Quick Rent habilitado está libre para el destinatario. POST /api/v2/quick-rent/availability utiliza tu clave Bearer existente y los mismos límites por clave y por IP que los demás métodos autenticados. No requiere una clave de idempotencia.

Envía target_address con una dirección TRON Base58 válida. resource_type es opcional y solo admite energy. No envíes energy_amount, duration_minutes, custom_lock_minutes ni datos de pago a este endpoint. La comprobación no admite ancho de banda.

HTTP 200 con available: true y reason: AVAILABLE significa que al menos una pareja pool–destinatario no tiene un bloqueo de energía activo ni una reserva pendiente de Quick Rent. HTTP 200 con available: false y reason: ALL_POOLS_BUSY indica que todos los pools aptos están ocupados para ese destinatario. NO_ELIGIBLE_POOLS indica que no hay ninguna fuente habilitada que pueda atenderlo, incluso si la única fuente coincide con el propio destinatario. Que los pools estén ocupados es un resultado normal, no un error HTTP.

Se aplican las reglas de reserva existentes, incluidos los pedidos delegating, delegate_confirming, undelegating y los pedidos delegated activos. Custom Locked sigue ocupando su fuente hasta que se procese la retirada, aunque el plazo de bloqueo ya haya terminado. Se consultan la configuración actual de los pools, las reservas de la base de datos y los bloqueos actuales de la blockchain para las parejas sin reserva. checked_at es la hora UTC en la que terminó la consulta, no una hora de desbloqueo garantizada.

HTTP 400: INVALID_REQUEST si el JSON no es válido, faltan campos, hay campos desconocidos o el recurso no es compatible; INVALID_TARGET_ADDRESS si la dirección o su suma de comprobación no son válidas. HTTP 401: clave ausente, no válida o deshabilitada. HTTP 429: límite de solicitudes superado. HTTP 503: QUICK_RENT_DISABLED o AVAILABILITY_CHECK_UNAVAILABLE si no pueden verificarse la base de datos, la configuración del firmante o la blockchain. Un 503 significa que el resultado es desconocido; no lo interpretes como disponibilidad ni como ocupación.

Flujo recomendado: comprueba la disponibilidad, solicita una cotización para la cantidad deseada y envía el pedido con el método habitual. Si los pools están ocupados, espera o utiliza otro destinatario. Reintenta las consultas inciertas aumentando el intervalo entre intentos; evita los bucles de consulta continua. Los endpoints y las respuestas existentes no cambian. Este método es opcional.

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/availability \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron"
}'

{
  "resource_type": "energy",
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron",
  "available": true,
  "reason": "AVAILABLE",
  "checked_at": "2026-09-30T12:00:00.000Z"
}

{
  "resource_type": "energy",
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron",
  "available": false,
  "reason": "ALL_POOLS_BUSY",
  "checked_at": "2026-09-30T12:00:00.000Z"
}

{
  "error": "AVAILABILITY_CHECK_UNAVAILABLE",
  "message": "Availability could not be verified. Retry later."
}

Calculadora

Estima la energía necesaria para una transferencia. Indica la billetera destinataria y si ya tiene USDT.

{
  "wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "has_usdt": true
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'

Consultar el precio

Devuelve el precio actual del paquete (price_trx), su disponibilidad, el porcentaje de ahorro (save_percent) y la validez de la cotización en segundos (expires_in_sec).

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"energy_amount":131000,"duration_minutes":15}'

Crear un pedido

Crea un pedido de alquiler. Para pagar en la blockchain, indica payer_address y envía el amount_trx devuelto a pay_address. Para pagar con saldo, añade payment_mode: balance; el importe se descuenta inmediatamente de la cuenta vinculada.

target_address es opcional y, por defecto, toma el valor de payer_address. Ten en cuenta los conflictos HTTP 409: solo puede haber un pedido pendiente de pago por pagador, y los pools ocupados para el destinatario pueden impedir un nuevo pedido (ACTIVE_DELEGATION_EXISTS).

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-onchain-001",
    "payer_address": "TPayer...",
    "target_address": "TTarget..."
  }'

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-balance-001",
    "payment_mode": "balance",
    "target_address": "TTarget..."
  }'

Consultar el estado de un pedido

Devuelve el estado, payment_mode, los importes y las direcciones. Si hubo un fallo, incluye error_code y error_message. effective_energy_amount refleja la energía realmente delegada tras ajustar un pago de más o de menos.

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

Cancelar un pedido

Cancela un pedido que sigue en pending_payment. Solo se aplica a pagos en la blockchain. Una vez delegada la energía, ya no se puede cancelar.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

Cambiar la billetera de pago

Cambia la billetera que pagará un pedido en la blockchain que siga en pending_payment. Resulta útil si el cliente decide usar otra billetera antes de enviar los TRX.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer_address":"TNewPayer..."}'

Consultar el saldo

Devuelve el saldo en TRX de la cuenta de TronBid vinculada a tu clave de API. Es el saldo dentro de la plataforma, no el de una billetera en la blockchain. Requiere la cabecera Authorization.

{ "balance_trx": "150.500000" }

curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
  -H "Authorization: Bearer $API_KEY"

Códigos de error

Los errores incluyen un estado HTTP y el campo error. Estas son las respuestas que puedes encontrar.

Solución de problemas

Situaciones habituales y cómo resolverlas.

Soporte

¿Necesitas acceso a la API, límites más altos o activar el pago con saldo? Contacta con nosotros.