POST /apiv2/time/add

Thêm một địa chỉ TRON vào Host Mode và tùy chọn đăng ký một URL callback để nhận thông báo ủy quyền và tạm dừng.

URL của Endpoint

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

Xác thực

Cung cấp API key của bạn trong body yêu cầu (api_key) hoặc tiêu đề X-API-KEY. IP gửi yêu cầu phải nằm trong whitelist được cấu hình cho API key của bạn.

Body của yêu cầu

json

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

Tham số

Tham số	Loại	Bắt buộc	Mô tả
api_key	chuỗi	Có*	API key. Cũng có thể gửi trong tiêu đề `X-API-KEY`.
address	chuỗi	Có	Địa chỉ TRON (TRC-20), phải khớp với `^T[1-9A-HJ-NP-Za-km-z]{33}$` (bắt đầu bằng `T`, 34 ký tự).
callback_url	chuỗi	Không	URL HTTP/HTTPS công khai để thông báo khi năng lượng được ủy quyền tới địa chỉ và khi Host Mode của địa chỉ bị tắt. Tối đa 2048 ký tự.
infinity	boolean	Không	`true` — đồng thời chuyển địa chỉ trực tiếp sang chế độ vô hạn, tiết kiệm một lệnh gọi riêng tới `/apiv2/time/infinitystart`. Mặc định là `false`.

* Bắt buộc trong body trừ khi tiêu đề X-API-KEY được sử dụng.

Xác thực callback_url: phải là http/https, chỉ chấp nhận host công khai (localhost, các dải mạng riêng tư RFC1918, link-local 169.254.0.0/16, IPv6 riêng tư/link-local, địa chỉ dành riêng và multicast sẽ bị từ chối), và tối đa 2048 ký tự.

Hành vi

Nếu địa chỉ là mới, nó sẽ được thêm vào Host Mode với trạng thái không hoạt động (status = 0, cycle_set = 0). Kích hoạt nó sau bằng /apiv2/time/order hoặc /apiv2/time/infinitystart.
Nếu địa chỉ đã tồn tại trong tài khoản của bạn, lệnh gọi sẽ cập nhật URL callback của địa chỉ đó.
Nếu callback_url được cung cấp, nó sẽ được lưu trữ (hoặc cập nhật) cho địa chỉ đó.

infinity

Với "infinity": true, địa chỉ sẽ được thêm và kích hoạt ở chế độ vô hạn trong một lệnh gọi duy nhất — mang lại kết quả tương tự như gọi /apiv2/time/add rồi gọi tiếp /apiv2/time/infinitystart. Cách tính phí giống hệt như lệnh gọi riêng: không có khoản phí nào bị trừ tại thời điểm này, và các chu kỳ sẽ được tính phí từng đợt một khi năng lượng được ủy quyền. Xem Host Mode → Chu kỳ và Giá cả.

Việc thêm địa chỉ và bật chế độ là hai bước riêng biệt, và chỉ có bước đầu tiên được đảm bảo. Phản hồi sẽ báo cáo kết quả của việc thêm địa chỉ. Nếu địa chỉ đã được thêm nhưng không thể bật chế độ, lệnh gọi vẫn trả về code: 0 cùng thông báo thông thường — địa chỉ đơn giản là vẫn ở trạng thái không hoạt động, hoàn toàn giống như khi bạn không truyền cờ này. Việc bật chế độ sẽ bị bỏ qua khi:

số dư của bạn không đủ để chi trả cho một chu kỳ theo mức giá hiện tại;
địa chỉ đã đang hoạt động;
địa chỉ đã có một đơn hàng đang mở.

Phản hồi là như nhau dù có hay không có cờ này — không có thêm trường dữ liệu nào, không có thêm mã lỗi nào, và nó không cho bạn biết liệu chế độ vô hạn đã thực sự được bật hay chưa. Hãy xác nhận điều đó với Trạng thái Thời gian: địa chỉ báo cáo status: "active" và mode: "infinity", kèm mã id đơn hàng nằm trong phản hồi đó. Đừng xem code: 0 từ endpoint này là bằng chứng cho thấy chế độ đang chạy.

