POST /apiv2/order5m

Cree una orden de alquiler de energía de 5 minutos a través de los pools internos de energía de Netts.

URL del endpoint

POST https://netts.io/apiv2/order5m

Encabezados de solicitud

Header	Required	Description
Content-Type	Sí	application/json
X-API-KEY	Sí	Su clave de API del panel de control de Netts
X-Real-IP	Sí	Dirección IP de su lista blanca

Cuerpo de la solicitud

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Parámetros de solicitud

Parameter	Type	Required	Description
amount	integer	Sí	Cantidad de Energy a alquilar (mínimo: 61,000, máximo: 650,000)
receiveAddress	string	Sí	Dirección TRON que recibirá la energía (formato TRC-20)

Límites de Energy

El endpoint de 5 minutos acepta cantidades de energía entre 61,000 y 650,000 unidades por orden. Las solicitudes fuera de este rango serán rechazadas con HTTP 400.

Información del Proveedor

Las órdenes de energía de 5 minutos se completan exclusivamente a través de los pools internos de energía de Netts. A diferencia del endpoint de 1 hora, no se utilizan proveedores externos.

Disponibilidad y Estrategia de Reintento

Dado que las delegaciones provienen únicamente de pools internos, es posible que ocurra una indisponibilidad temporal durante períodos de alta demanda. Si recibe un error 503, reintente la solicitud tras una breve pausa o recurra al endpoint de 1 hora, el cual tiene acceso a múltiples proveedores externos.

Ejemplos

cURL

bash

curl -X POST https://netts.io/apiv2/order5m \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/order5m"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Respuesta

Respuesta Exitosa (200 OK)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Éxito con Activación de Dirección (200 OK)

Cuando la dirección receptora no ha sido activada en la red TRON, Netts la activa automáticamente. El costo de activación se añade al total:

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc..."
        }
    }
}

Campos de la Respuesta

Field	Type	Description
detail.code	integer	Siempre `10000` para órdenes exitosas
detail.msg	string	Mensaje de éxito con la cantidad deducida
detail.data.orderId	string	ID de orden unificado (formato: `5M{id}`)
detail.data.paidTRX	number	Costo total en TRX (incluye tarifa de activación si corresponde)
detail.data.hash	string	Hash de la transacción de delegación
detail.data.delegateAddress	string	Dirección del pool que delegó la energía
detail.data.energy	integer	Cantidad de Energy + margen adicional (normalmente +50)
detail.data.activationHash	string	Solo presente si se realizó la activación de la dirección

Respuestas de error

Cantidad de Energy Inválida (400)

json

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

Error de Autenticación (401)

json

{
    "detail": "Invalid API key or IP not in whitelist"
}

Saldo Insuficiente (403)

json

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

Servicio No Disponible (503)

json

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

Gestión de Errores 503

Una respuesta 503 significa que los pools internos están temporalmente al límite de su capacidad. Estrategia recomendada:

Espere de 2 a 3 segundos y reintente la orden de 5 minutos
Si sigue sin estar disponible, recurra al endpoint de 1 hora que utiliza múltiples proveedores

Error Interno del Servidor (500)

json

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Referencia de Códigos de Error

Code	Description	HTTP Status
`10000`	Éxito	200
`10000`	Éxito (respuesta en caché)	208
`-`	Solicitud duplicada aún en procesamiento	409
`1003`	Cantidad de Energy fuera de rango	400
`1004`	Saldo insuficiente	403
`1005`	Dirección pagadora del usuario no configurada	400
`5000`	Error interno del servidor	500
`5003`	Servicio de Energy no disponible	503

Límites de tasa

Los siguientes límites de tasa aplican a este endpoint (por dirección IP):

Period	Limit	Description
1 segundo	50 solicitudes	Máximo 50 solicitudes por segundo

Encabezados de Límite de Tasa

http

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Límite de Tasa Excedido (429)

json

{
    "message": "API rate limit exceeded"
}

Idempotencia

