POST /apiv2/time/add

Tambahkan alamat TRON ke Host Mode dan, secara opsional, daftarkan URL callback untuk notifikasi delegasi dan jeda.

URL Endpoint

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

Autentikasi

Berikan API key Anda di body permintaan (api_key) atau header X-API-KEY. IP permintaan harus berada dalam whitelist yang dikonfigurasikan untuk API key Anda.

Isi Permintaan

json

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

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
api_key	string	Ya*	API key. Dapat juga dikirimkan di header `X-API-KEY`.
address	string	Ya	Alamat TRON (TRC-20), harus cocok dengan `^T[1-9A-HJ-NP-Za-km-z]{33}$` (dimulai dengan `T`, 34 karakter).
callback_url	string	Tidak	URL HTTP/HTTPS publik untuk diberitahu ketika Energy didelegasikan ke alamat tersebut dan ketika Host Mode untuk alamat tersebut dimatikan. Maksimal 2048 karakter.
infinity	boolean	Tidak	`true` — juga langsung mengalihkan alamat ke infinity mode, menghemat panggilan terpisah ke `/apiv2/time/infinitystart`. Default ke `false`.

* Diperlukan di dalam body kecuali jika header X-API-KEY digunakan.

Validasi callback_url: harus berupa http/https, hanya host publik (localhost, rentang privat RFC1918, link-local 169.254.0.0/16, IPv6 privat/link-local, alamat yang dicadangkan dan multicast ditolak), dan paling banyak 2048 karakter.

Perilaku

Jika alamat tersebut baru, alamat akan ditambahkan ke Host Mode dengan status tidak aktif (status = 0, cycle_set = 0). Aktifkan nanti dengan /apiv2/time/order atau /apiv2/time/infinitystart.
Jika alamat tersebut sudah ada di akun Anda, panggilan ini akan memperbarui URL callback-nya.
Jika callback_url diberikan, URL tersebut disimpan (atau diperbarui) untuk alamat tersebut.

infinity

Dengan "infinity": true, alamat ditambahkan dan diaktifkan dalam mode infinity dalam satu panggilan — hasil yang sama seperti memanggil /apiv2/time/add lalu /apiv2/time/infinitystart. Penagihan identik dengan panggilan terpisah: tidak ada biaya yang ditagihkan pada tahap ini, dan siklus ditagih satu per satu saat Energy didelegasikan. Lihat Host Mode → Siklus dan Penetapan Harga.

Menambahkan alamat dan mengaktifkannya adalah dua langkah terpisah, dan hanya langkah pertama yang dijamin. Respons melaporkan hasil penambahan. Jika alamat telah ditambahkan tetapi tidak dapat diaktifkan, panggilan tetap mengembalikan code: 0 dengan pesan biasa — alamat tersebut dibiarkan tidak aktif, persis seperti jika Anda tidak memberikan flag tersebut. Pengaktifan dilewati saat:

saldo Anda tidak mencukupi untuk satu siklus pada harga saat ini;
alamat sudah aktif;
alamat sudah memiliki pesanan terbuka.

Responsnya sama dengan dan tanpa flag — tidak ada field tambahan, tidak ada kode error tambahan, dan ini tidak memberi tahu Anda apakah mode infinity benar-benar telah diaktifkan. Konfirmasikan hal ini dengan Time Status: alamat melaporkan status: "active" dan mode: "infinity", dan ID pesanan ada di dalam respons tersebut. Jangan menganggap code: 0 dari endpoint ini sebagai bukti bahwa mode tersebut sedang berjalan.

Contoh Permintaan

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

Respons

Berhasil (alamat baru)

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

Berhasil (URL callback diperbarui untuk alamat yang sudah ada)

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

Field Respons

Field	Tipe	Deskripsi
code	integer	`0` = sukses, negatif = error
msg	string	Pesan yang dapat dibaca manusia
data.address	string	Alamat yang telah ditambahkan/diperbarui
data.callback_url	string \| null	URL callback yang terdaftar (`null` jika tidak ada)
data.timestamp	string	Timestamp ISO dari operasi

Respons Error

Semua error menggunakan code = -1 dan menjelaskan masalahnya di msg:

msg	Penyebab
`API key required in X-API-KEY header or request body`	Tidak ada API key yang diberikan
`Invalid API key or IP not in whitelist`	Autentikasi gagal
`Invalid TRC-20 address format`	Alamat tidak cocok dengan format yang diperlukan
`Invalid callback URL. Only public HTTP/HTTPS URLs are allowed`	URL callback ditolak oleh validasi
`Address belongs to another user`	Alamat terdaftar di bawah akun lain
`Database error adding/updating address`	Error sisi server sementara — coba lagi
`Internal server error`	Error tak terduga — coba lagi atau hubungi dukungan

