Time Status API

Obtenha informações de status para endereços no Host Mode — todos os endereços da sua conta ou um único endereço.

Existem dois endpoints:

POST /apiv2/time/status — status de todos os seus endereços (com paginação opcional e resumo no nível da conta).
GET /apiv2/time/status/{address} — status de um endereço específico.

POST /apiv2/time/status

URL do endpoint

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

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 lista de permissões configurada para sua chave de API.

Corpo da requisição

json

{
    "api_key": "your_api_key",
    "page": 1,
    "page_size": 50
}

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Sim	Chave de API (ou cabeçalho `X-API-KEY`).
page	integer	Não	Número da página, ≥ 1. Requer `page_size`.
page_size	integer	Não	Endereços por página, 1–100. Requer `page`.

Paginação: se page e page_size forem fornecidos, os resultados serão paginados e um objeto pagination será incluído. Sem eles, todos os endereços são retornados (até 1000), ordenados pelo horário de criação (mais recentes primeiro).

Exemplos

cURL (todos os endereços):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE" }'

cURL (paginado):

bash

curl -X POST https://netts.io/apiv2/time/status \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_API_KEY_HERE", "page": 1, "page_size": 50 }'

Python:

python

import requests

resp = requests.post(
    "https://netts.io/apiv2/time/status",
    json={"api_key": "YOUR_API_KEY_HERE"},  # add "page"/"page_size" to paginate
    timeout=30,
)
result = resp.json()

if result["code"] == 0:
    for a in result["data"]["addresses"]:
        # cycles_remaining is None in infinity mode — no limit to count down
        left = "unlimited" if a["cycles_remaining"] is None else f"{a['cycles_remaining']} left"
        print(a["address"], a["mode"], a["status"], left,
              f"spent {a['total_spent']} TRX")
else:
    print("Error:", result["msg"])

Node.js:

javascript

const axios = require('axios');

axios.post('https://netts.io/apiv2/time/status', { api_key: 'YOUR_API_KEY_HERE' })
    .then(({ data: result }) => {
        if (result.code === 0) {
            result.data.addresses.forEach(a => {
                // cycles_remaining is null in infinity mode — no limit to count down
                const left = a.cycles_remaining === null ? 'unlimited' : `${a.cycles_remaining} left`;
                console.log(a.address, a.mode, a.status, left, `spent ${a.total_spent} TRX`);
            });
        } else {
            console.error('Error:', result.msg);
        }
    })
    .catch(err => console.error('Request failed:', err.response?.data || err.message));

Resposta

json

