POST /apiv2/time/add

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

URL Endpoint

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

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 (whitelist) được định cấu hình cho API key của bạn.

Thân yêu cầu (Request Body)

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	string	Có*	API key. Cũng có thể được gửi trong tiêu đề `X-API-KEY`.
address	string	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	string	Không	URL HTTP/HTTPS công khai để thông báo khi Energy được ủy quyền tới địa chỉ. Tối đa 2048 ký tự.
infinity	boolean	Không	`true` — đồng thời chuyển thẳng địa chỉ sang chế độ vô hạn (infinity mode), giúp tiết kiệm một lệnh gọi riêng biệt tới `/apiv2/time/infinitystart`. Mặc định là `false`.

* Bắt buộc trong phần thân 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 máy chủ công khai (localhost, các dải địa chỉ riêng RFC1918, link-local 169.254.0.0/16, địa chỉ IPv6 riêng/link-local, địa chỉ dành riêng và multicast đều bị từ chối), và độ dài tối đa là 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 sau bằng /apiv2/time/order hoặc /apiv2/time/infinitystart.
Nếu địa chỉ đã tồn tại dưới 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 trong chế độ infinity chỉ bằng một lệnh gọi — kết quả tương đương với việc gọi /apiv2/time/add rồi sau đó gọi /apiv2/time/infinitystart. Cách tính phí giống hệt với lệnh gọi riêng biệt: 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 chu kỳ một khi Energy đượ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ỉ bước đầu tiên là được đảm bảo. Phản hồi báo cáo kết quả của việc thêm. 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 với thông báo thông thường — địa chỉ chỉ đơn giản là được để ở 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ỳ ở mức giá hiện tại;
địa chỉ đã hoạt động;
địa chỉ đã có một đơn hàng mở.

Phản hồi là như nhau khi có hoặc không có cờ này — không có trường bổ sung, không có mã lỗi bổ sung, và nó không cho bạn biết liệu chế độ infinity đã thực sự được bật hay chưa. Hãy xác nhận điều đó bằng Time Status: địa chỉ sẽ 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	integer	`0` = thành công, số âm = lỗi
msg	string	Thông báo dạng văn bản cho người đọc
data.address	string	Địa chỉ đã được thêm/cập nhật
data.callback_url	string \| null	URL callback đã đăng ký (`null` nếu không có)
data.timestamp	string	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 bắt buộc
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	URL callback bị từ chối do xác thực thất bại
`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 phía máy chủ tạm thời — thử lại
`Internal server error`	Lỗi không mong đợi — 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. 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 mã trạng thái khác 200 và định dạng 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": [ … ]}`	Phần thân yêu cầu xác thực không thành công: một trường bắt buộc bị thiếu hoặc sai loại. Lưu ý không có trường `code` trong phản hồi này

Callbacks (webhooks)

Nếu bạn đã đăng ký một callback_url, hệ thống sẽ gọi nó mỗi khi Energy đượ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ý).

Đị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ỳ tạo ra 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 nào 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 Energy
order_id	Mã định danh ủy quyền (`T` + mã ủy quyền nội bộ) — duy nhất cho mỗi lần ủy quyền
hash	Mã hash giao dịch on-chain của lần ủy quyền Energy
balance_after	Số dư tài khoản của bạn tính bằng TRX ngay sau lần trừ phí này (ảnh chụp nhanh tại thời điểm trừ phí; nó có thể đã thay đổi vào thời điểm callback đến)
idle_cycle	`1` — ủy quyền này được cấp sau 24 giờ không có giao dịch chuyển nào (tái ủy quyền khi nhàn rỗi), `0` — một chu kỳ thông thường tạo ra từ giao dịch chuyển hoặc kích hoạt của bạn
energy_used	Khung biểu giá của Energy được tiêu thụ bởi giao dịch chuyển tạo ra chu kỳ này: `65k` (65.000 Energy hoặc ít hơn → 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 rỗng) khi không có giao dịch chuyển nào trước đó để đo lường: lần ủy quyền đầu tiên của một lần kích hoạt, mỗi lần tái ủy quyền nhàn rỗi, và một địa chỉ chưa có lịch sử tiêu thụ. Tất cả những trường hợp đó đều bị tính phí theo mức giá 4 TRX
charged	Số tiền tính bằng TRX bị trừ cho chu kỳ này — `2.0000` hoặc `4.0000`, khớp với biểu giá trong `energy_used`. Luôn luôn xuất hiệ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 các lần ủy quyền với nhau và để đối chiếu với hồ sơ của riêng bạn — hai callback cho cùng một địa chỉ sẽ khác nhau bởi các giá trị này. Sử dụng charged để theo dõi mức chi tiêu trên mỗi chu kỳ mà không cần thăm dò /apiv2/time/status, và energy_used để xem giao dịch chuyể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 — khóa bị thiếu nghĩa là "không có giao dịch chuyển để đo lường", không phải lỗi, và không bao giờ giả định một giá trị mặc định cho nó.

Trình xử lý mẫu (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

    # 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 phân phối

Phương thức: GET, thời gian chờ ~10 giây. Trả về HTTP 200 để xác nhận.
Thử lại: tối đa 3 lần thử lại được thực hiện 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 (ủy quyền Energy vẫn diễn ra 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ỳ nội dung gì bạn đã nhúng trong chính callback_url của mình.
Đối chiếu: vì callback có thể bị nhỡ, hãy thăm dò thêm /apiv2/time/status và xây dựng trình xử lý của bạn có tính chất lũy kế (idempotent).

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 nó); thêm lại mà không có 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 — kích hoạt chế độ infinity
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ỉ

Lưu ý

Các đị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 infinity, 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 TRON trước khi thêm nó.

POST /apiv2/time/add ​

URL Endpoint ​

Xác thực ​

Thân yêu cầu (Request Body) ​

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 ​

Callbacks (webhooks) ​

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

Trình xử lý mẫu (Python / Flask) ​

Hành vi phân phối ​

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

Các endpoint liên quan ​

Lưu ý ​

POST /apiv2/time/add

URL Endpoint

Xác thực

Thân yêu cầu (Request Body)

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

Callbacks (webhooks)

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

Trình xử lý mẫu (Python / Flask)

Hành vi phân phối

Cập nhật / xóa callback

Các endpoint liên quan

Lưu ý