GET /apiv2/balances/

Herhangi bir TRON adresinin bakiyelerini okuyun: şu anda, geçmiş bir anda, zaman içinde veya belirli bir dönem için toplanmış olarak. Altı uç nokta, tümü senkron — yanıt cevapta gelir, kuyruk yoktur ve yoklanacak (poll edilecek) hiçbir şey bulunmaz.

Uç Nokta Temel URL'si

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

{address}, base58 formatında, tam olarak 34 karakter uzunluğunda bir TRON adresidir.

İstek Üstbilgileri

Header	Required	Description
X-API-KEY	evet	Kontrol panelinden alınan API anahtarı
X-Real-IP	evet	Anahtar beyaz listesindeki bir adres

Hesap bakiyeniz en az 4 TRX olmalıdır. Yetersiz bakiyeli bir hesap, istek verilere ulaşmadan önce 402 ile yanıtlanır.

Altı uç nokta

Endpoint	Yanıtladığı İçerik
GET /apiv2/balances/{address}	şu anda tutulan her token
GET /apiv2/balances/{address}/at?on=YYYY-MM-DD	ilgili tarihin sonundaki bakiyeler, UTC
GET /apiv2/balances/{address}/at-block?block=N	tam bir bloktaki veya ts=YYYY-MM-DD HH:MM:SS anındaki bakiyeler
GET /apiv2/balances/{address}/history?token_id=TRX&days=90	bir token'ın gün be gün nasıl hareket ettiği
GET /apiv2/balances/{address}/summary?date_from=&date_to=	token başına açılış, giriş, çıkış, ücretler ve kapanış
GET /apiv2/balances/{address}/statement?date_from=&date_to=	bireysel işlemlerle hesap ekstresi önizlemesi

Örnekler

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

Entegrasyondan önce bilinmesi gerekenler

Tutarlar dize (string) türündedir, sayı değildir. "1141.899000", kayan nokta (floating-point) gidiş-dönüş dönüşümlerinde hassasiyet kaybı yaşanmaması için metin olarak serileştirilmiş bir ondalık sayıdır. Bunu float ile değil, bir ondalık (decimal) türü ile ayrıştırın.

Geçmişe ait bir yanıtta doğru cevap balance alanıdır, node_balance değildir. balance, sorguladığınız andaki tutardır. node_balance ise her yanıtta zincirin şu anda tuttuğu değerdir — yani geçen aya ait bir yanıtta bile bugünün sayısını gösterir. Bunu asla geçmişe ait tutar olarak görüntülemeyin. Şimdiki zaman ile ilgili bir soruda roller değişir; bu bir sonraki bölümdür.

Bir tarih, o günün sonu anlamına gelir. ?on=2026-09-01, 2026-09-01 23:59:59Z anı için yanıt verir. Bir günün başlangıcına ihtiyacınız varsa, bir önceki günün sonunu isteyin veya açık bir ts ile /at-block kullanın.

İki bakiye ve "şimdi"nin neden çetrefilli olduğu

Bir yanıt iki farklı sayı taşır ve aktif bir adreste bunlar birbiriyle uyuşmaz:

Field	Nedir	Ne zaman kesindir
balance	as_of_block içinde bildirilen bloğa kadar indekslenmiş zincir olaylarından yeniden oluşturulan defter (ledger) değeri	O blok için kesin — ki bu en yeni blok değildir
node_balance	Bir TRON düğümünün şu anda tuttuğu değer	Her zaman günceldir, asla geçmişe ait değildir

balance, "zincirdeki şu anki bakiye" demek değildir. as_of_block itibarıyla olan bakiyedir. Zincirin mevcut sayısına ihtiyaç duyduğunuzda node_balance değerini okuyun — bu, istek anında bir TRON düğümünden ve TRX için tam formülle alınır: likit bakiye artı stake edilmiş frozenV2 artı delege edilmiş miktar. 41,7 milyon stake edilmiş TRX tutan bir adreste bu değer 42035672.226020 olarak yanıtlandı; bu da tam olarak 237799.226020 + 41760434 + 36816 + 623 toplamıdır. Düğümün yalnızca düz balance alanını okumak 237 bin gösterecek ve iki basamak mertebesinde hatalı olacaktı.