{
    "code": 0,
    "msg": "Status retrieved successfully",
    "data": {
        "summary": {
            "total_addresses": 3,
            "active_addresses": 2,
            "infinity_mode_count": 1,
            "total_cycles_ordered": 25,
            "total_open_orders": 3
        },
        "order_statistics": {
            "total_orders": 12,
            "open_orders": 3,
            "closed_orders": 9,
            "total_cycles_in_open_orders": 25,
            "total_delegations": 340,
            "total_amount_spent": 1502.4471
        },
        "addresses": [
            {
                "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
                "status": "active",
                "mode": "normal",
                "cycles_ordered": 25,
                "cycle_set": 25,
                "cycles_completed": 10,
                "cycles_remaining": 15,
                "cycles_total_lifetime": 214,
                "current_cycle_no": 3,
                "open_orders": 1,
                "total_spent": 962.1184,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T12:00:00.000000",
                "updated_at": "2026-07-09T10:00:00.000000"
            },
            {
                "address": "TYn8Y3khEsLJW2ChVWFMSMeRDow6KcbMTF",
                "status": "active",
                "mode": "infinity",
                "cycles_ordered": null,
                "cycle_set": 0,
                "cycles_completed": 83,
                "cycles_remaining": null,
                "cycles_total_lifetime": 115,
                "current_cycle_no": 5,
                "open_orders": 1,
                "total_spent": 519.1234,
                "bandwidth_delegated": true,
                "created_at": "2026-07-08T08:00:00.000000",
                "updated_at": "2026-07-09T09:30:00.000000"
            }
        ],
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

Com paginação, data também contém:

json

"pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
}

Campos de summary

Campo	Descrição
total_addresses	Número de endereços na sua conta
active_addresses	Endereços atualmente ativos
infinity_mode_count	Endereços ativos operando no modo infinity
total_cycles_ordered	Soma dos ciclos pedidos em pedidos abertos (pedidos infinity excluídos)
total_open_orders	Número de pedidos abertos em todos os endereços

Campos de order_statistics

Campo	Descrição
total_orders	Todos os pedidos já criados
open_orders	Pedidos atualmente abertos
closed_orders	Pedidos encerrados
total_cycles_in_open_orders	Ciclos em pedidos abertos (infinity excluído)
total_delegations	Delegações efetivamente realizadas em todos os seus endereços
total_amount_spent	Efetivamente cobrado, em TRX — a quantia realmente deduzida do seu saldo

Campos do objeto Address

Campo	Tipo	Descrição
address	string	Endereço TRON
status	string	`"active"` ou `"inactive"`
mode	string	`"normal"`, `"infinity"` ou `"off"` (quando inativo)
cycles_ordered	integer \| null	Ciclos pedidos em pedidos abertos. `null` no modo infinity
cycle_set	integer	Valor de `cycle_set` armazenado para o endereço
cycles_completed	integer	Ciclos utilizados desde a última inicialização do endereço. É reiniciado quando você interrompe o modo ou quando os ciclos pedidos se esgotam
cycles_remaining	integer \| null	`cycles_ordered − cycles_completed`. `null` no modo infinity
cycles_total_lifetime	integer	Todas as delegações para este endereço ao longo de todo o seu histórico. Nunca é reiniciado
current_cycle_no	integer \| null	Posição da delegação atual desde a última inicialização do endereço. `null` quando nenhuma delegação está ativa
open_orders	integer	Número de pedidos abertos para o endereço
total_spent	number	Valor efetivamente cobrado para este endereço, em TRX
bandwidth_delegated	boolean	Indica se a largura de banda (Bandwidth) está delegada no momento. A Bandwidth é gratuita e está incluída no preço do ciclo
created_at	string	Timestamp ISO de quando foi adicionado
updated_at	string	Timestamp ISO da última atualização

Modo infinity. cycles_ordered e cycles_remaining são null, e não 0 — não há limite para contagem regressiva. Trate null como “ilimitado” e não o interprete como “sem ciclos restantes”. cycles_completed ainda informa um número real.

Três contadores de ciclos, três significados. cycles_completed conta apenas desde a última inicialização do endereço, cycles_total_lifetime conta todo o seu histórico e current_cycle_no é a posição da delegação atual. Espera-se que eles sejam diferentes — para um mesmo endereço, você pode ver 83, 115 e 5 simultaneamente.

Erros

Todos os erros usam code = -1:

msg	Causa
`API key required in body or X-API-KEY header`	Nenhuma chave de API fornecida
`Invalid API key or IP not in whitelist`	Falha na autenticação
`Page number must be >= 1`	`page` é menor que 1
`Page size must be >= 1`	`page_size` é menor que 1
`Page size must be <= 100`	`page_size` é maior que 100
`Database error getting status`	Erro temporário do lado do servidor — tente novamente
`Internal server error`	Erro inesperado — tente novamente ou entre em contato com o suporte

GET /apiv2/time/status/

Status de um único endereço.

URL do endpoint

GET https://netts.io/apiv2/time/status/{address}

Autenticação

Envie sua chave de API no cabeçalho X-API-KEY. O IP da requisição deve estar na lista de permissões.

Exemplo de Requisição

bash

curl -X GET "https://netts.io/apiv2/time/status/TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" \
  -H "X-API-KEY: YOUR_API_KEY_HERE"

python

import requests

address = "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
resp = requests.get(
    f"https://netts.io/apiv2/time/status/{address}",
    headers={"X-API-KEY": "YOUR_API_KEY_HERE"},
    timeout=30,
)
print(resp.json())

Resposta

json

{
    "code": 0,
    "msg": "Address status retrieved successfully",
    "data": {
        "address_info": {
            "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
            "status": "active",
            "mode": "normal",
            "cycles_ordered": 25,
            "cycle_set": 25,
            "cycles_completed": 10,
            "cycles_remaining": 15,
            "cycles_total_lifetime": 214,
            "current_cycle_no": 3,
            "open_orders": 1,
            "total_spent": 962.1184,
            "bandwidth_delegated": true,
            "created_at": "2026-07-08T12:00:00.000000",
            "updated_at": "2026-07-09T10:00:00.000000"
        },
        "timestamp": "2026-07-09T12:34:50.123456"
    }
}

address_info utiliza os mesmos campos do objeto de endereço acima.

Erros

code = -1, por exemplo:

msg	Causa
`API key required in X-API-KEY header`	Cabeçalho ausente
`Invalid API key or IP not in whitelist`	Falha na autenticação
`Address not found or doesn't belong to user`	Endereço desconhecido para esta conta
`Database error getting address status`	Erro temporário do lado do servidor — tente novamente
`Internal server error`	Erro inesperado — tente novamente ou entre em contato com o suporte

Códigos de status HTTP

Ambos os endpoints retornam seus erros 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 de a requisição atingir o endpoint. Eles utilizam um status diferente de 200 e um formato de corpo distinto:

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": [ … ]}`	Apenas POST — o corpo da requisição falhou na validação: um campo possui o tipo incorreto ou `page`/`page_size` foram enviados sem `api_key`. Observe que não há campo `code` nesta resposta

Endpoints Relacionados

POST /apiv2/time/add — adicionar um endereço
POST /apiv2/time/order — comprar ciclos
POST /apiv2/time/infinitystart — habilitar o modo infinity
POST /apiv2/time/stop — parar um endereço
POST /apiv2/time/delete — remover um endereço

Notas

Os endpoints de status são somente leitura.
Apenas os endereços pertencentes à sua conta são retornados.
Os timestamps são strings no formato ISO 8601.

Time Status API ​

POST /apiv2/time/status ​

URL do endpoint ​

Autenticação ​

Corpo da requisição ​

Exemplos ​

Resposta ​

Campos de summary ​

Campos de order_statistics ​

Campos do objeto Address ​

Erros ​

GET /apiv2/time/status/ ​

URL do endpoint ​

Autenticação ​

Exemplo de Requisição ​

Resposta ​

Erros ​

Códigos de status HTTP ​

Endpoints Relacionados ​

Notas ​

Time Status API

POST /apiv2/time/status

URL do endpoint

Autenticação

Corpo da requisição

Exemplos

Resposta

Campos de summary

Campos de order_statistics

Campos do objeto Address

Erros

GET /apiv2/time/status/

URL do endpoint

Autenticação

Exemplo de Requisição

Resposta

Erros

Códigos de status HTTP

Endpoints Relacionados

Notas