GET /apiv2/balances/

Baca saldo dari alamat TRON mana pun: saat ini, pada waktu lampau, dari waktu ke waktu, atau dijumlahkan untuk suatu periode. Enam endpoint, semuanya sinkron — jawaban langsung diberikan dalam respons, tidak ada antrean dan tidak perlu melakukan polling.

URL Dasar Endpoint

https://netts.io/apiv2/balances/{address}

{address} adalah alamat TRON dalam base58, tepat 34 karakter.

Header Permintaan

Header	Diperlukan	Deskripsi
X-API-KEY	ya	Kunci API dari dasbor
X-Real-IP	ya	Alamat dari daftar putih kunci

Saldo akun Anda harus minimal 4 TRX. Akun yang kehabisan saldo akan dibalas dengan 402 sebelum permintaan mencapai data.

Enam endpoint tersebut

Endpoint	Menjawab
GET /apiv2/balances/{address}	setiap token yang dimiliki saat ini
GET /apiv2/balances/{address}/at?on=YYYY-MM-DD	saldo pada akhir tanggal tersebut, UTC
GET /apiv2/balances/{address}/at-block?block=N	saldo pada blok tertentu, atau pada ts=YYYY-MM-DD HH:MM:SS
GET /apiv2/balances/{address}/history?token_id=TRX&days=90	bagaimana pergerakan suatu token, hari demi hari
GET /apiv2/balances/{address}/summary?date_from=&date_to=	saldo awal, arus masuk, arus keluar, biaya, dan saldo akhir per token
GET /apiv2/balances/{address}/statement?date_from=&date_to=	pratinjau rekening koran dengan operasi individual

Contoh

curl -s 'https://netts.io/apiv2/balances/TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10'

{
  "status": "success",
  "code": 0,
  "msg": "",
  "data": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "as_of_block": 86012345,
    "live": false,
    "hide_spam": false,
    "total_value_usd": "385.25",
    "balances": [
      {
        "token_id": "TRX",
        "symbol": "TRON",
        "token_type": "TRX",
        "decimals": 6,
        "balance": "1141.899000",
        "price_usd": "0.334968",
        "value_usd": "382.50",
        "is_verified": true,
        "is_spam": false,
        "balance_source": "events",
        "node_balance": "1141.899000"
      }
    ]
  }
}

Hal yang perlu diketahui sebelum Anda melakukan integrasi

Jumlah berupa string, bukan angka. "1141.899000" adalah desimal yang diserialisasikan sebagai teks agar presisi tidak hilang akibat konversi floating-point bolak-balik. Uraikan (parse) dengan tipe desimal, bukan float.

Dalam balasan tentang masa lalu, balance adalah jawabannya dan node_balance bukan. balance adalah jumlah pada titik waktu yang Anda tanyakan. node_balance adalah apa yang tersimpan di rantai saat ini, dalam setiap balasan — sehingga dalam jawaban tentang bulan lalu nilai tersebut tetap menampilkan angka hari ini. Jangan pernah menampilkannya sebagai jumlah historis. Untuk pertanyaan tentang saat ini perannya bertukar; hal itu dibahas di bagian berikutnya.

Suatu tanggal berarti akhir dari hari tersebut. ?on=2026-09-01 menjawab untuk 2026-09-01 23:59:59Z. Jika Anda memerlukan awal hari, mintalah akhir dari hari sebelumnya, atau gunakan /at-block dengan ts yang eksplisit.

Dua saldo, dan mengapa "saat ini" adalah bagian yang rumit

Sebuah balasan memuat dua angka yang berbeda, dan pada alamat yang aktif keduanya tidak sama:

Bidang	Apa artinya	Kapan nilainya tepat
balance	Nilai buku besar (ledger), dibangun kembali dari peristiwa rantai yang diindeks hingga blok yang dilaporkan di as_of_block	Tepat untuk blok tersebut — yang bukan merupakan blok terbaru
node_balance	Apa yang disimpan node TRON saat ini	Selalu terkini, tidak pernah historis