Yêu cầu Mẫu

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

Phản hồi

Thành công (địa chỉ mới)

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

Thành công (URL callback đã được cập nhật cho một địa chỉ hiện có)

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

Các trường Phản hồi

Trường	Loại	Mô tả
code	số nguyên	`0` = thành công, số âm = lỗi
msg	chuỗi	Thông báo thân thiện cho người dùng
data.address	chuỗi	Địa chỉ đã được thêm/cập nhật
data.callback_url	chuỗi \| null	URL callback đã đăng ký (`null` nếu không có)
data.timestamp	chuỗi	Dấu thời gian ISO của thao tác

Phản hồi lỗi

Tất cả các lỗi đều sử dụng code = -1 và mô tả vấn đề trong msg:

msg	Nguyên nhân
`API key required in X-API-KEY header or request body`	Không có API key nào được cung cấp
`Invalid API key or IP not in whitelist`	Xác thực thất bại
`Invalid TRC-20 address format`	Địa chỉ không khớp với định dạng yêu cầu
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	URL callback bị từ chối khi xác thực
`Address belongs to another user`	Địa chỉ đã được đăng ký dưới một tài khoản khác
`Database error adding/updating address`	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ệ hỗ trợ

json

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

Mã trạng thái HTTP

Các lỗi endpoint được trả về với HTTP 200 và một code âm — hãy kiểm tra code, không phải trạng thái HTTP. Body 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 body khác:

HTTP	Body	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ị khóa — liên hệ hỗ trợ
422	`{"detail": [ … ]}`	Request body xác thực thất bại: thiếu một trường bắt buộc hoặc sai kiểu dữ liệu. Lưu ý rằng không có trường `code` trong phản hồi này

Địa chỉ đích không được phép (403)

Địa chỉ được kiểm tra trước khi thêm vào. Nếu việc ủy quyền tài nguyên cho địa chỉ đó không được phép, yêu cầu sẽ bị từ chối với HTTP 403 và không có gì được ghi lại — địa chỉ không được thêm vào và không được bật chế độ. Body sử dụng cấu trúc detail:

code	msg	Ý nghĩa
1006	`Address is blocked. Contact support.`	Địa chỉ bị khóa
1007	`Energy rental to smart contracts is not supported.`	Địa chỉ là hợp đồng thông minh (địa chỉ ví GasFree cũng là hợp đồng thông minh)
1010	`Resource delegation to this address is not available.`	Ủy quyền tài nguyên cho địa chỉ này không khả dụng
1011	`This address is frozen and cannot receive resource delegation.`	Địa chỉ bị đóng băng và không thể nhận ủy quyền tài nguyên

json

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

Callbacks (webhooks)

Nếu bạn đã đăng ký một callback_url, hệ thống sẽ gọi URL đó mỗi khi năng lượng được ủy quyền tới địa chỉ (tức là một lần cho mỗi chu kỳ ủy quyền khi nó được xử lý), và một lần mỗi khi Host Mode của địa chỉ bị tắt — xem Sự kiện Host tạm dừng.

Định dạng yêu cầu

Hệ thống gửi một yêu cầu HTTP GET với các tham số truy vấn:

Một chu kỳ phát sinh từ một giao dịch chuyển USDT — có energy_used:

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

Một chu kỳ không có giao dịch chuyển tiền trước đó — bỏ qua energy_used:

GET https://your-server.com/webhook?address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&order_id=T149937&hash=97b4eb0257088aefcb286229aa42ec750f27554390dd4e186f55efe273666577&balance_after=138.3500&idle_cycle=0&charged=4.0000

