POST /apiv2/time/add

Adicione um endereço TRON ao Host Mode e, opcionalmente, registre uma URL de callback para notificações de delegação.

URL do endpoint

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

Autenticação

Forneça sua chave de API no corpo da requisição (api_key) ou no cabeçalho X-API-KEY. O IP da requisição deve estar na whitelist configurada para sua chave de API.

Corpo da requisição

json

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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim*	Chave de API. Também pode ser enviada no cabeçalho `X-API-KEY`.
address	string	Sim	Endereço TRON (TRC-20), deve corresponder a `^T[1-9A-HJ-NP-Za-km-z]{33}$` (começa com `T`, 34 caracteres).
callback_url	string	Não	URL HTTP/HTTPS pública para notificar quando a energia for delegada ao endereço. Máximo de 2048 caracteres.
infinity	boolean	Não	`true` — também alterna o endereço diretamente para o modo infinity, economizando uma chamada separada para `/apiv2/time/infinitystart`. O padrão é `false`.

* Obrigatório no corpo, a menos que o cabeçalho X-API-KEY seja utilizado.

Validação de callback_url: deve ser http/https, apenas um host público (localhost, intervalos privados RFC1918, link-local 169.254.0.0/16, IPv6 privado/link-local, endereços reservados e multicast são rejeitados) e ter no máximo 2048 caracteres.

Comportamento

Se o endereço for novo, ele será adicionado ao Host Mode com o status inativo (status = 0, cycle_set = 0). Ative-o posteriormente com /apiv2/time/order ou /apiv2/time/infinitystart.
Se o endereço já existir sob sua conta, a chamada atualizará sua URL de callback.
Se callback_url for fornecida, ela será armazenada (ou atualizada) para aquele endereço.

infinity

Com "infinity": true o endereço é adicionado e ativado no modo infinity em uma única chamada — o mesmo resultado de chamar /apiv2/time/add e depois /apiv2/time/infinitystart. A cobrança é idêntica à chamada separada: nada é cobrado neste momento, e os ciclos são cobrados um a um conforme a energia é delegada. Veja Host Mode → Ciclos e Preços.

Adicionar o endereço e ativá-lo são duas etapas separadas, e apenas a primeira é garantida. A resposta relata o resultado da adição. Se o endereço foi adicionado mas não pôde ser ativado, a chamada ainda retorna code: 0 com a mensagem habitual — o endereço simplesmente permanece inativo, exatamente como se você não tivesse passado o parâmetro. A ativação é ignorada quando:

seu saldo não cobre um ciclo no preço atual;
o endereço já está ativo;
o endereço já possui um pedido em aberto.

A resposta é a mesma com e sem o parâmetro — sem campos adicionais, sem códigos de erro extras, e ela não informa se o modo infinity foi de fato ativado. Confirme com Time Status: o endereço reporta status: "active" e mode: "infinity", e o ID do pedido está nessa resposta. Não trate code: 0 deste endpoint como prova de que o modo está em execução.

Exemplos de Requisição

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));

Resposta

Sucesso (novo endereço)

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"
    }
}

