GET /apiv2/compliance/

Pencarian kepatuhan terbuka tanpa kunci untuk satu alamat TRON. Endpoint ini mengembalikan keputusan — apakah alamat tersebut diblokir, dan dalam kategori apa — disajikan sepenuhnya dari cache daftar tolak (deny-list) dalam memori. Tanpa kunci API, tanpa saldo, tanpa biaya. Tujuannya adalah agar siapa pun dapat mengintegrasikan lapisan kepatuhan dengan satu HTTP GET.

Endpoint ini hanya membaca cache, tidak pernah membaca basis data atau node rantai (chain node), sehingga pencarian hanya memerlukan waktu sepersekian milidetik. Batasan laju diterapkan per IP oleh gateway.

URL Endpoint

GET https://netts.io/apiv2/compliance/{address}

Tidak diperlukan header autentikasi.

Parameter Permintaan

Parameter	Type	Required	Description
address	string	Ya	Alamat TRON base58 — T diikuti oleh 33 karakter

Contoh

cURL

curl https://netts.io/apiv2/compliance/TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL

Python

import requests

address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL"
r = requests.get(f"https://netts.io/apiv2/compliance/{address}")
data = r.json()

if r.status_code == 200:
    d = data["data"]
    print(f"blocked : {d['blocked']}")
    print(f"category: {d['category']}")
    if d["category"] == "aml_risk":
        print(f"reason  : {d.get('reason_code')} — {d.get('label')}")
else:
    print(f"Error: {data}")

JavaScript

const address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL";
const res = await fetch(`https://netts.io/apiv2/compliance/${address}`);
const { data } = await res.json();
console.log(data.blocked, data.category, data.label);

Respons

Diblokir — ada di dalam daftar tolak pusat (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL",
        "blocked": true,
        "category": "aml_risk",
        "severity": "BLOCK",
        "reason_code": "SANCTIONS_SCREENING",
        "label": "DPRK Bitget Exploit - September 2026",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": ["aml_risk"],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Dompet GasFree — smart contract yang dapat menerima USDT (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TZEMF5vmSABaWjeUPty8kFpUsquMAKhGFp",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "gasfree_wallet",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T12:00:00+00:00"
    }
}