La API admite idempotencia para evitar el procesamiento de órdenes duplicadas. Cuando envía múltiples solicitudes idénticas, el sistema garantiza que la orden se procese solo una vez.

Cómo Funciona la Idempotencia

La singularidad de la solicitud se determina mediante una combinación de:

Marca de tiempo de la solicitud (ventana de 2 segundos)
Cantidad de Energy
Dirección receptora
Clave de API

Cada solicitud recibe una ventana de singularidad de 2 segundos. Las solicitudes con parámetros idénticos dentro de esta ventana se tratan como duplicadas.

Proporcionar Su Propia Clave

Puede gestionar la idempotencia por su cuenta enviando el encabezado X-Idempotency-Key. Cuando está presente, ese valor decide por sí solo si una solicitud es una repetición, y no se utiliza la combinación automática descrita arriba. Cuando está ausente, nada cambia: el servidor deduce la clave por usted.

Las reglas son las mismas que en /apiv2/order1h:


Encabezado	`X-Idempotency-Key`
Formato	Exactamente 64 caracteres hexadecimales en minúscula: un hash SHA-256
Duración	24 horas a partir de la primera solicitud que incluya esa clave
Alcance	Su cuenta. El mismo valor enviado por una cuenta diferente nunca devolverá su resultado

Una clave con cualquier otro formato —un UUID con guiones, base64, hexadecimal en mayúsculas— se rechaza con 400 antes de que se cree la orden y antes de que se realice cualquier cobro:

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

Deduzca la clave a partir de su clave de API para que sea exclusiva de su cuenta y reproducible en un reintento; el ejemplo práctico se encuentra en la página de 1 hora. Incluya el período de alquiler en el mensaje al que aplica el hash: alquilar para la misma dirección durante 5 minutos y durante 1 hora son órdenes diferentes, y reutilizar una misma clave para ambas devolverá la respuesta de la primera orden para la segunda solicitud.

Realizar Dos Órdenes Idénticas

La misma trampa que en el endpoint por horas, con una ventana más amplia. Dos órdenes idénticas —la misma cantidad a la misma dirección— son indistinguibles de un reintento, y únicamente el momento de llegada las diferencia.

Sin una clave propia:

Intervalo entre las dos solicitudes	Qué sucede
Dentro de la misma ventana de 2 segundos	La segunda solicitud se interpreta como una repetición. No se ejecuta: recibe `208` y la respuesta de la primera orden. No se cobra nada por ella
Separadas por más de dos segundos	Dos claves diferentes: ambas órdenes se crean y ambas se cobran

Por lo tanto, deje pasar más de dos segundos entre dos órdenes idénticas y lea el código de estado: 208 significa que la orden que acaba de enviar no se creó.

Una pausa es solo una solución provisional, no una solución definitiva; también separa las solicitudes que nunca pretendió repetir, como un reintento tras un tiempo de espera agotado o un mensaje reenviado por su cola, y cada una de ellas se convierte en una orden independiente con un cobro independiente. Enviar su propia clave es lo que realmente lo resuelve: un nuevo nonce para una nueva orden, el nonce del primer intento para un reintento. La explicación completa se encuentra en la página de 1 hora.

Códigos de Estado HTTP para Solicitudes Duplicadas

Status Code	Name	Description
200	OK	Orden procesada exitosamente (primera solicitud)
208	Already Reported	La orden ya fue procesada, devolviendo respuesta en caché
409	Conflict	La solicitud se está procesando actualmente, no reintente

Solicitud Duplicada - Ya Procesada (208)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

Solicitud Duplicada - Aún en Procesamiento (409)

json

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "retry_after_seconds": 3
}

Prácticas Recomendadas

No envíe solicitudes paralelas con los mismos parámetros; espere cada respuesta
Gestione las respuestas 409 esperando, no reintentando inmediatamente
Compruebe el campo idempotency.cached para identificar respuestas en caché

Comparación: Órdenes de 5 Minutos vs 1 Hora

