POST /apiv2/time/add

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

URL del endpoint

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

Autenticación

Proporciona tu clave 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 tu clave API.

Cuerpo de solicitud

json

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

Parámetros

Parámetro	Tipo	Requerido	Descripción
api_key	string	Sí*	Clave 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 a la que notificar cuando se delegue Energy a 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 use el encabezado X-API-KEY.

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

Comportamiento

Si la dirección es nueva, se añade a Host Mode con estado inactivo (status = 0, cycle_set = 0). Actívala más tarde con /apiv2/time/order o /apiv2/time/infinitystart.
Si la dirección ya existe en tu 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 llamada separada: no se cobra nada en este momento, y los ciclos se cobran uno por uno a medida que se delega Energy. Consulta Host Mode → Cycles and Pricing.

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

tu 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 te indica si el modo infinity fue realmente activado. Confírmalo con Time Status: la dirección reporta status: "active" y mode: "infinity", y el ID de la orden se encuentra en esa respuesta. No trates code: 0 de este endpoint como prueba de que el modo está en ejecución.

Ejemplos de solicitudes

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 usan code = -1 y describen el problema en msg:

msg	Causa
`API key required in X-API-KEY header or request body`	No se proporcionó clave 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 la 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 — reintenta
`Internal server error`	Error inesperado — reintenta o contacta con 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 — comprueba 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 API está bloqueada — contacta con soporte
422	`{"detail": [ … ]}`	El cuerpo de la solicitud no superó la validación: falta un campo obligatorio o tiene un tipo incorrecto. Ten en cuenta que no hay un campo `code` en esta respuesta

Callbacks (webhooks)

Si registraste 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 conforme se procesa).

Formato de la 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 delegación (`T` + ID de delegación interna) — único por delegación
hash	Hash de transacción on-chain de la delegación de Energy
balance_after	El saldo de tu cuenta en TRX inmediatamente después de este cobro (instantánea al momento del cobro; puede haber cambiado para cuando llegue 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 tu transferencia o activación
energy_used	Tramo tarifario 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 una 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 todavía. 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`. Consulta Host Mode → Cycles and Pricing

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

Manejador de ejemplo (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

    # 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. Devuelve 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 sigue ocurriendo de todos modos).
Sin firma: la solicitud no está firmada por Netts. El secreto (si lo hay) es el que hayas incrustado en tu propia callback_url.
Conciliación: debido a que los callbacks pueden perderse, consulta también por sondeo a /apiv2/time/status y haz que tu manejador sea idempotente.

Actualizar / eliminar el callback

Actualizar: llama a /apiv2/time/add de nuevo con la misma dirección y una nueva callback_url.
Eliminar: llama a /apiv2/time/delete para eliminar la dirección (esto también elimina su callback); vuelve a añadirla 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 — consultar estado y ciclos
POST /apiv2/time/stop — detener Host Mode
POST /apiv2/time/delete — eliminar la dirección

Notas

Las nuevas direcciones comienzan inactivas; actívalas con una orden, con infinity start o pasando "infinity": true aquí.
La misma dirección no se puede registrar en dos cuentas diferentes.
La dirección debe estar activada en la red TRON antes de añadirla.

POST /apiv2/time/add ​

URL del endpoint ​

Autenticación ​

Cuerpo de solicitud ​

Parámetros ​

Comportamiento ​

infinity ​

Ejemplos de solicitudes ​

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 ​

Callbacks (webhooks) ​

Formato de la solicitud ​

Manejador de ejemplo (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

Comportamiento

infinity

Ejemplos de solicitudes

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

Callbacks (webhooks)

Formato de la solicitud

Manejador de ejemplo (Python / Flask)

Comportamiento de entrega

Actualizar / eliminar el callback

Endpoints relacionados

Notas