GET /apiv2/compliance/

Открытая проверка комплаенса без ключа для одного адреса TRON. Она возвращает вердикт — заблокирован ли адрес и в какой категории — полностью из кэша списков блокировки в оперативной памяти. Без API-ключа, без баланса, бесплатно. Цель — позволить любому интегрировать уровень комплаенса с помощью одного HTTP GET.

Эндпоинт обращается только к кэшу, никогда к базе данных или ноде сети, поэтому проверка занимает доли миллисекунды. Шлюз ограничивает частоту запросов с каждого IP.

URL эндпоинта

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

Заголовки аутентификации не требуются.

Параметры запроса

Параметр	Тип	Обязательный	Описание
address	string	Да	Адрес TRON в формате base58 — символ T и следующие за ним 33 знака

Примеры запросов

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);

Ответ

Заблокирован — находится в центральном списке блокировки (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"
    }
}

Поля ответа

Поле	Тип	Описание
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):

Категория	blocked	Значение
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

Охват и нюансы:

• Известны только развернутые кошельки. Адрес GasFree, который получил USDT, но еще ничего не отправлял, пока не развернут, поэтому он не входит ни в один набор и возвращается как clean.
• Подтип указывает, куда адрес может принимать средства. Он ничего не говорит о переводах с кошелька GasFree; проверяйте адрес отправителя отдельно.
• subtype_status: "unavailable" означает, что к списку GasFree не удалось обратиться. Остальная часть вердикта (blocked, category, matches) остается действительной.
• Сам контроллер и другие контракты не являются кошельками GasFree: они возвращаются с subtype: null.

Удаленные контракты

Контракт может удалить сам себя (self-destruct). Адрес остается в наборе 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-адресов. Свяжитесь с нами для получения ключа.

Ограничение частоты запросов действует на ключ и установлено выше, чем у публичного эндпоинта для одиночных адресов:

Период	Лимит
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 даже в этом состоянии. Ошибку 5004 вызывают только те ответы, которые потенциально могли бы стать clean.

В пакетном эндпоинте эта же ситуация отображается для конкретного адреса со значением 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". Повторите попытку позже.

Справочник кодов ошибок

Код	Описание	HTTP-статус
0	Успешно	200
1001	Неверный формат адреса TRON	400
5003	Бэкенд кэша временно недоступен	503
5004	Центральный список блокировки не загружен — невозможно сформировать вердикт (повторите попытку)	503
5005	Не удалось применить набор данных — невозможно сформировать вердикт (повторите попытку)	503

Ограничения частоты запросов

Существует два уровня ограничений, которые применяются на шлюзе:

Эндпоинт	Аутентификация	Критерий лимита	1 секунда	1 минута
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). Этот эндпоинт отвечает на один конкретный вопрос: находится ли адрес в нашем списке блокировки и по какой причине.