Alquilar energía

`POST /v2/energy/rent`

Cobra de tu saldo QvaPay y delega la energía a la dirección indicada.

Autenticación

Cabeceras app-id / app-secret, o Authorization: Bearer <token>.

Request

curl -X POST https://api.qvapay.com/v2/energy/rent \
  -H "app-id: tu-app-id" \
  -H "app-secret: tu-app-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "target_address": "TUo8pycbvje9w2XYsNnnzw67bpPs4GLFyD",
    "volume": 132000,
    "duration": "1h",
    "idempotency_key": "6f9c2a1e-3b7d-4c08-9f21-2e5a7c0b1d44",
    "quote_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
`target_address`	string	Sí	Dirección TRON que recibe la energía (la que firma el envío)
`volume`	number	Sí	Energía a alquilar: 32.000 – 5.000.000
`duration`	string	Sí	`1h`, `1d`, `3d` o `7d`
`idempotency_key`	string	Sí	8–64 caracteres `[A-Za-z0-9._-]`. Ver abajo
`quote_id`	string	No	Cotización congelada con `POST /v2/energy/quote`
`max_price_usd`	number	No	Sin `quote_id`: precio máximo que aceptas pagar

Manda siempre quote_id o max_price_usd. Sin ninguno de los dos aceptas el precio vivo sea cual sea, y la energía se mueve con la demanda de la red.

Idempotencia

idempotency_key es obligatoria y es lo que hace seguro reintentar.

Situación	Resultado
Misma clave, orden ya creada	`200` con la orden original y `duplicate: true`. No se cobra otra vez
Misma clave, petición todavía en curso	`409` `DUPLICATE_REQUEST`
Clave nueva	Orden nueva

Genera una clave nueva por cada compra, y reutiliza la misma al reintentar esa compra. Si una petición muere por timeout, repítela con la misma clave: o te devuelve la orden que sí se creó, o la crea. Nunca cobra dos veces.

Response — `201` entregada

{
  "data": {
    "uuid": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
    "resource": "energy",
    "target_address": "TUo8pycbvje9w2XYsNnnzw67bpPs4GLFyD",
    "volume": 132000,
    "duration": "1h",
    "price_usd": 1.00,
    "status": "completed",
    "order_id": "1H76d06176b8",
    "txid": "db47c131876a504ceee32f023a46cf3aa23629362e28c8c272c10ced8f1f27a8",
    "explorer": "https://tronscan.org/#/transaction/db47c131876a...",
    "created_at": "2026-09-18T19:12:00.000Z",
    "completed_at": "2026-09-18T19:12:03.000Z"
  },
  "balance": 42.31
}

Response — `202` en curso

El saldo ya se cobró y la entrega sigue en marcha. Consulta GET /v2/energy/orders/{uuid} hasta que quede en completed o refunded; lo normal es que tarde menos de un minuto.

{
  "data": { "uuid": "9c0d1e2f-...", "status": "dispatching", "txid": null },
  "balance": 42.31
}

Estados de una orden

Estado	Significa
`pending`	Cobrada, pendiente de entregar
`dispatching`	Entrega en curso. Se reintenta automáticamente
`completed`	Energía delegada. Trae `txid`
`refunded`	No se pudo entregar y te devolvimos el saldo
`needs_review`	La entrega no se resolvió y la está revisando nuestro equipo

Errores

Código	`code`	Descripción
`400`	`INVALID_ADDRESS`	La dirección TRON no es válida (se comprueba el checksum completo)
`400`	`INVALID_VOLUME` / `INVALID_DURATION`	Fuera de los valores admitidos
`400`	`INSUFFICIENT_BALANCE`	Saldo insuficiente
`403`	`LIMIT_EXCEEDED`	Superado el límite diario. La respuesta trae `remaining`
`403`	`SANCTIONS_BLOCKED`	No es posible completar la operación
`409`	`QUOTE_EXPIRED`	La cotización caducó; pide una nueva
`409`	`PRICE_ABOVE_MAX`	El precio vivo supera tu `max_price_usd`. Trae `price_usd`
`409`	`DUPLICATE_REQUEST`	Hay una petición idéntica en curso
`429`	`RATE_LIMITED`	Demasiadas solicitudes
`502`	`DELIVERY_FAILED`	No se pudo entregar; el saldo ya fue devuelto
`503`	`PROVIDER_UNAVAILABLE`	Servicio no disponible ahora mismo

Rate Limiting

3 requests cada 3 segundos por cuenta.

On this page