Ancak node_balance her satır için doldurulmaz. TRX ve her TRC10 tek bir getaccount çağrısında döner, bu nedenle her zaman bu değeri taşırlar. TRC20 bunu yapamaz: bir düğümün, bir adresin tuttuğu TRC20 token'larını listelemesinin hiçbir yolu yoktur, bu yüzden balanceOf yalnızca başlıca token'lar için sorulur. 504 TRC20 satırına sahip bir cüzdanda ölçüldüğünde, bunlardan 494'ü null olarak döndü. Bu null bir arızadan ziyade bir politikadır ve düğüme kısa bir süre ulaşılamadığında da aynı null görünür. Dolayısıyla TRX ve TRC10 için zincirin mevcut değeri sizin için her zaman mevcuttur; kuyrukta kalan (long-tail) bir TRC20 için elinizdeki tek şey balance ve dayandığı bloktur.

Defter, yalnızca her indeksleme yazıcısı o bloğu onayladıktan sonra bir bloğa ilerler ve filigranı (watermark) bunların tümü arasındaki minimum değerdir. En yavaş yazıcılar işaretlerini toplu (batch) olarak yayınlar, bu nedenle fark düzenli olarak açılır ve ardından aniden kapanır — sabit bir değer değil, bir testere dişidir.

6 Eylül 2026'da 20 dakikalık bir pencerede örneklenmiştir:

	Tepe noktasının gerisindeki blok sayısı	Gerisindeki süre
En iyi	22	~1 dk
Medyan	44	~2 dk
90. yüzdelik	86	~4 dk
Gözlemlenen en kötü	121	~6 dk

Defterin zincirin birkaç saniye değil, birkaç dakika gerisinde olacağını planlayın.

Bundan çıkan sonuçlar:

• Hareketsiz bir adres "şimdi" için bile kesindir. Mevcut gecikmeden daha uzun süre hiçbir şey hareket etmediğinde, defter arayı kapatmıştır ve balance, node_balance değerine eşit olur.
• Henüz işlem yapmış bir adreste balance her iki yönde de yanlış olabilir — gelen bir transfer henüz indekslenmemişken çok düşük, giden bir transfer indekslenmemişken çok yüksek olabilir.
• live=true farkı kapatmadan daraltır. as_of_block ile zincir başı (head) arasındaki transfer olaylarının kuyruğunu 30–80 ms boyunca anında uygular. as_of_block değerini ilerletmez, ücretleri hesaba katmaz ve ayrı bir indeks tarafından izlenen TRC10 token'larını kasıtlı olarak atlar. Ölçülen bir örnek: defterinde 157.317444 TRX bildirilen bir adres, live=true ile 766.194807 yanıtı verirken, düğüm 1698.995472 tutuyordu. Faydalıdır, ancak node_balance zincirin geçerli değerini yansıtan tek alan olmaya devam eder.
• Geçmişe ait yanıtlar kesin ve nettir, nokta. /at, /at-block, /history, /summary ve /statement, defterin çoktan geçtiği noktaları tanımlar. Hesaba katılacak bir gecikme yoktur.

Muhasebe, mutabakat ve ekstreler için geçmiş uç noktalarını kullanın ve onlara güvenin. Canlı bir cüzdan ekranı için, mevcut olduğu yerlerde — ki bu TRX ve her TRC10'u kapsar — node_balance değerini gösterin; null olduğu yerlerde ise okuyucunun sayının hangi bloğa dayandığını bilmesi için yanında as_of_block ile birlikte balance değerine geri dönün.

/history yalnızca hareketlilik olan günleri döndürür. Üç gününde hareket olmuş bir adreste days=7 istemek yedi değil, üç nokta döndürür. Her nokta, o günün kapanış balance değerini ve önceki noktaya göre delta farkını taşır.

