Time Status API

Get status information for addresses in Host Mode — all addresses for your account, or a single address.

There are two endpoints:

POST /apiv2/time/status — status for all your addresses (with optional pagination and account-level summary).
GET /apiv2/time/status/{address} — status for one specific address.

POST /apiv2/time/status

Endpoint URL

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

Authentication

Provide your API key in the request body (api_key) or the X-API-KEY header. The request IP must be in the whitelist configured for your API key.

Request Body

json

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

Parameter	Type	Required	Description
api_key	string	Yes	API key (or `X-API-KEY` header).
page	integer	No	Page number, ≥ 1. Requires `page_size`.
page_size	integer	No	Addresses per page, 1–100. Requires `page`.

Pagination: if page and page_size are both provided, results are paginated and a pagination object is included. Without them, all addresses are returned (up to 1000), sorted by creation time (newest first).

Example Requests

cURL (all addresses):

bash

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

cURL (paginated):

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

Response

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

With pagination, data also contains:

json

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

Summary fields

Field	Description
total_addresses	Number of addresses under your account
active_addresses	Addresses currently active
infinity_mode_count	Active addresses running in infinity mode
total_cycles_ordered	Sum of ordered cycles across open orders (infinity orders excluded)
total_open_orders	Number of open orders across all addresses

order_statistics fields

Field	Description
total_orders	All orders ever created
open_orders	Currently open orders
closed_orders	Closed orders
total_cycles_in_open_orders	Cycles across open orders (infinity excluded)
total_delegations	Delegations actually performed across all your addresses
total_amount_spent	Actually charged, in TRX — the sum really deducted from your balance

Address object fields

Field	Type	Description
address	string	TRON address
status	string	`"active"` or `"inactive"`
mode	string	`"normal"`, `"infinity"`, or `"off"` (when inactive)
cycles_ordered	integer \| null	Ordered cycles in open orders. `null` in infinity mode
cycle_set	integer	`cycle_set` value stored for the address
cycles_completed	integer	Cycles used since the address was last started. Resets when you stop the mode or the ordered cycles run out
cycles_remaining	integer \| null	`cycles_ordered − cycles_completed`. `null` in infinity mode
cycles_total_lifetime	integer	All delegations for this address over its whole history. Never reset
current_cycle_no	integer \| null	Position of the current delegation since the address was last started. `null` when no delegation is active
open_orders	integer	Number of open orders for the address
total_spent	number	Actually charged for this address, in TRX
bandwidth_delegated	boolean	Whether bandwidth is currently delegated. Bandwidth is free and included in the cycle price
created_at	string	ISO timestamp when added
updated_at	string	ISO timestamp of last update

Infinity mode. cycles_ordered and cycles_remaining are null, not 0 — there is no limit to count down. Treat null as “unlimited”, and do not read it as “no cycles left”. cycles_completed still reports a real number.

Three cycle counters, three meanings. cycles_completed counts only since the address was last started, cycles_total_lifetime counts its whole history, and current_cycle_no is the position of the current delegation. They are expected to differ — for one address you may see 83, 115 and 5 at the same time.

Errors

All errors use code = -1:

msg	Cause
`API key required in body or X-API-KEY header`	No API key provided
`Invalid API key or IP not in whitelist`	Authentication failed
`Page number must be >= 1`	`page` is below 1
`Page size must be >= 1`	`page_size` is below 1
`Page size must be <= 100`	`page_size` is above 100
`Database error getting status`	Temporary server-side error — retry
`Internal server error`	Unexpected error — retry or contact support

GET /apiv2/time/status/

Status for a single address.

Endpoint URL

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

Authentication

Send your API key in the X-API-KEY header. The request IP must be whitelisted.

Example Request

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

Response

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 uses the same fields as the address object above.

Errors

code = -1, for example:

msg	Cause
`API key required in X-API-KEY header`	Missing header
`Invalid API key or IP not in whitelist`	Authentication failed
`Address not found or doesn't belong to user`	Unknown address for this account
`Database error getting address status`	Temporary server-side error — retry
`Internal server error`	Unexpected error — retry or contact support

HTTP status codes

Both endpoints return their errors with HTTP 200 and a negative code — check code, not the HTTP status. Error bodies always include "data": null.

Some errors are returned before the request reaches the endpoint. They use a non-200 status and a different body shape:

HTTP	Body	Cause
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	Account balance is too low
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	The API key is blocked — contact support
422	`{"detail": [ … ]}`	POST only — request body failed validation: a field has the wrong type, or `page`/`page_size` were sent without `api_key`. Note there is no `code` field in this response

POST /apiv2/time/add — add an address
POST /apiv2/time/order — buy cycles
POST /apiv2/time/infinitystart — enable infinity mode
POST /apiv2/time/stop — stop an address
POST /apiv2/time/delete — remove an address

Notes

The status endpoints are read-only.
Only addresses belonging to your account are returned.
Timestamps are ISO 8601 strings.

Time Status API ​

POST /apiv2/time/status ​

Endpoint URL ​

Authentication ​

Request Body ​

Example Requests ​

Response ​

Summary fields ​

order_statistics fields ​

Address object fields ​

Errors ​

GET /apiv2/time/status/ ​

Endpoint URL ​

Authentication ​

Example Request ​

Response ​

Errors ​

HTTP status codes ​

Related Endpoints ​

Notes ​

Time Status API

POST /apiv2/time/status

Endpoint URL

Authentication

Request Body

Example Requests

Response

Summary fields

order_statistics fields

Address object fields

Errors

GET /apiv2/time/status/

Endpoint URL

Authentication

Example Request

Response

Errors

HTTP status codes

Related Endpoints

Notes