Kontrak yang dihapus — alamat tetap dianggap sebagai smart contract (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TBtrogXC58EAvE7vod56ZnzRY4y5jrwtbN",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "selfdestructed_contract",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

Bersih — tidak ada di himpunan mana pun (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC",
        "blocked": false,
        "category": "clean",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": [],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Bidang Respons

Field	Type	Description
data.address	string	Alamat yang diperiksa
data.blocked	boolean	true jika alamat berada dalam himpunan pemblokiran apa pun
data.category	string	aml_risk, usdt_frozen, smart_contract, spam_sender, atau clean (lihat di bawah); endpoint batch juga dapat mengembalikan invalid atau unavailable
data.severity	string	Hanya untuk aml_risk. Contoh: BLOCK, REVIEW
data.reason_code	string	Hanya untuk aml_risk. Kode mesin, contoh: SANCTIONS_OFAC_SDN
data.label	string	Hanya untuk aml_risk. Label yang dapat dibaca manusia
data.subtype	string | null	Memperinci smart_contract. gasfree_wallet — dompet GasFree aktif (lihat Dompet GasFree); selfdestructed_contract — kontrak pada alamat ini telah dihapus (lihat Kontrak yang dihapus); null untuk kondisi lainnya
data.subtype_status	string	confirmed — subtipe diketahui berdasarkan status terkonfirmasi terbaru; not_found — kedua subtipe tidak berlaku; unavailable — daftar subtipe tidak dapat dikonsultasikan saat ini, sehingga subtype bernilai null dan tidak menyatakan apa pun
data.matches	string[]	Semua himpunan tempat alamat berada, berdasarkan urutan prioritas (contoh: ["usdt_frozen", "smart_contract", "spam_sender"]). category hanyalah elemen pertama di antaranya
data.checks_complete	boolean	true jika keempat himpunan dimuat dan diperbarui pada saat pencarian. false berarti jawaban clean didasarkan pada pemeriksaan yang tidak lengkap
data.checked_at	string	Stempel waktu ISO-8601 UTC saat pencarian

Kategori

category adalah sebuah keputusan, bukan skor risiko. Ketika suatu alamat berada di lebih dari satu himpunan, kategori yang paling serius akan dipilih, dengan urutan berikut (semuanya dicantumkan dalam matches):

Category	blocked	Meaning
aml_risk	true	Ada di dalam daftar tolak pusat: sanksi, penipuan, ransomware, aset curian, fraud, temuan penegak hukum atau penyalahgunaan internal. Alasan yang dikurasi dilampirkan
usdt_frozen	true	Alamat dibekukan oleh penerbit USDT (Tether). Alamat tidak dapat memindahkan USDT, sehingga delegasi sumber daya ke alamat tersebut ditolak
smart_contract	true	Alamat smart contract yang dikenal, termasuk kontrak yang dihapus kemudian. Lihat catatan di bawah
spam_sender	true	Pengirim spam massal yang terkonfirmasi
clean	false	Tidak ada di himpunan mana pun
unavailable	null	Daftar tolak pusat tidak dapat dikonsultasikan, sehingga alamat tersebut tidak terkonfirmasi bersih maupun diblokir. Hanya untuk batch; endpoint alamat tunggal akan mengembalikan 503 dengan code 5004. Lihat Daftar tolak pusat tidak tersedia

Smart contract diblokir karena alasan teknis, bukan alasan AML

Keputusan smart_contract berarti alamat tersebut milik kontrak, bukan dompet pengguna, sehingga energi tidak didelegasikan kepadanya dan alamat tersebut ditolak bahkan sebelum pesanan dibuat. Himpunan ini mencakup setiap alamat tempat kontrak berhasil dibuat, termasuk kontrak yang dihapus di kemudian hari — kontrak yang dihapus tidak mengubah alamatnya menjadi dompet pengguna. Ini tidak berarti kontrak tersebut disusupi, tercemar, atau berisiko tinggi berdasarkan AML. Sebagian besar kontrak dalam himpunan ini sepenuhnya normal. Perlakukan smart_contract sebagai "bukan target delegasi", bukan sebagai tanda bahaya risiko.

Dompet GasFree

Dompet GasFree adalah kontrak yang memungkinkan pemiliknya menerima dan mengirim token serta membayar biaya jaringan dengan token tersebut. Masing-masing dibuat oleh pengontrol GasFree TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U. Alamat seperti ini dilaporkan sebagai category: "smart_contract" dengan subtype: "gasfree_wallet".

Perbedaannya penting saat Anda merutekan dana:

	Smart contract biasa	Dompet GasFree
Kirim USDT ke alamat ini	bukan penerima normal	ya — ini adalah dompet pengguna
Delegasikan energi ke alamat ini	tidak	tidak — kami tidak mendelegasikan energi ke dompet GasFree
category / subtype	smart_contract / null	smart_contract / gasfree_wallet

Cakupan dan peringatan:

• Hanya dompet yang telah di-deploy yang diketahui. Alamat GasFree yang telah menerima USDT tetapi belum pernah mengirim apa pun belum di-deploy, sehingga belum masuk ke himpunan mana pun dan dikembalikan sebagai clean.
• Subtipe menjelaskan ke mana alamat dapat menerima dana. Ini tidak menyatakan apa pun tentang transfer dari dompet GasFree; periksa alamat pengirim secara terpisah.
• subtype_status: "unavailable" berarti daftar GasFree tidak dapat dikonsultasikan. Bagian keputusan lainnya (blocked, category, matches) tetap valid.
• Pengontrol itu sendiri dan kontrak lainnya bukan dompet GasFree: mereka dikembalikan dengan subtype: null.

Kontrak yang dihapus

Sebuah kontrak dapat menghapus dirinya sendiri (self-destruct). Alamat tersebut tetap berada dalam himpunan smart_contract: alamat tersebut dulunya adalah alamat kontrak, bukan dompet pengguna, dan Netts tidak mendelegasikan sumber daya atau mengirim pembayaran kepadanya. Alamat seperti ini dilaporkan sebagai category: "smart_contract" dengan subtype: "selfdestructed_contract".

• confirmed berarti dihapus berdasarkan status terbaru yang dikonfirmasi oleh node TRON. Ini bukan jaminan untuk masa depan: sebuah kontrak dapat di-deploy kembali di alamat yang sama, dan kemudian subtipe akan dihapus sementara alamat tetap menjadi smart_contract.
• Panggilan self-destruct saja tidak menandakan penghapusan: pada TRON, kontrak yang dibuat dalam transaksi sebelumnya mempertahankan kodenya setelah itu. Hanya status node yang diperhitungkan.
• Jika suatu alamat merupakan kontrak yang dihapus sekaligus berada dalam daftar GasFree, selfdestructed_contract yang diutamakan — alamat tidak dilaporkan sebagai dompet GasFree yang berfungsi.
• subtype_status: "unavailable" berarti daftar kontrak yang dihapus tidak dapat dikonsultasikan; bagian keputusan lainnya tetap valid, dan tidak ada alamat yang dikonfirmasi sebagai dompet GasFree hingga dapat dikonsultasikan kembali.

Kode alasan dan penyedia data

Untuk aml_risk, reason_code dan label menjelaskan alasan alamat tersebut dicantumkan. Otoritas pemberi sanksi publik dipertahankan sebagaimana adanya — SANCTIONS_OFAC_SDN, SANCTIONS_EU_FSF, SANCTIONS_UK_FCDO, dan sebagainya. Nama penyedia penyaringan komersial di balik temuan tidak pernah diungkapkan: kode-kode tersebut dinormalisasi menjadi SANCTIONS_SCREENING, dan nama penyedia mana pun dihapus dari label.

Ukuran daftar tolak

GET https://netts.io/apiv2/compliance/stats

Ukuran agregat dari himpunan di balik keputusan, dari cache yang sama. Terbuka dan tanpa kunci.

{
    "code": 0,
    "status": "ok",
    "data": {
        "aml_risk": 1079,
        "usdt_frozen": 8022,
        "smart_contract": 7581686,
        "spam_sender": 27039018,
        "gasfree_wallets_subset": 512487,
        "selfdestructed_contracts_subset": 4065766,
        "total": 34629805,
        "revision": 1117,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

smart_contract adalah bagian netral AML terbesar dari total — lihat catatan tentang kontrak di atas. gasfree_wallets_subset (dompet GasFree aktif) dan selfdestructed_contracts_subset (kontrak yang dihapus) adalah bagian dari smart_contract; mereka tidak ditambahkan ke total. Jika salah satu dari kedua penghitung ini tidak dapat dibaca saat ini, nilainya adalah null dan angka lainnya tetap dikembalikan.

Pencarian batch (kunci API)

Untuk memeriksa banyak alamat sekaligus, gunakan endpoint batch terautentikasi. Endpoint ini disediakan untuk menghemat perjalanan pulang-pergi jaringan (network round-trip): satu permintaan dan satu pipeline internal alih-alih N panggilan GET terpisah. Satu alamat hanyalah sebuah array dengan satu elemen.

POST https://netts.io/apiv2/compliance/batch
x-api-key: YOUR_KEY
Content-Type: application/json

{ "addresses": ["TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC"] }

Hingga 1000 alamat per permintaan. Keputusan dikembalikan dalam urutan yang sama, masing-masing dengan bidang yang sama seperti respons alamat tunggal (termasuk subtype, subtype_status, matches, dan checks_complete), ditambah category: "invalid" (dengan bidang error) untuk setiap entri yang formatnya salah — satu entri buruk tidak menggagalkan seluruh batch. Jika daftar tolak pusat tidak dimuat, alamat yang seharusnya bersih akan dikembalikan sebagai category: "unavailable" (blocked: null, dengan bidang error) alih-alih clean — lihat Daftar tolak pusat tidak tersedia.

{
    "code": 0,
    "status": "ok",
    "data": {
        "count": 2,
        "checked_at": "2026-09-27T12:00:00+00:00",
        "results": [
            { "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "blocked": true, "category": "aml_risk", "subtype": null, "subtype_status": "not_found", "matches": ["aml_risk"], "checks_complete": true, "severity": "BLOCK", "reason_code": "SANCTIONS_SCREENING", "label": "DPRK Bitget Exploit - September 2026" },
            { "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC", "blocked": false, "category": "clean", "subtype": null, "subtype_status": "not_found", "matches": [], "checks_complete": true }
        ]
    }
}

Endpoint batch memerlukan kunci API (header x-api-key) dan kunci tersebut secara opsional dapat diikat ke whitelist IP. Hubungi kami untuk mendapatkan kunci.

Batasan lajunya berlaku per kunci dan lebih tinggi daripada endpoint alamat tunggal publik:

Period	Limit
1 detik	200 permintaan
1 menit	12.000 permintaan

Setiap permintaan dapat memuat hingga 1000 alamat, sehingga satu kunci dapat menyaring jauh di atas seratus ribu alamat per detik dalam batas ini.

Respons Kesalahan

Format alamat tidak valid (400)

{
    "code": 1001,
    "status": "error",
    "msg": "Invalid TRON address format (expected base58, 'T' + 33 chars)"
}

Layanan sementara tidak tersedia (503)

{
    "code": 5003,
    "status": "error",
    "msg": "compliance service temporarily unavailable"
}

Daftar tolak pusat tidak tersedia (503, code 5004)

Keputusan disajikan dari cache dalam memori. Jika cache tersebut dapat dijangkau tetapi daftar tolak AML pusat saat ini tidak dimuat, atau revisi saat ini gagal dalam pemeriksaan integritas, endpoint tidak beralih ke clean — hal itu akan melaporkan alamat yang belum diperiksa sebagai aman. Sebaliknya, endpoint akan memberi tahu Anda secara jelas bahwa endpoint tidak dapat menghasilkan keputusan:

{
    "code": 5004,
    "status": "error",
    "msg": "compliance deny-list temporarily unavailable, verdict cannot be produced"
}

Artinya: alamat tersebut tidak terkonfirmasi bersih maupun diblokir. Layanan tidak dapat menyaringnya terhadap daftar sanksi/AML saat ini. Jangan menganggap alamat tersebut bersih — coba lagi dalam waktu singkat.

Pemblokiran pasti tetap dikembalikan secara normal: jika alamat cocok dengan USDT beku, smart contract, atau pengirim spam (himpunan yang tidak bergantung pada daftar pusat), Anda tetap mendapatkan keputusan biasa blocked: true bahkan dalam kondisi ini. Hanya jawaban yang seharusnya clean yang berubah menjadi 5004.

Pada endpoint batch, situasi yang sama dilaporkan per alamat sebagai category: "unavailable" (blocked: null, dengan bidang error); sisa batch tidak terpengaruh. Ini adalah kondisi sementara yang jarang terjadi.

Registri tidak tersedia (503, code 5005)

Himpunan diperbarui langsung di tempat dan tetap dapat dibaca saat diperbarui, sehingga pembaruan rutin tidak pernah memengaruhi keputusan. Hanya jika suatu himpunan gagal diterapkan, alamat yang seharusnya bersih tidak dapat dikonfirmasi bersih. Endpoint alamat tunggal kemudian mengembalikan:

{
    "code": 5005,
    "status": "error",
    "msg": "address registry temporarily unavailable, verdict cannot be produced, retry shortly"
}

Sama seperti 5004, pemblokiran pasti tetap dikembalikan secara normal, dan endpoint batch melaporkan kasus tersebut per alamat sebagai category: "unavailable". Coba lagi nanti.

Referensi Kode Kesalahan

Code	Description	HTTP Status
0	Berhasil	200
1001	Format alamat TRON tidak valid	400
5003	Backend cache sementara tidak tersedia	503
5004	Daftar tolak pusat tidak dimuat — keputusan tidak dapat dibuat (coba lagi)	503
5005	Suatu himpunan gagal diterapkan — keputusan tidak dapat dibuat (coba lagi)	503

Batas Kecepatan

Terdapat dua tingkatan yang diberlakukan di gateway:

Endpoint	Auth	Dibatasi berdasarkan	1 detik	1 menit
GET /apiv2/compliance/{address}	terbuka, tanpa kunci	IP	10	300
GET /apiv2/compliance/stats	terbuka, tanpa kunci	IP	10	300
POST /apiv2/compliance/batch	kunci API	kunci	200	12.000

Endpoint alamat tunggal terbuka ditujukan untuk penggunaan interaktif dan terprogram ringan. Untuk penyaringan massal, gunakan endpoint batch: dengan kapasitas hingga 1000 alamat per permintaan dan 200 permintaan/detik per kunci, satu kunci dapat menyaring jauh di atas seratus ribu alamat per detik. Butuh lebih banyak? Batas per kunci adalah pengaturan kebijakan, bukan batas teknis — hubungi kami.

Batas Laju Terlampaui (429)

{
    "message": "API rate limit exceeded"
}

Catatan

• Tanpa autentikasi dan tanpa biaya. Siapa pun dapat memanggilnya; tidak ada yang perlu ditandatangani.
• Hanya cache. Keputusan tidak pernah menyentuh basis data atau node, sehingga cepat dan aman untuk melakukan polling dalam batasan laju.
• Bukan laporan AML lengkap. Untuk skor risiko, rincian paparan, dan laporan bertanda tangan, gunakan API penyaringan terautentikasi (POST /apiv2/screening). Endpoint ini menjawab satu pertanyaan yang lebih sempit: apakah alamat tersebut ada di daftar tolak kami, dan mengapa.