Tham số	Mô tả
address	Địa chỉ TRON đã nhận ủy quyền năng lượng
order_id	Mã định danh ủy quyền (`T` + id ủy quyền nội bộ) — duy nhất cho mỗi lần ủy quyền
hash	Mã băm giao dịch trên chuỗi (tx hash) của đợt ủy quyền năng lượng
balance_after	Số dư tài khoản của bạn tính bằng TRX ngay sau lần tính phí này (ảnh chụp nhanh tại thời điểm tính phí; có thể đã thay đổi vào thời điểm callback gửi tới)
idle_cycle	`1` — đợt ủy quyền này được cấp sau 24 giờ không có giao dịch chuyển tiền (ủy quyền lại khi không hoạt động), `0` — một chu kỳ thông thường phát sinh từ giao dịch chuyển tiền hoặc kích hoạt của bạn
energy_used	Khung giá của năng lượng được tiêu thụ bởi giao dịch chuyển tiền đã tạo ra chu kỳ này: `65k` (65.000 năng lượng trở xuống → 2 TRX) hoặc `131k` (nhiều hơn 65.000 → 4 TRX). Tùy chọn — khóa này bị bỏ qua hoàn toàn khỏi chuỗi truy vấn (không gửi giá trị rỗng) khi không có giao dịch chuyển tiền trước đó để đo lường: đợt ủy quyền đầu tiên của một lần kích hoạt, mỗi lần ủy quyền lại khi không hoạt động, và một địa chỉ chưa có lịch sử tiêu thụ. Tất cả các trường hợp đó đều bị tính phí theo mức 4 TRX
charged	Số tiền bằng TRX bị tính phí cho chu kỳ này — `2.0000` hoặc `4.0000`, khớp với khung giá trong `energy_used`. Luôn hiện diện, bao gồm cả khi `energy_used` bị bỏ qua. Xem Host Mode → Chu kỳ và Giá cả

Sử dụng order_id và hash để phân biệt đợt ủy quyền này với đợt ủy quyền khác và để đối chiếu với bản ghi của riêng bạn — hai callback cho cùng một địa chỉ sẽ khác nhau ở các giá trị này. Sử dụng charged để theo dõi chi tiêu cho mỗi chu kỳ mà không cần thăm dò /apiv2/time/status, và energy_used để xem giao dịch chuyển tiền trước đó rơi vào khung giá nào. Hãy đọc energy_used như một tham số tùy chọn — việc thiếu khóa này có nghĩa là "không có giao dịch chuyển tiền để đo lường", không phải là lỗi, và không bao giờ giả định một giá trị mặc định cho nó.

Sự kiện Host tạm dừng

Cùng một callback_url sẽ được gọi khi Host Mode của địa chỉ bị tắt (trở nên không hoạt động), bất kể lý do là gì:

GET https://your-server.com/webhook?event=host_paused&address=TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE&reason=idle&paused_at=2026-09-13T11:16:58Z&balance=418.0000

Tham số	Mô tả
event	Luôn là `host_paused` cho loại thông báo này
address	Địa chỉ TRON có Host Mode bị tắt
reason	Lý do chế độ bị tắt — xem bảng bên dưới
paused_at	Thời điểm chế độ bị tắt, theo định dạng ISO-8601 UTC
balance	Số dư tài khoản của bạn tính bằng TRX tại thời điểm đó, 4 chữ số thập phân

reason	Ý nghĩa
`idle`	2 ngày liên tiếp không hoạt động — hai chu kỳ 24 giờ kết thúc mà không có giao dịch chuyển tiền (xem Host Mode → Tắt khi không hoạt động)
`cycles_exhausted`	Tất cả các chu kỳ đã đặt hàng đều đã được sử dụng
`no_balance`	Số dư của bạn không đủ để chi trả cho một chu kỳ hoặc khoản nạp tối thiểu hàng ngày
`stopped`	Chế độ đã bị dừng bằng `/apiv2/time/stop`, hoặc bị tắt vì bất kỳ lý do nào khác

Cách phân biệt hai loại thông báo: chỉ thông báo tạm dừng mới có tham số event; chỉ thông báo ủy quyền mới có order_id và hash. Định dạng thông báo ủy quyền không thay đổi.

