POST /apiv2/time/add

Añade una dirección TRON a Host Mode y, opcionalmente, registra una URL de callback para notificaciones de delegación y pausa.

URL del endpoint

POST https://netts.io/apiv2/time/add

Autenticación

Proporcione su clave de API en el cuerpo de la solicitud (api_key) o en el encabezado X-API-KEY. La IP de la solicitud debe estar en la lista blanca configurada para su clave de API.

Cuerpo de solicitud

json

{
    "api_key": "your_api_key",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",
    "infinity": true
}

Parámetros de solicitud

Parámetro	Tipo	Requerido	Descripción
api_key	string	Sí*	Clave de API. También se puede enviar en el encabezado `X-API-KEY`.
address	string	Sí	Dirección TRON (TRC-20), debe coincidir con `^T[1-9A-HJ-NP-Za-km-z]{33}$` (comienza con `T`, 34 caracteres).
callback_url	string	No	URL pública HTTP/HTTPS para notificar cuando se delega Energy a la dirección y cuando se desactiva el Host Mode para la dirección. Máximo 2048 caracteres.
infinity	boolean	No	`true` — también cambia la dirección directamente al modo infinity, ahorrando una llamada separada a `/apiv2/time/infinitystart`. El valor predeterminado es `false`.

* Requerido en el cuerpo a menos que se utilice el encabezado X-API-KEY.

Validación de callback_url: debe ser http/https, solo un host público (se rechazan localhost, rangos privados RFC1918, link-local 169.254.0.0/16, IPv6 privadas/link-local, direcciones reservadas y multidifusión), y un máximo de 2048 caracteres.

Comportamiento

Si la dirección es nueva, se añade a Host Mode con el estado inactiva (status = 0, cycle_set = 0). Actívela más tarde con /apiv2/time/order o /apiv2/time/infinitystart.
Si la dirección ya existe en su cuenta, la llamada actualiza su URL de callback.
Si se proporciona callback_url, se almacena (o actualiza) para esa dirección.

infinity

Con "infinity": true, la dirección se añade y se activa en modo infinity en una sola llamada — el mismo resultado que llamar a /apiv2/time/add y luego a /apiv2/time/infinitystart. La facturación es idéntica a la de la llamada por separado: no se cobra nada en este punto y los ciclos se cobran uno a uno a medida que se delega Energy. Consulte Host Mode → Ciclos y precios.

Añadir la dirección y activarla son dos pasos separados, y solo el primero está garantizado. La respuesta informa el resultado de la adición. Si la dirección se añadió pero no se pudo activar, la llamada aún devuelve code: 0 con el mensaje habitual — la dirección simplemente se deja inactiva, exactamente igual que si no hubiera pasado el parámetro. La activación se omite cuando:

su saldo no cubre un ciclo al precio actual;
la dirección ya está activa;
la dirección ya tiene una orden abierta.

La respuesta es la misma con y sin el parámetro — sin campos adicionales, sin códigos de error adicionales, y no le indica si el modo infinity se activó realmente. Confírmelo con Time Status: la dirección reporta status: "active" y mode: "infinity", y el ID de la orden se encuentra en esa respuesta. No trate code: 0 de este endpoint como prueba de que el modo está en ejecución.

Ejemplos

cURL

bash

curl -X POST https://netts.io/apiv2/time/add \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/time/add"
data = {
    "api_key": "YOUR_API_KEY_HERE",
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "callback_url": "https://your-server.com/webhook",  # optional
    # "infinity": True,  # optional: also switch the address into infinity mode
}

resp = requests.post(url, json=data, timeout=30)
result = resp.json()

if result["code"] == 0:
    print("Added:", result["data"]["address"])
else:
    print("Error:", result["msg"])

Node.js

javascript

const axios = require('axios');

const data = {
    api_key: 'YOUR_API_KEY_HERE',
    address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
    // callback_url: 'https://your-server.com/webhook', // optional
    // infinity: true, // optional: also switch the address into infinity mode
};