json

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

Kode status HTTP

Error endpoint dikembalikan dengan HTTP 200 dan code negatif — periksa code, bukan status HTTP. Body error selalu menyertakan "data": null.

Beberapa error dikembalikan sebelum permintaan mencapai endpoint. Error ini menggunakan status non-200 dan bentuk body yang berbeda:

HTTP	Body	Penyebab
402	`{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}`	Saldo akun terlalu rendah
403	`{"detail": {"code": 1005, "msg": "API key is blocked. Contact support."}}`	API key diblokir — hubungi dukungan
422	`{"detail": [ … ]}`	Body permintaan gagal validasi: field yang diperlukan hilang atau memiliki tipe yang salah. Perhatikan bahwa tidak ada field `code` dalam respons ini

Alamat tujuan tidak diizinkan (403)

Alamat diperiksa sebelum ditambahkan. Jika delegasi sumber daya ke alamat tersebut tidak diizinkan, permintaan ditolak dengan HTTP 403 dan tidak ada yang ditulis — alamat tidak ditambahkan dan tidak diaktifkan. Body menggunakan struktur detail:

code	msg	Arti
1006	`Address is blocked. Contact support.`	Alamat diblokir
1007	`Energy rental to smart contracts is not supported.`	Alamat tersebut merupakan smart contract (alamat dompet GasFree juga merupakan smart contract)
1010	`Resource delegation to this address is not available.`	Delegasi sumber daya ke alamat ini tidak tersedia
1011	`This address is frozen and cannot receive resource delegation.`	Alamat dibekukan dan tidak dapat menerima delegasi sumber daya

json

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

Callback (webhook)

Jika Anda mendaftarkan callback_url, sistem akan memanggilnya setiap kali Energy didelegasikan ke alamat tersebut (yaitu sekali per siklus delegasi saat diproses), dan sekali setiap kali Host Mode untuk alamat tersebut dimatikan — lihat Peristiwa Host dijeda.

Format permintaan

Sistem mengirimkan permintaan HTTP GET dengan parameter kueri:

Siklus yang lahir dari transfer USDT — energy_used ada:

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

Siklus tanpa transfer sebelumnya — energy_used dihilangkan:

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

Parameter	Deskripsi
address	Alamat TRON yang menerima delegasi Energy
order_id	Pengidentifikasi delegasi (`T` + ID delegasi internal) — unik per delegasi
hash	Hash transaksi on-chain dari delegasi Energy
balance_after	Saldo akun Anda dalam TRX tepat setelah pembebanan biaya ini (snapshot pada saat penagihan; saldo mungkin telah berubah saat callback tiba)
idle_cycle	`1` — delegasi ini dikeluarkan setelah 24 jam tanpa transfer (delegasi ulang saat idle), `0` — siklus reguler yang lahir dari transfer atau aktivasi Anda
energy_used	Rentang tarif dari Energy yang dikonsumsi oleh transfer yang menghasilkan siklus ini: `65k` (65.000 Energy atau kurang → 2 TRX) atau `131k` (lebih dari 65.000 → 4 TRX). Opsional — kunci dihilangkan dari query string sepenuhnya (tidak dikirim kosong) ketika tidak ada transfer sebelumnya untuk diukur: delegasi pertama dari suatu aktivasi, setiap delegasi ulang saat idle, dan alamat yang belum memiliki riwayat konsumsi. Semua itu dikenakan tarif 4 TRX
charged	Jumlah dalam TRX yang dibebankan untuk siklus ini — `2.0000` atau `4.0000`, sesuai dengan tarif di `energy_used`. Selalu ada, termasuk ketika `energy_used` dihilangkan. Lihat Host Mode → Siklus dan Penetapan Harga

Gunakan order_id dan hash untuk membedakan satu delegasi dari delegasi lainnya dan untuk mencocokkan dengan catatan Anda sendiri — dua callback untuk alamat yang sama dibedakan oleh nilai-nilai ini. Gunakan charged untuk melacak pengeluaran per siklus tanpa polling ke /apiv2/time/status, dan energy_used untuk melihat ke dalam tarif mana transfer sebelumnya masuk. Bacalah energy_used sebagai parameter opsional — kunci yang hilang berarti "tidak ada transfer untuk diukur", bukan error, dan jangan pernah mengasumsikan nilai default untuknya.

Peristiwa Host dijeda