Sau khi tạm dừng, địa chỉ vẫn ở trong Host Mode cùng với URL callback của nó; bật lại bằng /apiv2/time/order hoặc /apiv2/time/infinitystart. Cơ chế gửi hoạt động theo cách tương tự như đối với thông báo ủy quyền.

Ví dụ trình xử lý (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

Hành vi gửi

Phương thức: GET, thời gian chờ ~10 giây. Trả về HTTP 200 để xác nhận đã nhận.
Thử lại: tối đa 3 lần thử lại nếu yêu cầu thất bại; nếu tất cả đều thất bại, callback sẽ bị hủy bỏ (việc ủy quyền năng lượng vẫn diễn ra bình thường bất kể điều đó).
Không có chữ ký: yêu cầu không được ký bởi Netts. Khóa bí mật (nếu có) là bất kỳ chuỗi nào bạn tự nhúng vào callback_url của mình.
Đối chiếu: vì callback có thể bị bỏ lỡ, hãy chủ động thăm dò /apiv2/time/status và xây dựng trình xử lý của bạn có tính chất idempotent (bảo toàn kết quả khi thực hiện nhiều lần).

Cập nhật / xóa callback

Cập nhật: gọi lại /apiv2/time/add với cùng địa chỉ và một callback_url mới.
Xóa: gọi /apiv2/time/delete để xóa địa chỉ (thao tác này cũng xóa callback của địa chỉ); thêm lại không kèm callback_url nếu cần.

Các Endpoint Liên quan

POST /apiv2/time/order — mua các chu kỳ (kích hoạt địa chỉ)
POST /apiv2/time/infinitystart — bật chế độ vô hạn
POST /apiv2/time/status — kiểm tra trạng thái và các chu kỳ
POST /apiv2/time/stop — dừng Host Mode
POST /apiv2/time/delete — xóa địa chỉ

Ghi chú

Địa chỉ mới bắt đầu ở trạng thái không hoạt động; kích hoạt chúng bằng một đơn hàng, bằng bắt đầu vô hạn, hoặc bằng cách truyền "infinity": true tại đây.
Cùng một địa chỉ không thể đăng ký dưới hai tài khoản khác nhau.
Địa chỉ nên được kích hoạt trên mạng lưới TRON trước khi thêm nó.
Hợp đồng thông minh — bao gồm cả địa chỉ ví GasFree — không thể thêm vào (HTTP 403, code 1007).

POST /apiv2/time/add ​

URL của Endpoint ​

Xác thực ​

Body của yêu cầu ​

Tham số ​

Hành vi ​

infinity ​

Yêu cầu Mẫu ​

cURL ​

Python ​

Node.js ​

Phản hồi ​

Thành công (địa chỉ mới) ​

Thành công (URL callback đã được cập nhật cho một địa chỉ hiện có) ​

Các trường Phản hồi ​

Phản hồi lỗi ​

Mã trạng thái HTTP ​

Địa chỉ đích không được phép (403) ​

Callbacks (webhooks) ​

Định dạng yêu cầu ​

Sự kiện Host tạm dừng ​

Ví dụ trình xử lý (Python / Flask) ​

Hành vi gửi ​

Cập nhật / xóa callback ​

Các Endpoint Liên quan ​

Ghi chú ​

POST /apiv2/time/add

URL của Endpoint

Xác thực

Body của yêu cầu

Tham số

Hành vi

infinity

Yêu cầu Mẫu

cURL

Python

Node.js

Phản hồi

Thành công (địa chỉ mới)

Thành công (URL callback đã được cập nhật cho một địa chỉ hiện có)

Các trường Phản hồi

Phản hồi lỗi

Mã trạng thái HTTP

Địa chỉ đích không được phép (403)

Callbacks (webhooks)

Định dạng yêu cầu

Sự kiện Host tạm dừng

Ví dụ trình xử lý (Python / Flask)

Hành vi gửi

Cập nhật / xóa callback

Các Endpoint Liên quan

Ghi chú