balance bukanlah "saldo di rantai saat ini". Ini adalah saldo per as_of_block. Jika Anda memerlukan angka rantai saat ini, baca node_balance — nilai ini diambil dari node TRON pada saat permintaan dibuat dan, untuk TRX, dihitung dengan rumus lengkap: saldo likuid ditambah frozenV2 yang di-stake ditambah yang didelegasikan keluar. Pada alamat yang menyimpan 41,7 juta TRX yang di-stake, nilainya dijawab 42035672.226020, yang tepat merupakan 237799.226020 + 41760434 + 36816 + 623. Hanya membaca bidang balance biasa dari node akan menampilkan 237 ribu dan meleset sebesar dua kali lipat pesanan (orders of magnitude).

Namun node_balance tidak terisi untuk setiap baris. TRX dan setiap TRC10 dimuat kembali dalam satu panggilan getaccount, sehingga keduanya selalu membawanya. TRC20 tidak bisa: node tidak memiliki cara untuk mendaftar token TRC20 yang dimiliki suatu alamat, sehingga balanceOf hanya diminta untuk token-token utama. Terukur pada dompet dengan 504 baris TRC20, 494 di antaranya mengembalikan null. Nilai null tersebut adalah kebijakan dan bukan kegagalan, dan null yang sama muncul jika node tidak dapat dijangkau sementara. Jadi untuk TRX dan TRC10, nilai rantai saat ini selalu tersedia untuk Anda; untuk TRC20 ekor panjang (long-tail), yang Anda miliki hanyalah balance dan blok tempat saldo tersebut berada.

Buku besar hanya maju ke suatu blok setelah setiap penulis pengindeksan mengonfirmasi blok tersebut, dan batas airnya (watermark) adalah nilai minimum di antara semuanya. Penulis paling lambat menerbitkan tandanya dalam kumpulan (batch), sehingga jaraknya melebar terus-menerus lalu menyusut kembali — berpola gigi gergaji, bukan konstan.

Diambil sampelnya selama rentang waktu 20 menit pada 6 September 2026:

	Blok di belakang head	Waktu di belakang
Terbaik	22	~1 mnt
Median	44	~2 mnt
Persentil ke-90	86	~4 mnt
Terburuk yang teramati	121	~6 mnt

Rencanakan kemungkinan buku besar tertinggal beberapa menit di belakang rantai, bukan beberapa detik.

Hal-hal yang mengikuti kondisi tersebut:

• Alamat yang tidak aktif bernilai tepat bahkan untuk "saat ini". Setelah tidak ada transaksi yang berpindah lebih lama dari kelambatan saat ini, buku besar telah menyusul dan balance sama dengan node_balance.
• Pada alamat yang baru saja bertransaksi, balance bisa salah ke salah satu arah — terlalu rendah saat transfer masuk masih belum diindeks, terlalu tinggi saat transfer keluar belum diindeks.
• live=true mempersempit jarak tanpa menutupnya sepenuhnya. Opsi ini menerapkan sisa peristiwa transfer antara as_of_block dan head rantai secara langsung, selama 30–80 md. Ini tidak memindahkan as_of_block, tidak memperhitungkan biaya, dan sengaja melewatkan token TRC10, yang dilacak oleh indeks terpisah. Contoh terukur: sebuah alamat yang buku besarnya melaporkan 157.317444 TRX dijawab 766.194807 dengan live=true, sementara node menyimpan 1698.995472. Bermanfaat, tetapi node_balance tetap menjadi satu-satunya bidang yang merupakan nilai rantai saat ini.
• Jawaban historis selalu tepat, tanpa pengecualian. /at, /at-block, /history, /summary, dan /statement mendeskripsikan titik waktu yang telah lama dilewati oleh buku besar. Tidak ada kelambatan yang perlu diperhitungkan.

Untuk akuntansi, rekonsiliasi, dan rekening koran, gunakan endpoint historis dan percayalah pada hasilnya. Untuk layar dompet langsung, tampilkan node_balance jika ada — yang mencakup TRX dan setiap TRC10 — dan gunakan balance sebagai cadangan dengan as_of_block di sampingnya jika nilainya null, sehingga pembaca mengetahui di blok mana angka tersebut berada.

