GET /apiv2/compliance/
Відкрита перевірка на відповідність правилам (compliance) без ключів для однієї TRON-адреси. Вона повертає вердикт — чи заблокована адреса та в якій категорії — повністю з кешу списку заборон (deny-list) у оперативній пам'яті. Без API-ключа, без балансу, безкоштовно. Мета — дозволити будь-кому інтегрувати рівень compliance за допомогою одного HTTP GET-запиту.
Кінцева точка читає лише кеш і ніколи не звертається до бази даних або вузла мережі, тому перевірка триває частку мілісекунди. Шлюз обмежує частоту запитів за IP-адресою.
URL кінцевої точки
GET https://netts.io/apiv2/compliance/{address}Заголовки автентифікації не потрібні.
Параметри запиту
| Parameter | Type | Required | Description |
|---|---|---|---|
| address | string | Yes | TRON base58-адреса — T, за якою слідують 33 символи |
Приклади
cURL
curl https://netts.io/apiv2/compliance/TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpLPython
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);Відповідь
Заблоковано — у центральному списку заборон (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"
}
}Гаманець GasFree — смартконтракт, який може приймати 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"
}
}Видалений контракт — адреса все ще вважається смартконтрактом (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"
}
}Чисто — немає в жодному зі списків (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"
}
}Поля відповіді
| Parameter | Type | Description |
|---|---|---|
| data.address | string | Перевірена адреса |
| data.blocked | boolean | true, якщо адреса присутня в будь-якому блокувальному списку |
| data.category | string | aml_risk, usdt_frozen, smart_contract, spam_sender або clean (див. нижче); пакетна кінцева точка також може повертати invalid або unavailable |
| data.severity | string | Лише для aml_risk. Наприклад, BLOCK, REVIEW |
| data.reason_code | string | Лише для aml_risk. Машинний код, наприклад SANCTIONS_OFAC_SDN |
| data.label | string | Лише для aml_risk. Людинозрозуміла мітка |
| data.subtype | string | null | Уточнює smart_contract. gasfree_wallet — активний гаманець GasFree (див. Гаманці GasFree); selfdestructed_contract — контракт за цією адресою було видалено (див. Видалені контракти); в інших випадках null |
| data.subtype_status | string | confirmed — підтип відомий за останнім підтвердженим станом; not_found — жоден підтип не застосовується; unavailable — наразі не вдалося звернутися до списку підтипів, тому subtype має значення null і нічого не стверджує |
| data.matches | string[] | Усі списки, в яких присутня адреса, у порядку пріоритету (наприклад, ["usdt_frozen", "smart_contract", "spam_sender"]). category відображає лише перший із них |
| data.checks_complete | boolean | true, якщо всі чотири списки були завантажені та актуальні на момент перевірки. false означає, що відповідь clean базується на неповній перевірці |
| data.checked_at | string | Мітка часу перевірки у форматі UTC ISO-8601 |
Категорії
category — це вердикт, а не оцінка ризику. Якщо адреса перебуває в кількох списках, пріоритет має найбільш серйозна категорія в такому порядку (усі вони перелічені в matches):
| Category | blocked | Meaning |
|---|---|---|
aml_risk | true | У центральному списку заборон: санкції, шахрайство, програми-вимагачі, викрадені активи, обманні схеми, висновки правоохоронних органів або внутрішньої перевірки на зловживання. Додається курована причина |
usdt_frozen | true | Адреса заморожена емітентом USDT (Tether). Вона не може переміщувати USDT, тому в делегуванні ресурсів на неї відмовлено |
smart_contract | true | Відома адреса смартконтракту, включно з контрактами, видаленими пізніше. Дивіться примітку нижче |
spam_sender | true | Підтверджений відправник масового спаму |
clean | false | Немає в жодному зі списків |
unavailable | null | Не вдалося звернутися до центрального списку заборон, тому адреса ані підтверджено чиста, ані заблокована. Тільки для пакетної перевірки; кінцева точка для однієї адреси натомість повертає 503 із code 5004. Див. Центральний список заборон недоступний |
Смартконтракти блокуються з технічних причин, а не через AML
Вердикт smart_contract означає, що адреса належить контракту, а не гаманцю користувача, тому Energy на неї не делегується, а адреса відхиляється ще до створення замовлення. Список містить кожну адресу, де було успішно створено контракт, включно з контрактами, які було видалено пізніше — видалений контракт не перетворює свою адресу на гаманець користувача. Це не означає, що контракт скомпрометований, заплямований або є високоризиковим з точки зору AML. Більшість контрактів у цьому списку абсолютно звичайні. Сприймайте smart_contract як позначку «не є ціллю для делегування», а не як індикатор ризику.
Гаманці GasFree
Гаманець GasFree — це контракт, який дозволяє своєму власнику приймати та відправляти токени, а також сплачувати мережеву комісію цими токенами. Кожен із них створюється контролером GasFree TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U. Така адреса позначається як category: "smart_contract" із subtype: "gasfree_wallet".
Ця різниця має значення під час маршрутизації коштів:
| Звичайний смартконтракт | Гаманець GasFree | |
|---|---|---|
| Надіслати USDT на нього | не є нормальним одержувачем | так — це гаманець користувача |
| Делегувати Energy на нього | ні | ні — ми не делегуємо Energy на гаманці GasFree |
category / subtype | smart_contract / null | smart_contract / gasfree_wallet |
Покриття та застереження:
- Відомо лише про розгорнуті (deployed) гаманці. Адреса GasFree, яка отримала USDT, але нічого не надсилала, ще не розгорнута, тому вона відсутня в будь-якому списку і повертається як
clean. - Підтип описує те, куди адреса може приймати кошти. Він нічого не говорить про перекази з гаманця GasFree; перевіряйте адресу відправника окремо.
subtype_status: "unavailable"означає, що не вдалося звернутися до списку GasFree. Решта вердикту (blocked,category,matches) залишається дійсною.- Сам контролер та інші контракти не є гаманцями GasFree: вони повертаються із значенням
subtype: null.
Видалені контракти
Контракт може видалити себе (самознищитися). Адреса залишається у списку smart_contract: це була адреса контракту, а не гаманець користувача, і Netts не делегує ресурси та не надсилає на неї виплати. Така адреса повертається з category: "smart_contract" та subtype: "selfdestructed_contract".
confirmedозначає видалення згідно з останнім станом, підтвердженим вузлом TRON. Це не є гарантією на майбутнє: контракт може бути розгорнутий за цією ж адресою знову, і тоді підтип видаляється, тоді як адреса залишаєтьсяsmart_contract.- Сам по собі виклик self-destruct не означає видалення: у TRON контракт, створений у попередній транзакції, зберігає свій код після цього. Враховується лише стан вузла.
- Якщо адреса одночасно є видаленим контрактом і присутня у списку GasFree, пріоритет має
selfdestructed_contract— адреса не вважається робочим гаманцем GasFree. subtype_status: "unavailable"означає, що не вдалося звернутися до списку видалених контрактів; решта вердикту залишається дійсною, і жодна адреса не підтверджується як гаманець GasFree, доки до списку знову не буде отримано доступ.
Коди причин і постачальник даних
Для aml_risk поля reason_code і label описують, чому адреса внесена до списку. Офіційні санкційні органи залишаються без змін — SANCTIONS_OFAC_SDN, SANCTIONS_EU_FSF, SANCTIONS_UK_FCDO тощо. Назва комерційного провайдера перевірки за виявленим фактом ніколи не розкривається: такі коди нормалізуються до SANCTIONS_SCREENING, а будь-яка назва постачальника видаляється з label.
Розмір списку заборон
GET https://netts.io/apiv2/compliance/statsСукупні розміри списків, що формують вердикт, з того самого кешу. Відкрито і без ключів.
{
"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 — це найбільша AML-нейтральна частина загальної кількості (див. примітку про контракти вище). gasfree_wallets_subset (активні гаманці GasFree) та selfdestructed_contracts_subset (видалені контракти) є частинами smart_contract; вони не додаються до total. Якщо один із цих двох лічильників не вдається прочитати просто зараз, він повертає null, а інші числа все одно повертаються.
Пакетна перевірка (API-ключ)
Для одночасної перевірки багатьох адрес використовуйте автентифіковану пакетну кінцеву точку. Вона існує, щоб заощадити кількість мережевих запитів: один запит і один внутрішній конвеєр замість N окремих GET-запитів. Перевірка однієї адреси є просто масивом із одного елемента.
POST https://netts.io/apiv2/compliance/batch
x-api-key: YOUR_KEY
Content-Type: application/json
{ "addresses": ["TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC"] }До 1000 адрес на запит. Вердикти повертаються в тому ж порядку, кожен із тими самими полями, що й у відповіді для однієї адреси (включно з subtype, subtype_status, matches та checks_complete), плюс category: "invalid" (з полем error) для кожного некоректного запису — одна помилкова адреса не порушує обробку всієї пачки. Якщо центральний список заборон не завантажено, адреса, яка інакше була б чиста, повертається як category: "unavailable" (blocked: null, з полем error) замість clean — див. Центральний список заборон недоступний.
{
"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 }
]
}
}Пакетна кінцева точка вимагає API-ключ (заголовок x-api-key), і ключ можна опціонально прив'язати до білого списку IP-адрес. Зв'яжіться з нами, щоб отримати ключ.
Її ліміт частоти запитів розраховується на ключ і є вищим, ніж для публічної кінцевої точки для однієї адреси:
| Period | Limit |
|---|---|
| 1 секунда | 200 запитів |
| 1 хвилина | 12 000 запитів |
Кожен запит може містити до 1000 адрес, тому за цього ліміту один ключ може перевіряти понад сто тисяч адрес на секунду.
Відповіді з помилками
Неправильний формат адреси (400)
{
"code": 1001,
"status": "error",
"msg": "Invalid TRON address format (expected base58, 'T' + 33 chars)"
}Сервіс тимчасово недоступний (503)
{
"code": 5003,
"status": "error",
"msg": "compliance service temporarily unavailable"
}Центральний список заборон недоступний (503, код 5004)
Вердикт надається з кешу в оперативній пам'яті. Якщо цей кеш доступний, але центральний AML-список заборон наразі не завантажений або його поточна версія не проходить перевірку цілісності, кінцева точка не перемикається на повернення clean — це означало б помилкове маркування неперевіреної адреси як безпечної. Натомість вона прямо повідомляє про неможливість винести вердикт:
{
"code": 5004,
"status": "error",
"msg": "compliance deny-list temporarily unavailable, verdict cannot be produced"
}Що це означає: адреса ані підтверджено чиста, ані заблокована. Сервіс не зміг перевірити її за санкційним/AML-списком просто зараз. Не вважайте адресу чистою — повторіть спробу незабаром.
Точне блокування все одно повертається у звичайному режимі: якщо адреса знайдена серед заморожених у USDT, смартконтрактів або розсильників спаму (списки, які не залежать від центрального списку), ви отримаєте звичний вердикт blocked: true навіть у цьому стані. Лише потенційна відповідь clean перетворюється на 5004.
У пакетній кінцевій точці ця ж ситуація повертається для кожної адреси як category: "unavailable" (blocked: null, з полем error); на решту пачки це не впливає. Це рідкісний перехідний стан.
Реєстр недоступний (503, код 5005)
Списки оновлюються на місці та залишаються доступними для читання під час оновлення, тому стандартне оновлення ніколи не впливає на вердикт. Лише у випадку, якщо список не вдалося застосувати, чиста в іншому випадку адреса не може бути підтверджена як чиста. Тоді кінцева точка для однієї адреси повертає:
{
"code": 5005,
"status": "error",
"msg": "address registry temporarily unavailable, verdict cannot be produced, retry shortly"
}Як і з 5004, точне блокування все одно повертається як зазвичай, а пакетна кінцева точка повертає для адреси category: "unavailable". Повторіть спробу пізніше.
Довідник кодів помилок
| Code | Description | HTTP Status |
|---|---|---|
0 | Успішно | 200 |
1001 | Неправильний формат адреси TRON | 400 |
5003 | Бекенд кешу тимчасово недоступний | 503 |
5004 | Центральний список заборон не завантажено — вердикт не може бути сформований (повторіть спробу) | 503 |
5005 | Не вдалося застосувати список — вердикт не може бути сформований (повторіть спробу) | 503 |
Ліміти запитів
Є два рівні обмежень, які застосовуються на шлюзі:
| Endpoint | Auth | Limited by | 1 second | 1 minute |
|---|---|---|---|---|
GET /apiv2/compliance/{address} | відкрита, без ключів | IP | 10 | 300 |
GET /apiv2/compliance/stats | відкрита, без ключів | IP | 10 | 300 |
POST /apiv2/compliance/batch | API-ключ | ключ | 200 | 12 000 |
Відкрита кінцева точка для однієї адреси призначена для інтерактивного та легкого програмного використання. Для масової перевірки використовуйте пакетну кінцеву точку: за ліміту до 1000 адрес на запит і 200 запитів/секунду на один ключ, один ключ може перевіряти значно більше ста тисяч адрес на секунду. Потрібно більше? Ліміт на ключ регулюється налаштуваннями політики, а не технічними обмеженнями — зв'яжіться з нами.
Перевищено ліміт запитів (429)
{
"message": "API rate limit exceeded"
}Примітки
- Без автентифікації та безкоштовно. Будь-хто може викликати її; підписувати запити не потрібно.
- Тільки кеш. Формування вердикту ніколи не звертається до бази даних або вузла, тому воно працює швидко і безпечно для опитування в межах встановлених лімітів.
- Не є повним AML-звітом. Для отримання оцінки ризику, деталізації впливу та підписаного звіту використовуйте захищене API скринінгу (POST /apiv2/screening). Ця кінцева точка відповідає на одне більш вузьке питання: чи є адреса в нашому списку заборон і чому.