/summary kendi içinde mutabakat sağlar. Her token için opening_balance + period_in − period_out − period_fees = closing_balance bağıntısı vardır ve motor bu aritmetiği control_formula içinde önceden yazılmış olarak döndürür; örneğin 76493.940406 + 141490.950160 - 216763.731366 - 79.260200 = 1141.899000. Ücretler period_fees_energy ve period_fees_bandwidth olarak ayrıştırılır. /summary uç noktasının, güncel bakiye uç noktasının tamamen dışarıda bıraktığı bir token için küçük bir negatif bakiye bildirebileceğini unutmayın.

/statement, ops_limit ile sınırlandırılmıştır. 10 ile 5000 arasında işlemi kabul eder; bu aralığın dışındaki her şey 422 hatasıdır. operations_total dönem için gerçek sayıdır ve operations_truncated listenin kısa kesilip kesilmediğini belirtir. Belirtilmediğinde token_id varsayılan olarak TRX olur. 5000 işlemin üzerindeki tam bir ekstre için bunun yerine bir dosya sipariş edin — bkz. Ekstre dosyaları.

Token sıralaması kasıtlıdır. Önce TRX ve başlıca stabilcoin'ler gelir, ardından fiyatı olan doğrulanmış token'lar, sonra da diğer her şey. Tutara göre yeniden sıralamayın: airdrop ile gelen spam'ler genellikle muazzam nominal bakiyeler taşır ve en üste çıkabilir.

Spam işaretlenir, kaldırılmaz. is_spam, yanıltıcı olarak sınıflandırılan token'ları işaretler. Bunları yanıttan çıkarmak için hide_spam=true parametresini geçin; TRX ve USDT asla gizlenmez.

İstek Hızı Sınırları

Her uç nokta, o uç noktanın tüm istemcileri arasında paylaşılan şekilde saniyede 10 istek kabul eder. Sınır uç nokta başınadır, bu nedenle /history ve /summary birbiriyle rekabet etmez.

Sınırın aşılması, RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset ile birlikte Retry-After: 1 içeren bir 429 yanıtı verir. Belirtilen gecikmeden sonra tekrar deneyin.

Tüm API genelinde geçerli olan, kaynak IP başına saniyede 100 istek şeklinde ikinci ve çok daha geniş bir sınır bulunur. İkisi mesajla birbirinden ayırt edilir: uç nokta sınırı Endpoint rate limit exceeded (10 req/s shared), hesap genelindeki sınır ise API rate limit exceeded mesajını verir.

Hata Yanıtları

HTTP	Anlamı
400	adres 34 karakterdir ancak base58 sağlama toplamı (checksum) başarısızdır
401	anahtar eksik veya geçersiz ya da kaynak IP beyaz listede değil
402	hesap bakiyesi 4 TRX minimumunun altında
403	API anahtarı engellendi; destek ile iletişime geçin
422	bir parametre eksik veya aralık dışında — yanlış bir adres uzunluğu veya 10–5000 aralığının dışında bir ops_limit
429	hız sınırı aşıldı
503	bakiye motoru yanıt vermedi; istek sayılmadı, tekrar deneyin

Hata gövdeleri, isteği hangi katmanın reddettiğine bağlı olarak üç biçimde gelir. Gövdeye değil, HTTP durum koduna göre eşleştirme yapın.

// 401, 402, 403 — the gateway, before the request reaches the service
{"detail": {"code": 1004, "msg": "Insufficient funds. Minimum balance is 4 TRX. Please top up your account."}}

// 400, 422 — the service, after parameters are parsed
{"status": "error", "code": -4, "msg": "address must be base58 (T...)", "data": {"code": -4, "msg": "address must be base58 (T...)"}}

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

İlgili

• Ekstre dosyaları — CSV veya PDF dosyası olarak tam hesap ekstresi
• Rapor webhook'ları — bir dosya hazır olduğunda bildirim alma