Sucesso (URL de callback atualizada para um endereço 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 da Resposta

Campo	Tipo	Descrição
code	integer	`0` = sucesso, negativo = erro
msg	string	Mensagem legível
data.address	string	O endereço que foi adicionado/atualizado
data.callback_url	string \| null	A URL de callback registrada (`null` se nenhuma)
data.timestamp	string	Timestamp ISO da operação

Respostas de Erro

Todos os erros utilizam code = -1 e descrevem o problema em msg:

msg	Causa
`API key required in X-API-KEY header or request body`	Nenhuma chave de API fornecida
`Invalid API key or IP not in whitelist`	Falha na autenticação
`Invalid TRC-20 address format`	O endereço não corresponde ao formato obrigatório
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	URL de callback rejeitada pela validação
`Address belongs to another user`	O endereço está registrado sob uma conta diferente
`Database error adding/updating address`	Erro temporário no servidor — tente novamente
`Internal server error`	Erro inesperado — tente novamente ou contate o suporte

json

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

Códigos de status HTTP

Erros de endpoint são retornados com HTTP 200 e um code negativo — verifique code, não o status HTTP. Corpos de erro sempre incluem "data": null.

Alguns erros são retornados antes que a requisição alcance o endpoint. Eles utilizam um status diferente de 200 e um formato de corpo diferente:

HTTP	Corpo	Causa
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	O saldo da conta é muito baixo
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	A chave de API está bloqueada — contate o suporte
422	`{"detail": [ … ]}`	O corpo da requisição falhou na validação: um campo obrigatório está ausente ou tem o tipo incorreto. Note que não há campo `code` nesta resposta

Callbacks (webhooks)

Se você registrou uma callback_url, o sistema a chamará cada vez que a energia for delegada ao endereço (isto é, uma vez por ciclo de delegação conforme for processado).

Formato da requisição

O sistema envia uma requisição HTTP GET com parâmetros de query:

Um ciclo originado de uma transferência de 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

Um ciclo sem transferência anterior — 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	Descrição
address	O endereço TRON que recebeu a delegação de energia
order_id	Identificador da delegação (`T` + id de delegação interno) — único por delegação
hash	Hash da transação on-chain da delegação de energia
balance_after	O saldo da sua conta em TRX logo após esta cobrança (snapshot no momento da cobrança; pode ter mudado até o momento em que o callback chega)
idle_cycle	`1` — esta delegação foi emitida após 24 horas sem transferência (redelegação ociosa), `0` — um ciclo regular originado de sua transferência ou ativação
energy_used	Faixa tarifária da energia consumida pela transferência que gerou este ciclo: `65k` (65.000 de energia ou menos → 2 TRX) ou `131k` (mais de 65.000 → 4 TRX). Opcional — a chave é totalmente omitida da query string (não enviada vazia) quando não houve transferência anterior para medir: a primeira delegação de uma ativação, toda redelegação ociosa e um endereço sem histórico de consumo ainda. Todos esses são cobrados na tarifa de 4 TRX
charged	Valor em TRX cobrado por este ciclo — `2.0000` ou `4.0000`, correspondendo à tarifa em `energy_used`. Sempre presente, inclusive quando `energy_used` é omitido. Veja Host Mode → Ciclos e Preços

Use order_id e hash para distinguir uma delegação de outra e para reconciliar com seus próprios registros — dois callbacks para o mesmo endereço diferem por esses valores. Use charged para acompanhar os gastos por ciclo sem consultar /apiv2/time/status, e energy_used para ver em qual tarifa a transferência anterior se enquadrou. Leia energy_used como um parâmetro opcional — uma chave ausente significa "nenhuma transferência para medir", não um erro, e nunca assuma um valor padrão para ela.

Exemplo de handler (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

Comportamento de entrega

Método: GET, timeout ~10 segundos. Retorne HTTP 200 para confirmar.
Tentativas de reenvio: até 3 tentativas são feitas se a requisição falhar; se todas falharem, o callback é descartado (a delegação de energia ainda ocorre independentemente).
Sem assinatura: a requisição não é assinada pela Netts. O segredo (se houver) é o que você incorporou em sua própria callback_url.
Reconciliação: como os callbacks podem ser perdidos, consulte também /apiv2/time/status e torne seu handler idempotente.

Atualizando / removendo o callback

Atualizar: chame /apiv2/time/add novamente com o mesmo endereço e uma nova callback_url.
Remover: chame /apiv2/time/delete para remover o endereço (isso também remove seu callback); readicione sem callback_url se necessário.

Endpoints Relacionados

POST /apiv2/time/order — comprar ciclos (ativa o endereço)
POST /apiv2/time/infinitystart — ativar o modo infinity
POST /apiv2/time/status — verificar status e ciclos
POST /apiv2/time/stop — parar o Host Mode
POST /apiv2/time/delete — remover o endereço

Notas

Novos endereços começam inativos; ative-os com um pedido, com infinity start ou passando "infinity": true aqui.
O mesmo endereço não pode ser registrado sob duas contas diferentes.
O endereço deve ser ativado na rede TRON antes de ser adicionado.

POST /apiv2/time/add ​

URL do endpoint ​

Autenticação ​

Corpo da requisição ​

Parâmetros ​

Comportamento ​

infinity ​

Exemplos de Requisição ​

cURL ​

Python ​

Node.js ​

Resposta ​

Sucesso (novo endereço) ​

Sucesso (URL de callback atualizada para um endereço existente) ​

Campos da Resposta ​

Respostas de Erro ​

Códigos de status HTTP ​

Callbacks (webhooks) ​

Formato da requisição ​

Exemplo de handler (Python / Flask) ​

Comportamento de entrega ​

Atualizando / removendo o callback ​

Endpoints Relacionados ​

Notas ​

POST /apiv2/time/add

URL do endpoint

Autenticação

Corpo da requisição

Parâmetros

Comportamento

infinity

Exemplos de Requisição

cURL

Python

Node.js

Resposta

Sucesso (novo endereço)

Sucesso (URL de callback atualizada para um endereço existente)

Campos da Resposta

Respostas de Erro

Códigos de status HTTP

Callbacks (webhooks)

Formato da requisição

Exemplo de handler (Python / Flask)

Comportamento de entrega

Atualizando / removendo o callback

Endpoints Relacionados

Notas