/history hanya mengembalikan hari-hari yang memiliki aktivitas. Meminta days=7 pada alamat yang hanya bertransaksi pada tiga hari di antaranya akan mengembalikan tiga titik data, bukan tujuh. Setiap titik membawa balance penutupan hari itu dan delta terhadap titik sebelumnya.

/summary merekonsiliasi dirinya sendiri. Untuk setiap token opening_balance + period_in − period_out − period_fees = closing_balance, dan mesin mengembalikan aritmetika tersebut yang sudah tertulis di control_formula, misalnya 76493.940406 + 141490.950160 - 216763.731366 - 79.260200 = 1141.899000. Biaya diuraikan menjadi period_fees_energy dan period_fees_bandwidth. Perhatikan bahwa /summary dapat melaporkan saldo negatif kecil untuk token yang diabaikan sepenuhnya oleh endpoint saldo saat ini.

/statement dibatasi oleh ops_limit. Endpoint ini menerima 10 hingga 5000 operasi; apa pun di luar rentang tersebut menghasilkan 422. operations_total adalah hitungan sebenarnya untuk periode tersebut dan operations_truncated menyatakan apakah daftar tersebut dipotong. token_id default ke TRX saat dihilangkan. Untuk rekening koran lengkap di atas 5000 operasi, pesan berkas sebagai gantinya — lihat Berkas rekening koran.

Urutan token disengaja. TRX dan stablecoin utama diletakkan terlebih dahulu, kemudian token terverifikasi yang memiliki harga, lalu sisanya. Jangan mengurutkan ulang berdasarkan jumlah: spam airdrop sering kali membawa saldo nominal yang sangat besar dan akan naik ke posisi paling atas.

Spam ditandai, bukan dihapus. is_spam menandai token yang diklasifikasikan sebagai penipuan. Teruskan hide_spam=true untuk menghilangkannya dari balasan; TRX dan USDT tidak pernah disembunyikan.

Batas Laju

Setiap endpoint menerima 10 permintaan per detik, yang dibagi bersama di antara semua klien endpoint tersebut. Batas ini berlaku per endpoint, sehingga /history dan /summary tidak saling bersaing.

Melampaui batas ini menghasilkan respons 429 dengan Retry-After: 1, bersama dengan RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset. Coba lagi setelah penundaan yang ditentukan.

Batas kedua yang jauh lebih longgar sebesar 100 permintaan per detik per IP sumber berlaku di seluruh API. Keduanya dibedakan melalui pesannya: batas endpoint menyatakan Endpoint rate limit exceeded (10 req/s shared), sedangkan batas seluruh akun menyatakan API rate limit exceeded.

Kesalahan

HTTP	Arti
400	alamat memiliki panjang 34 karakter tetapi gagal dalam checksum base58
401	kunci tidak ada atau tidak valid, atau IP sumber tidak ada dalam daftar putih
402	saldo akun di bawah minimum 4 TRX
403	kunci API diblokir; hubungi dukungan
422	parameter tidak ada atau di luar rentang — panjang alamat salah, atau ops_limit di luar 10–5000
429	batas laju terlampaui
503	mesin saldo tidak menjawab; permintaan tidak dihitung, coba lagi

Isi kesalahan (error body) hadir dalam tiga format, bergantung pada lapisan mana yang menolak permintaan tersebut. Cocokkan berdasarkan status HTTP, bukan berdasarkan isi respons.

// 401, 402, 403 — gateway, sebelum permintaan mencapai layanan
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — layanan, setelah parameter diuraikan
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

// 429 — pembatas laju (rate limiter)
{"message": "Endpoint rate limit exceeded (10 req/s shared), retry shortly", "request_id": "e5dbf25437d2eb215c764617d50b8d3b"}

Terkait

• Berkas rekening koran — rekening koran lengkap sebagai berkas CSV atau PDF
• Webhook laporan — mendapatkan pemberitahuan saat berkas siap