POST /apiv2/time/add

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

URL Endpoint

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

Autentikasi

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

Body Permintaan

json

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

Parameter

Parameter	Tipe	Wajib	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. Maksimal 2048 karakter.
infinity	boolean	Tidak	`true` — juga langsung mengalihkan alamat ke mode infinity, menghemat pemanggilan terpisah ke `/apiv2/time/infinitystart`. Default-nya adalah `false`.

* Wajib diisi 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 akan ditolak), serta maksimal 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, pemanggilan ini akan memperbarui URL callback-nya.
Jika callback_url disediakan, URL tersebut akan disimpan (atau diperbarui) untuk alamat tersebut.

infinity

Dengan "infinity": true, alamat ditambahkan dan diaktifkan dalam mode infinity dalam satu pemanggilan — hasil yang sama seperti memanggil /apiv2/time/add lalu /apiv2/time/infinitystart. Penagihannya identik dengan pemanggilan terpisah: tidak ada biaya yang ditagihkan pada tahap ini, dan siklus ditagihkan 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 berhasil ditambahkan tetapi tidak dapat diaktifkan, pemanggilan tetap mengembalikan code: 0 dengan pesan biasa — alamat tersebut dibiarkan tidak aktif, persis seperti jika Anda tidak menyertakan flag tersebut. Pengaktifan dilewati ketika:

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

Responsnya sama baik dengan maupun tanpa flag tersebut — tidak ada field tambahan, tidak ada kode kesalahan 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",  # opsional
    # "infinity": True,  # opsional: juga alihkan alamat ke mode infinity
}

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', // opsional
    // infinity: true, // opsional: juga alihkan alamat ke mode infinity
};

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` = berhasil, negatif = kesalahan
msg	string	Pesan yang dapat dibaca manusia
data.address	string	Alamat yang ditambahkan/diperbarui
data.callback_url	string \| null	URL callback yang terdaftar (`null` jika tidak ada)
data.timestamp	string	Timestamp ISO dari operasi

Respons Kesalahan

Semua kesalahan 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 yang berbeda
`Database error adding/updating address`	Kesalahan sementara di sisi server — coba lagi
`Internal server error`	Kesalahan yang tidak terduga — coba lagi atau hubungi dukungan

json

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

Kode status HTTP

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

Beberapa kesalahan dikembalikan sebelum permintaan mencapai endpoint. Kesalahan 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 divalidasi: field yang wajib diisi tidak ada atau memiliki tipe yang salah. Perhatikan bahwa tidak ada field `code` dalam respons ini

Callback (webhook)

Jika Anda mendaftarkan callback_url, sistem akan memanggilnya setiap kali energy didelegasikan ke alamat tersebut (yaitu sekali per siklus delegasi saat diproses).

Format permintaan

Sistem mengirimkan permintaan HTTP GET dengan parameter kueri:

Siklus yang dihasilkan 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 penagihan ini (snapshot pada saat penagihan; mungkin telah berubah saat callback tiba)
idle_cycle	`1` — delegasi ini diterbitkan setelah 24 jam tanpa transfer (delegasi ulang idle), `0` — siklus reguler yang dihasilkan dari transfer atau aktivasi Anda
energy_used	Kategori 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 — key ini dihilangkan sama sekali dari string kueri (tidak dikirim dalam keadaan kosong) ketika tidak ada transfer sebelumnya untuk diukur: delegasi pertama dari suatu aktivasi, setiap delegasi ulang idle, dan alamat yang belum memiliki riwayat konsumsi. Semuanya dikenakan biaya dengan tarif 4 TRX
charged	Jumlah dalam TRX yang ditagihkan 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 yang lain dan untuk mencocokkan dengan catatan Anda sendiri — dua callback untuk alamat yang sama berbeda berdasarkan nilai-nilai ini. Gunakan charged untuk melacak pengeluaran per siklus tanpa perlu melakukan polling ke /apiv2/time/status, dan energy_used untuk melihat tarif mana yang dikenakan pada transfer sebelumnya. Perlakukan energy_used sebagai parameter opsional — key yang hilang berarti "tidak ada transfer untuk diukur", bukan kesalahan, dan jangan pernah mengasumsikan nilai default untuknya.

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 yang ditagihkan untuk siklus ini
    energy_used = request.args.get('energy_used')  # '65k' | '131k' | None (key mungkin tidak ada)

    if not address:
        return jsonify({"error": "Missing address parameter"}), 400

    # Logika bisnis Anda (idempoten berdasarkan 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 (timeout) ~10 detik. Kembalikan HTTP 200 sebagai konfirmasi.
Percobaan ulang: hingga 3 kali percobaan dilakukan jika permintaan gagal; jika semuanya gagal, callback akan dibatalkan (delegasi energy tetap terjadi).
Tanpa tanda tangan: permintaan tidak ditandatangani oleh Netts. Rahasianya (jika ada) adalah apa pun yang Anda sematkan di callback_url Anda sendiri.
Rekonsiliasi: karena callback bisa terlewat, lakukan juga polling ke /apiv2/time/status dan pastikan handler Anda bersifat idempoten.

Memperbarui / menghapus callback

Perbarui: panggil /apiv2/time/add lagi dengan alamat yang sama dan callback_url yang 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 mode infinity
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 dengan status tidak aktif; aktifkan dengan pesanan, dengan infinity start, atau dengan meneruskan "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.

POST /apiv2/time/add ​

URL Endpoint ​

Autentikasi ​

Body 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 Kesalahan ​

Kode status HTTP ​

Callback (webhook) ​

Format permintaan ​

Contoh handler (Python / Flask) ​

Perilaku pengiriman ​

Memperbarui / menghapus callback ​

Endpoint Terkait ​

Catatan ​

POST /apiv2/time/add

URL Endpoint

Autentikasi

Body 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 Kesalahan

Kode status HTTP

Callback (webhook)

Format permintaan

Contoh handler (Python / Flask)

Perilaku pengiriman

Memperbarui / menghapus callback

Endpoint Terkait

Catatan