API Trạng thái Thời gian

Lấy thông tin trạng thái cho các địa chỉ trong Host Mode — tất cả địa chỉ cho tài khoản của bạn, hoặc một địa chỉ duy nhất.

Có hai endpoint:

POST /apiv2/time/status — trạng thái cho tất cả địa chỉ của bạn (với phân trang tùy chọn và tóm tắt cấp tài khoản).
GET /apiv2/time/status/{address} — trạng thái cho một địa chỉ cụ thể.

POST /apiv2/time/status

URL Endpoint

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

Xác thực

Cung cấp API key của bạn trong phần thân yêu cầu (api_key) hoặc tiêu đề X-API-KEY. IP yêu cầu phải nằm trong danh sách trắng được định cấu hình cho API key của bạn.

Body yêu cầu

json

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

Tham số	Loại	Bắt buộc	Mô tả
api_key	chuỗi	Có	API key (hoặc tiêu đề `X-API-KEY`).
page	số nguyên	Không	Số trang, ≥ 1. Yêu cầu `page_size`.
page_size	số nguyên	Không	Số địa chỉ trên mỗi trang, 1–100. Yêu cầu `page`.

Phân trang: nếu cả page và page_size đều được cung cấp, kết quả sẽ được phân trang và bao gồm đối tượng pagination. Nếu không có chúng, tất cả các địa chỉ sẽ được trả về (tối đa 1000), được sắp xếp theo thời gian tạo (mới nhất trước).

Ví dụ yêu cầu

cURL (tất cả địa chỉ):

bash

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

cURL (phân trang):

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

Phản hồi

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

Với phân trang, data cũng chứa:

json

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

Các trường summary

Trường	Mô tả
total_addresses	Số lượng địa chỉ thuộc tài khoản của bạn
active_addresses	Các địa chỉ hiện đang hoạt động
infinity_mode_count	Các địa chỉ hoạt động đang chạy ở infinity mode
total_cycles_ordered	Tổng số chu kỳ đã đặt trên các đơn hàng đang mở (không bao gồm các đơn hàng vô hạn)
total_open_orders	Số lượng đơn hàng đang mở trên tất cả các địa chỉ

Các trường order_statistics

Trường	Mô tả
total_orders	Tất cả các đơn hàng từng được tạo
open_orders	Các đơn hàng hiện đang mở
closed_orders	Các đơn hàng đã đóng
total_cycles_in_open_orders	Các chu kỳ trên các đơn hàng đang mở (không bao gồm vô hạn)
total_delegations	Các ủy quyền thực tế đã thực hiện trên tất cả các địa chỉ của bạn
total_amount_spent	Thực tế đã tính phí, tính bằng TRX — số tiền thực sự bị trừ khỏi số dư của bạn

Các trường đối tượng Address

Trường	Loại	Mô tả
address	chuỗi	Địa chỉ TRON
status	chuỗi	`"active"` hoặc `"inactive"`
mode	chuỗi	`"normal"`, `"infinity"`, hoặc `"off"` (khi không hoạt động)
cycles_ordered	số nguyên \| null	Các chu kỳ đã đặt trong các đơn hàng đang mở. `null` trong infinity mode
cycle_set	số nguyên	Giá trị `cycle_set` được lưu trữ cho địa chỉ
cycles_completed	số nguyên	Các chu kỳ đã sử dụng kể từ lần cuối địa chỉ được bắt đầu. Đặt lại khi bạn dừng chế độ hoặc các chu kỳ đã đặt hết
cycles_remaining	số nguyên \| null	`cycles_ordered − cycles_completed`. `null` trong infinity mode
cycles_total_lifetime	số nguyên	Tất cả các ủy quyền cho địa chỉ này trong toàn bộ lịch sử của nó. Không bao giờ đặt lại
current_cycle_no	số nguyên \| null	Vị trí của ủy quyền hiện tại kể từ lần cuối địa chỉ được bắt đầu. `null` khi không có ủy quyền nào hoạt động
open_orders	số nguyên	Số lượng đơn hàng đang mở cho địa chỉ
total_spent	số	Thực tế đã tính phí cho địa chỉ này, tính bằng TRX
bandwidth_delegated	boolean	Bandwidth hiện có được ủy quyền hay không. Bandwidth là miễn phí và được bao gồm trong giá chu kỳ
created_at	chuỗi	Dấu thời gian ISO khi được thêm
updated_at	chuỗi	Dấu thời gian ISO của lần cập nhật gần nhất