callback_url yang sama dipanggil ketika Host Mode untuk alamat tersebut beralih menjadi mati (menjadi tidak aktif), apa pun alasannya:

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

Parameter	Deskripsi
event	Selalu `host_paused` untuk notifikasi ini
address	Alamat TRON yang Host Mode-nya dimatikan
reason	Alasan mengapa mode tersebut dimatikan — lihat tabel di bawah ini
paused_at	Waktu saat mode dimatikan, ISO-8601 UTC
balance	Saldo akun Anda dalam TRX pada saat itu, 4 desimal

reason	Arti
`idle`	2 hari idle berturut-turut — dua siklus 24 jam ditutup tanpa adanya transfer (lihat Host Mode → Penutupan idle)
`cycles_exhausted`	Semua siklus yang dipesan telah digunakan
`no_balance`	Saldo Anda tidak mencukupi untuk membebankan biaya siklus atau top-up minimum harian
`stopped`	Mode dihentikan dengan `/apiv2/time/stop`, atau dimatikan karena alasan lain

Cara membedakan kedua notifikasi: hanya notifikasi jeda yang memiliki parameter event; hanya notifikasi delegasi yang memiliki order_id dan hash. Format notifikasi delegasi tidak berubah.

Setelah jeda, alamat tetap berada di Host Mode beserta URL callback-nya; aktifkan kembali dengan /apiv2/time/order atau /apiv2/time/infinitystart. Pengiriman bekerja dengan cara yang sama seperti notifikasi delegasi.

Contoh handler (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

Perilaku pengiriman

Metode: GET, batas waktu ~10 detik. Kembalikan HTTP 200 untuk mengonfirmasi penerimaan.
Percobaan ulang: hingga 3 kali percobaan dilakukan jika permintaan gagal; jika semua gagal, callback akan diabaikan (delegasi Energy tetap terjadi bagaimanapun juga).
Tanpa tanda tangan: permintaan tidak ditandatangani oleh Netts. Rahasia (jika ada) adalah apa pun yang Anda sematkan di callback_url Anda sendiri.
Rekonsiliasi: karena callback dapat terlewat, lakukan juga polling /apiv2/time/status dan buat handler Anda idempoten.

Memperbarui / menghapus callback

Perbarui: panggil /apiv2/time/add lagi dengan alamat yang sama dan callback_url baru.
Hapus: panggil /apiv2/time/delete untuk menghapus alamat (ini juga menghapus callback-nya); tambahkan kembali tanpa callback_url jika diperlukan.

Endpoint Terkait

POST /apiv2/time/order — beli siklus (mengaktifkan alamat)
POST /apiv2/time/infinitystart — aktifkan infinity mode
POST /apiv2/time/status — periksa status dan siklus
POST /apiv2/time/stop — hentikan Host Mode
POST /apiv2/time/delete — hapus alamat

Catatan

Alamat baru dimulai dalam status tidak aktif; aktifkan dengan pesanan, dengan infinity start, atau dengan memberikan "infinity": true di sini.
Alamat yang sama tidak dapat didaftarkan di bawah dua akun yang berbeda.
Alamat harus sudah diaktifkan di jaringan TRON sebelum menambahkannya.
Smart contract — termasuk alamat dompet GasFree — tidak dapat ditambahkan (HTTP 403, code 1007).

POST /apiv2/time/add ​

URL Endpoint ​

Autentikasi ​

Isi Permintaan ​

Parameter ​

Perilaku ​

infinity ​

Contoh Permintaan ​

cURL ​

Python ​

Node.js ​

Respons ​

Berhasil (alamat baru) ​

Berhasil (URL callback diperbarui untuk alamat yang sudah ada) ​

Field Respons ​

Respons Error ​

Kode status HTTP ​

Alamat tujuan tidak diizinkan (403) ​

Callback (webhook) ​

Format permintaan ​

Peristiwa Host dijeda ​

Contoh handler (Python / Flask) ​

Perilaku pengiriman ​

Memperbarui / menghapus callback ​

Endpoint Terkait ​

Catatan ​

POST /apiv2/time/add

URL Endpoint

Autentikasi

Isi Permintaan

Parameter

Perilaku

infinity

Contoh Permintaan

cURL

Python

Node.js

Respons

Berhasil (alamat baru)

Berhasil (URL callback diperbarui untuk alamat yang sudah ada)

Field Respons

Respons Error

Kode status HTTP

Alamat tujuan tidak diizinkan (403)

Callback (webhook)

Format permintaan

Peristiwa Host dijeda

Contoh handler (Python / Flask)

Perilaku pengiriman

Memperbarui / menghapus callback

Endpoint Terkait

Catatan