Feature	Orden de 5 Minutos	Orden de 1 Hora
Endpoint	`/apiv2/order5m`	`/apiv2/order1h`
Duración	5 minutos	1 hora
Rango de Energy	61,000 - 650,000	61,000 - 3,000,000
Proveedores	Solo pools internos de Netts	Pools internos + proveedores externos
Precio	Más bajo (tarifa de 5 minutos)	Tarifa horaria estándar
Disponibilidad	Puede ser limitada en horas pico	Alta (respaldo de múltiples proveedores)
Ideal para	Transacciones pequeñas frecuentes	Entregas grandes o garantizadas

Notas

La Energy se entrega de forma instantánea al procesarse la orden con éxito (normalmente entre 0.5 y 2 segundos)
Tiempo de espera de respuesta de la API: Máximo 10 segundos (incluye intentos de reintento internos)
Activación de dirección: Si la dirección receptora no está activada, Netts la activa a precio de costo. El costo de activación se cobra solo una vez por dirección
Duración: Fija de 5 minutos (300 segundos)
Cantidad mínima de Energy: 61,000 unidades
Cantidad máxima de Energy: 650,000 unidades por orden
Margen adicional de Energy: +50 unidades añadidas automáticamente (sin cargo adicional)
Formato del ID de orden: 5M{id} para seguimiento unificado
Tarificación: Dinámica en función de la hora del día mediante la Pricing API
Límite de tasa: 50 solicitudes por segundo por dirección IP
Solo pools internos: Si los pools están al límite de su capacidad, reintente tras una breve pausa o utilice el endpoint de 1 hora como respaldo

POST /apiv2/order5m ​

URL del endpoint ​

Encabezados de solicitud ​

Cuerpo de la solicitud ​

Parámetros de solicitud ​

Información del Proveedor ​

Ejemplos ​

cURL ​

Python ​

Respuesta ​

Respuesta Exitosa (200 OK) ​

Éxito con Activación de Dirección (200 OK) ​

Campos de la Respuesta ​

Respuestas de error ​

Cantidad de Energy Inválida (400) ​

Error de Autenticación (401) ​

Saldo Insuficiente (403) ​

Servicio No Disponible (503) ​

Error Interno del Servidor (500) ​

Referencia de Códigos de Error ​

Límites de tasa ​

Encabezados de Límite de Tasa ​

Límite de Tasa Excedido (429) ​

Idempotencia ​

Cómo Funciona la Idempotencia ​

Proporcionar Su Propia Clave ​

Realizar Dos Órdenes Idénticas ​

Códigos de Estado HTTP para Solicitudes Duplicadas ​

Solicitud Duplicada - Ya Procesada (208) ​

Solicitud Duplicada - Aún en Procesamiento (409) ​

Prácticas Recomendadas ​

Comparación: Órdenes de 5 Minutos vs 1 Hora ​

Notas ​

POST /apiv2/order5m

URL del endpoint

Encabezados de solicitud

Cuerpo de la solicitud

Parámetros de solicitud

Información del Proveedor

Ejemplos

cURL

Python

Respuesta

Respuesta Exitosa (200 OK)

Éxito con Activación de Dirección (200 OK)

Campos de la Respuesta

Respuestas de error

Cantidad de Energy Inválida (400)

Error de Autenticación (401)

Saldo Insuficiente (403)

Servicio No Disponible (503)

Error Interno del Servidor (500)

Referencia de Códigos de Error

Límites de tasa

Encabezados de Límite de Tasa

Límite de Tasa Excedido (429)

Idempotencia

Cómo Funciona la Idempotencia

Proporcionar Su Propia Clave

Realizar Dos Órdenes Idénticas

Códigos de Estado HTTP para Solicitudes Duplicadas

Solicitud Duplicada - Ya Procesada (208)

Solicitud Duplicada - Aún en Procesamiento (409)

Prácticas Recomendadas

Comparación: Órdenes de 5 Minutos vs 1 Hora

Notas