Infinity mode. cycles_ordered và cycles_remaining là null, không phải 0 — không có giới hạn để đếm ngược. Coi null là “không giới hạn”, và không hiểu nó là “không còn chu kỳ nào”. cycles_completed vẫn báo cáo một con số thực tế.

Ba bộ đếm chu kỳ, ba ý nghĩa. cycles_completed chỉ đếm kể từ lần cuối địa chỉ được bắt đầu, cycles_total_lifetime đếm toàn bộ lịch sử của nó, và current_cycle_no là vị trí của ủy quyền hiện tại. Chúng dự kiến sẽ khác nhau — đối với một địa chỉ, bạn có thể thấy 83, 115 và 5 cùng một lúc.

Lỗi

Tất cả các lỗi đều sử dụng code = -1:

msg	Nguyên nhân
`API key required in body or X-API-KEY header`	Không có API key được cung cấp
`Invalid API key or IP not in whitelist`	Xác thực thất bại
`Page number must be >= 1`	`page` nhỏ hơn 1
`Page size must be >= 1`	`page_size` nhỏ hơn 1
`Page size must be <= 100`	`page_size` lớn hơn 100
`Database error getting status`	Lỗi tạm thời phía máy chủ — thử lại
`Internal server error`	Lỗi không mong muốn — thử lại hoặc liên hệ bộ phận hỗ trợ

GET /apiv2/time/status/

Trạng thái cho một địa chỉ duy nhất.

URL Endpoint

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

Xác thực

Gửi API key của bạn trong tiêu đề X-API-KEY. IP yêu cầu phải nằm trong danh sách trắng.

Ví dụ yêu cầu

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

Phản hồi

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 sử dụng các trường tương tự như đối tượng address ở trên.

Lỗi

code = -1, ví dụ:

msg	Nguyên nhân
`API key required in X-API-KEY header`	Thiếu tiêu đề
`Invalid API key or IP not in whitelist`	Xác thực thất bại
`Address not found or doesn't belong to user`	Không tìm thấy địa chỉ cho tài khoản này
`Database error getting address status`	Lỗi tạm thời phía máy chủ — thử lại
`Internal server error`	Lỗi không mong muốn — thử lại hoặc liên hệ bộ phận hỗ trợ

Mã trạng thái HTTP

Cả hai endpoint đều trả về lỗi của chúng với HTTP 200 và một code âm — kiểm tra code, không phải trạng thái HTTP. Phần thân lỗi luôn bao gồm "data": null.

Một số lỗi được trả về trước khi yêu cầu đến được endpoint. Chúng sử dụng trạng thái khác 200 và cấu trúc phần thân khác:

HTTP	Thân	Nguyên nhân
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	Số dư tài khoản quá thấp
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API key bị chặn — liên hệ hỗ trợ
422	`{"detail": [ … ]}`	Chỉ POST — phần thân yêu cầu không qua được xác thực: một trường có loại không chính xác, hoặc `page`/`page_size` được gửi mà không có `api_key`. Lưu ý rằng không có trường `code` trong phản hồi này

Các endpoint liên quan

POST /apiv2/time/add — thêm một địa chỉ
POST /apiv2/time/order — mua chu kỳ
POST /apiv2/time/infinitystart — bật infinity mode
POST /apiv2/time/stop — dừng một địa chỉ
POST /apiv2/time/delete — xóa một địa chỉ

Ghi chú

Các endpoint trạng thái chỉ ở chế độ đọc.
Chỉ các địa chỉ thuộc về tài khoản của bạn mới được trả về.
Dấu thời gian là các chuỗi ISO 8601.

API Trạng thái Thời gian ​

POST /apiv2/time/status ​

URL Endpoint ​

Xác thực ​

Body yêu cầu ​

Ví dụ yêu cầu ​

Phản hồi ​

Các trường summary ​

Các trường order_statistics ​

Các trường đối tượng Address ​

Lỗi ​

GET /apiv2/time/status/ ​

URL Endpoint ​

Xác thực ​

Ví dụ yêu cầu ​

Phản hồi ​

Lỗi ​

Mã trạng thái HTTP ​

Các endpoint liên quan ​

Ghi chú ​

API Trạng thái Thời gian

POST /apiv2/time/status

URL Endpoint

Xác thực

Body yêu cầu

Ví dụ yêu cầu

Phản hồi

Các trường summary

Các trường order_statistics

Các trường đối tượng Address

Lỗi

GET /apiv2/time/status/

URL Endpoint

Xác thực

Ví dụ yêu cầu

Phản hồi

Lỗi

Mã trạng thái HTTP

Các endpoint liên quan

Ghi chú