axios.post('https://netts.io/apiv2/time/add', data)
    .then(({ data: result }) => {
        if (result.code === 0) console.log('Added:', result.data.address);
        else console.error('Error:', result.msg);
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

Respuesta

Éxito (nueva dirección)

json

{
    "code": 0,
    "msg": "Address added to Host Mode successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://your-server.com/webhook",
        "timestamp": "2026-07-13T05:30:15.123456"
    }
}

Éxito (URL de callback actualizada para una dirección existente)

json

{
    "code": 0,
    "msg": "Address callback URL updated successfully",
    "data": {
        "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "callback_url": "https://new-webhook.com/endpoint",
        "timestamp": "2026-07-13T05:35:20.789012"
    }
}

Campos de respuesta

Campo	Tipo	Descripción
code	integer	`0` = éxito, negativo = error
msg	string	Mensaje legible por humanos
data.address	string	La dirección que fue añadida/actualizada
data.callback_url	string \| null	La URL de callback registrada (`null` si no hay ninguna)
data.timestamp	string	Marca de tiempo ISO de la operación

Respuestas de error

Todos los errores utilizan code = -1 y describen el problema en msg:

msg	Causa
`API key required in X-API-KEY header or request body`	No se proporcionó ninguna clave de API
`Invalid API key or IP not in whitelist`	La autenticación falló
`Invalid TRC-20 address format`	La dirección no coincide con el formato requerido
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	URL de callback rechazada por validación
`Address belongs to another user`	La dirección está registrada en una cuenta diferente
`Database error adding/updating address`	Error temporal del lado del servidor — reintente
`Internal server error`	Error inesperado — reintente o contacte a soporte

json

{ "code": -1, "msg": "Invalid API key or IP not in whitelist", "data": null }

Códigos de estado HTTP

Los errores del endpoint se devuelven con HTTP 200 y un code negativo — verifique code, no el estado HTTP. Los cuerpos de error siempre incluyen "data": null.

Algunos errores se devuelven antes de que la solicitud llegue al endpoint. Utilizan un estado distinto de 200 y una estructura de cuerpo diferente:

HTTP	Cuerpo	Causa
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	El saldo de la cuenta es demasiado bajo
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	La clave de API está bloqueada — contacte a soporte
422	`{"detail": [ … ]}`	El cuerpo de la solicitud no superó la validación: falta un campo obligatorio o tiene un tipo incorrecto. Tenga en cuenta que no hay ningún campo `code` en esta respuesta

Dirección de destino no permitida (403)

La dirección se verifica antes de añadirse. Si no se permite la delegación de recursos a ella, la solicitud se rechaza con HTTP 403 y no se escribe nada — la dirección no se añade ni se activa. El cuerpo utiliza la estructura detail:

code	msg	Significado
1006	`Address is blocked. Contact support.`	La dirección está bloqueada
1007	`Energy rental to smart contracts is not supported.`	La dirección es un contrato inteligente (las direcciones de billeteras GasFree también son contratos inteligentes)
1010	`Resource delegation to this address is not available.`	La delegación a esta dirección no está disponible
1011	`This address is frozen and cannot receive resource delegation.`	La dirección está congelada

json

{ "detail": { "code": 1007, "msg": "Energy rental to smart contracts is not supported." } }

Callbacks (webhooks)

Si registró una callback_url, el sistema la llama cada vez que se delega Energy a la dirección (es decir, una vez por ciclo de delegación a medida que se procesa), y una vez cada vez que se desactiva el Host Mode para la dirección — consulte Evento de host pausado.

Formato de solicitud

El sistema envía una solicitud HTTP GET con parámetros de consulta:

Un ciclo originado a partir de una transferencia USDT — energy_used presente:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149936&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=142.3500&idle_cycle=0&energy_used=65k&charged=2.0000

Un ciclo sin transferencia previa — energy_used omitido:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

Parámetro	Descripción
address	La dirección TRON que recibió la delegación de Energy
order_id	Identificador de la delegación (`T` + id de delegación interno) — único por delegación
hash	Hash de transacción en cadena de la delegación de Energy
balance_after	El saldo de su cuenta en TRX inmediatamente después de este cobro (instantánea al momento del cobro; puede haber cambiado en el momento en que llega el callback)
idle_cycle	`1` — esta delegación se emitió después de 24 horas sin transferencias (redelegación por inactividad), `0` — un ciclo regular originado a partir de su transferencia o activación
energy_used	Tramo de tarifa de la Energy consumida por la transferencia que produjo este ciclo: `65k` (65,000 de Energy o menos → 2 TRX) o `131k` (más de 65,000 → 4 TRX). Opcional — la clave se omite completamente de la cadena de consulta (no se envía vacía) cuando no hubo transferencia previa para medir: la primera delegación de una activación, cada redelegación por inactividad y una dirección sin historial de consumo aún. Todas ellas se cobran a la tarifa de 4 TRX
charged	Cantidad en TRX cobrada por este ciclo — `2.0000` o `4.0000`, coincidiendo con la tarifa en `energy_used`. Siempre presente, incluso cuando se omite `energy_used`. Consulte Host Mode → Ciclos y precios

Utilice order_id y hash para distinguir una delegación de otra y conciliar con sus propios registros — dos callbacks para la misma dirección difieren por estos valores. Utilice charged para realizar un seguimiento del gasto por ciclo sin sondear /apiv2/time/status, y energy_used para ver en qué tarifa cayó la transferencia anterior. Lea energy_used como un parámetro opcional — una clave faltante significa "no hay transferencia para medir", no un error, y nunca asuma un valor predeterminado para ella.

Evento de host pausado

La misma callback_url se llama cuando Host Mode para la dirección se desactiva (pasa a estar inactivo), sea cual sea la razón:

GET https://your-server.com/webhook?event=host_paused&address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&reason=idle&paused_at=2026-09-13T11:16:58Z&balance=418.0000

Parámetro	Descripción
event	Siempre `host_paused` para esta notificación
address	La dirección TRON cuyo Host Mode fue desactivado
reason	Por qué se desactivó el modo — consulte la tabla a continuación
paused_at	Cuándo se desactivó el modo, ISO-8601 UTC
balance	El saldo de su cuenta en TRX en ese momento, 4 decimales

reason	Significado
`idle`	2 días consecutivos de inactividad — dos ciclos de 24 horas cerrados sin una transferencia (consulte Host Mode → Apagado por inactividad)
`cycles_exhausted`	Todos los ciclos ordenados se han utilizado
`no_balance`	Su saldo no fue suficiente para cobrar un ciclo o la recarga del mínimo diario
`stopped`	El modo se detuvo con `/apiv2/time/stop`, o se desactivó por cualquier otra razón

Cómo diferenciar las dos notificaciones: solo la notificación de pausa tiene el parámetro event; solo la notificación de delegación tiene order_id y hash. El formato de la notificación de delegación no cambia.

Después de una pausa, la dirección permanece en Host Mode con su URL de callback; actívela de nuevo con /apiv2/time/order o /apiv2/time/infinitystart. La entrega funciona de la misma manera que para las notificaciones de delegación.

Ejemplo de controlador (Python / Flask)

python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['GET'])
def energy_delegation_webhook():
    address = request.args.get('address')
    order_id = request.args.get('order_id')
    tx_hash = request.args.get('hash')
    charged = request.args.get('charged')          # TRX charged for this cycle
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key may be absent)

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    if request.args.get('event') == 'host_paused':
        # Host Mode switched off: reason = idle | cycles_exhausted | no_balance | stopped
        print(f"Host Mode paused: address={address} reason={request.args.get('reason')} "
              f"paused_at={request.args.get('paused_at')} balance={request.args.get('balance')}")
        return jsonify({"status": "success"}), 200

    # Your business logic (idempotent by order_id / hash)
    print(f"Energy delegated: address={address} order_id={order_id} hash={tx_hash} "
          f"charged={charged} energy_used={energy_used}")
    return jsonify({"status": "success"}), 200

