POST /apiv2/time/add

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

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 a 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 pública HTTP/HTTPS para notificar quando a Energy for delegada ao endereço e quando o Host Mode para o endereço for desativado. 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 usado.

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

Comportamento

Se o endereço for novo, ele será adicionado ao Host Mode com status inativo (status = 0, cycle_set = 0). Ative-o posteriormente com /apiv2/time/order ou /apiv2/time/infinitystart.
Se o endereço já existir em sua conta, a chamada atualizará a URL de callback.
Se callback_url for fornecida, ela será armazenada (ou atualizada) para esse 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. O faturamento é idêntico ao da chamada separada: nada é cobrado neste momento, e os ciclos são cobrados um a um conforme a Energy é delegada. Consulte Host Mode → Cycles and Pricing.

Adicionar o endereço e ativá-lo são duas etapas separadas, e apenas a primeira é garantida. A resposta informa o resultado da adição. Se o endereço foi adicionado, mas não pôde ser ativado, a chamada ainda retornará code: 0 com a mensagem habitual — o endereço é simplesmente deixado 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 aberto.

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

Exemplos de Requisições

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 para humanos
data.address	string	O endereço que foi adicionado/atualizado
data.callback_url	string \| null	A URL de callback registrada (`null` se não houver)
data.timestamp	string	Timestamp ISO da operação

Respostas de Erro

Todos os erros usam 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 em uma conta diferente
`Database error adding/updating address`	Erro temporário do lado do servidor — tente novamente
`Internal server error`	Erro inesperado — tente novamente ou entre em contato com o suporte

json

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

Códigos de status HTTP

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

Alguns erros são retornados antes que a requisição chegue ao endpoint. Eles usam 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 — entre em contato com 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

Endereço de destino não permitido (403)

O endereço é verificado antes de ser adicionado. Se a delegação de recursos para ele não for permitida, a requisição será rejeitada com HTTP 403 e nada será gravado — o endereço não é adicionado nem ativado. O corpo usa o formato detail:

code	msg	Significado
1006	`Address is blocked. Contact support.`	O endereço está bloqueado
1007	`Energy rental to smart contracts is not supported.`	O endereço é um contrato inteligente (endereços de carteira GasFree também são contratos inteligentes)
1010	`Resource delegation to this address is not available.`	A delegação de recursos para este endereço não está disponível
1011	`This address is frozen and cannot receive resource delegation.`	O endereço está congelado

json

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

Callbacks (webhooks)

Se você registrou uma callback_url, o sistema a chamará sempre que a Energy for delegada ao endereço (ou seja, uma vez por ciclo de delegação conforme ele é processado), e uma vez a cada momento em que o Host Mode para o endereço for desativado — consulte Evento de host pausado.

Formato da requisição

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

Um ciclo originado de uma transferência 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 prévia — 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 Energy
order_id	Identificador da delegação (`T` + ID interno da delegação) — único por delegação
hash	Hash da transação on-chain da delegação de Energy
balance_after	O saldo da sua conta em TRX logo após esta cobrança (snapshot no momento da cobrança; pode ter mudado no momento em que o callback chegar)
idle_cycle	`1` — esta delegação foi emitida após 24 horas sem transferência (redelegação ociosa), `0` — um ciclo regular originado da sua transferência ou ativação
energy_used	Faixa de tarifa da Energy consumida pela transferência que gerou este ciclo: `65k` (65.000 de Energy 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, cada redelegação ociosa e um endereço sem histórico de consumo ainda. Todas essas são cobradas à taxa 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` for omitido. Consulte Host Mode → Cycles and Pricing

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

Evento de host pausado

A mesma callback_url é chamada quando o Host Mode para o endereço é desativado (torna-se inativo), qualquer que seja o motivo:

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	Descrição
event	Sempre `host_paused` para esta notificação
address	O endereço TRON cujo Host Mode foi desativado
reason	Por que o modo foi desativado — veja a tabela abaixo
paused_at	Quando o modo foi desativado, ISO-8601 UTC
balance	O saldo da sua conta em TRX naquele momento, 4 casas decimais

reason	Significado
`idle`	2 dias ociosos consecutivos — dois ciclos de 24 horas encerrados sem transferência (consulte Host Mode → Idle shutdown)
`cycles_exhausted`	Todos os ciclos contratados foram utilizados
`no_balance`	Seu saldo não foi suficiente para cobrar um ciclo ou a recarga daily minimum
`stopped`	O modo foi interrompido com `/apiv2/time/stop` ou desativado por qualquer outro motivo

Como diferenciar as duas notificações: somente a notificação de pausa possui o parâmetro event; apenas a notificação de delegação possui order_id e hash. O formato da notificação de delegação permanece inalterado.

Após uma pausa, o endereço permanece no Host Mode com sua URL de callback; reative-o com /apiv2/time/order ou /apiv2/time/infinitystart. A entrega funciona da mesma forma que para as notificações de delegação.

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

Comportamento de entrega

Método: GET, timeout de ~10 segundos. Retorne HTTP 200 para confirmação.
Tentativas: até 3 tentativas são feitas caso a requisição falhe; se todas falharem, o callback é descartado (a delegação de Energy continuará ocorrendo independentemente disso).
Sem assinatura: a requisição não é assinada pela Netts. O segredo (se houver) é o que você tiver embutido na sua própria callback_url.
Reconciliação: como callbacks podem ser perdidos, consulte também periodicamente /apiv2/time/status e torne seu manipulador 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); adicione novamente sem callback_url, se necessário.

Endpoints Relacionados

POST /apiv2/time/order — comprar ciclos (ativa o endereço)
POST /apiv2/time/infinitystart — habilitar 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.
Contratos inteligentes — incluindo endereços de carteira GasFree — não podem ser adicionados (HTTP 403, code 1007).

POST /apiv2/time/add ​

URL do endpoint ​

Autenticação ​

Corpo da requisição ​

Parâmetros ​

Comportamento ​

infinity ​

Exemplos de Requisições ​

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 ​

Endereço de destino não permitido (403) ​

Callbacks (webhooks) ​

Formato da requisição ​

Evento de host pausado ​

Exemplo de manipulador (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ções

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

Endereço de destino não permitido (403)

Callbacks (webhooks)

Formato da requisição

Evento de host pausado

Exemplo de manipulador (Python / Flask)

Comportamento de entrega

Atualizando / removendo o callback

Endpoints Relacionados

Notas