Comportamiento de entrega

Método: GET, tiempo de espera ~10 segundos. Devuelva HTTP 200 para confirmar la recepción.
Reintentos: se realizan hasta 3 intentos si la solicitud falla; si todos fallan, el callback se descarta (la delegación de Energy aún ocurre independientemente de esto).
Sin firma: la solicitud no está firmada por Netts. El secreto (si lo hay) es el que haya incrustado en su propia callback_url.
Conciliación: debido a que los callbacks pueden perderse, también sondee /apiv2/time/status y haga que su controlador sea idempotente.

Actualizar / eliminar el callback

Actualizar: llame a /apiv2/time/add nuevamente con la misma dirección y una nueva callback_url.
Eliminar: llame a /apiv2/time/delete para eliminar la dirección (esto también elimina su callback); vuelva a agregarla sin callback_url si es necesario.

Endpoints relacionados

POST /apiv2/time/order — comprar ciclos (activa la dirección)
POST /apiv2/time/infinitystart — habilitar el modo infinity
POST /apiv2/time/status — verificar estado y ciclos
POST /apiv2/time/stop — detener Host Mode
POST /apiv2/time/delete — eliminar la dirección

Notas

Las direcciones nuevas comienzan inactivas; actívelas con una orden, con inicio de infinity o pasando "infinity": true aquí.
La misma dirección no puede registrarse en dos cuentas diferentes.
La dirección debe estar activada en la red TRON antes de añadirla.
Los contratos inteligentes — incluidas las direcciones de billeteras GasFree — no se pueden añadir (HTTP 403, code 1007).

POST /apiv2/time/add ​

URL del endpoint ​

Autenticación ​

Cuerpo de solicitud ​

Parámetros de solicitud ​

Comportamiento ​

infinity ​

Ejemplos ​

cURL ​

Python ​

Node.js ​

Respuesta ​

Éxito (nueva dirección) ​

Éxito (URL de callback actualizada para una dirección existente) ​

Campos de respuesta ​

Respuestas de error ​

Códigos de estado HTTP ​

Dirección de destino no permitida (403) ​

Callbacks (webhooks) ​

Formato de solicitud ​

Evento de host pausado ​

Ejemplo de controlador (Python / Flask) ​

Comportamiento de entrega ​

Actualizar / eliminar el callback ​

Endpoints relacionados ​

Notas ​

POST /apiv2/time/add

URL del endpoint

Autenticación

Cuerpo de solicitud

Parámetros de solicitud

Comportamiento

infinity

Ejemplos

cURL

Python

Node.js

Respuesta

Éxito (nueva dirección)

Éxito (URL de callback actualizada para una dirección existente)

Campos de respuesta

Respuestas de error

Códigos de estado HTTP

Dirección de destino no permitida (403)

Callbacks (webhooks)

Formato de solicitud

Evento de host pausado

Ejemplo de controlador (Python / Flask)

Comportamiento de entrega

Actualizar / eliminar el callback

Endpoints relacionados

Notas