Разработчикам / Документация
Справочник API скрининга USDT
REST-документация API скрининга USDT.Lawyer: проверка по блэклисту, сверка с OFAC SDN и информация о кошельке. JSON по HTTPS, без ключа, без токена и без регистрации.
С чего начать
Выберите эндпоинт
POST /api/check/lookup — статус адреса в блэклисте; GET /api/sanctions/ofac/check — сверка со списком OFAC SDN; GET /api/wallet/info — его балансы.
Вызывайте со своего сервера
Отправьте запрос по HTTPS со своего бэкенда. Ключ, токен и регистрация не нужны. API не отдаёт заголовков CORS, поэтому страница в браузере на другом домене не сможет прочитать его ответы.
Отправляйте JSON в проверку
Проверка читает тело в JSON: укажите Content-Type: application/json. Без этого заголовка тело не читается, и ответ — 400 invalid_address.
Обработайте ответ
Сначала разберите поля status и onchain, затем token, frozenBalance и events, и кэшируйте ответ: опубликованной квоты и SLA нет, поэтому не отправляйте запросы слишком часто.
Базовый URL
https://usdt.lawyer
OpenAPI 3.1
Все публичные эндпоинты с параметрами, полями ответа и ошибками — в одном машиночитаемом файле: https://usdt.lawyer/openapi.json
Доступ
Аутентификации нет: сервер не выдаёт ключей, не проверяет учётных данных и отвечает любому, кто к нему обращается. Префикса версии в путях нет. Опубликованной квоты и SLA нет, поэтому, пожалуйста, кэшируйте полученные ответы и не отправляйте запросы слишком часто. API рассчитан на вызовы между серверами и не отдаёт заголовков CORS: вызывайте его со своего бэкенда, а не со страницы в браузере на другом домене.
Заголовок запроса (проверка)
Content-Type: application/json
POST /api/check/lookup
Проверка заморозки и блэклиста
Возвращает состояние одного адреса в блэклисте. Есть ли адрес в блэклисте USDT от Tether сейчас, проверка читает в момент запроса из самого контракта USDT (getBlackListStatus в TRON или Ethereum); историю она берёт из нашего индекса событий блэклиста: баланс, записанный при действующей заморозке, и все события по адресу (от старых к новым, не больше 1000). В нашем индексе есть известные пробелы, они перечислены на /methodology. Используйте это, чтобы ответить на вопрос «в блэклисте ли этот кошелёк и с какого времени?».
Изменено 7 ноября 2026 года
- ✓status теперь — текущий статус: в блэклисте ли адрес, решает контракт USDT от Tether. Раньше это было то, что говорил один наш индекс; это значение теперь в indexStatus.
- ✓TON и Solana теперь возвращают status unknown вместо not_found. С любым другим значением network контракт не читается (onchain "unknown"), но адрес 0x всё равно ищется в индексе, и может вернуться история и статус адреса Ethereum: отправляйте TRC20 или ERC20.
- ✓status frozen может прийти с events: [] и без firstSeen и lastSeen: контракт числит адрес в блэклисте, а события нет в нашем индексе (mismatch "not_in_index").
- ✓Новые поля: onchain, checkedOnChainAt, indexStatus, mismatch, explorerUrl. Ни одно поле не удалено.
Запрос
POST /api/check/lookup
Content-Type: application/json
{
"network": "TRC20",
"address": "<TRON address>"
}Параметры
- ✓network — отправьте «TRC20» (TRON) или «ERC20» (Ethereum); также принимаются «TRX», «TRON», «ETH» и «ETHEREUM» в любом регистре. Указывайте его всегда: без него адрес TRON отклоняется, а адрес в формате Ethereum ищется во всех сетях индекса. «TON» и «SOL» проходят проверку адреса, но ни индекс, ни чтение контракта их не покрывают, поэтому ответ всегда unknown, а onchain — "unknown".
- ✓address — обязательный. Адрес в формате своей сети; у адресов TRON проверяется контрольная сумма. На отсутствующий, некорректный или чужой для сети адрес приходит 400 invalid_address.
Ответ 200
{
"status": "burned", // frozen | unfrozen | burned | not_found | unknown
"address": "TXyZ…demo",
"network": "TRX", // TRX | ETH
"token": "USDT", // USDT | USDC
"firstSeen": "2026-03-11 08:42:13",
"lastSeen": "2026-04-02 15:09:51",
"frozenBalance": 0,
"burnedAmount": 48250,
"eventCount": 2,
"events": [
{
"event": "AddedBlackList",
"kind": "frozen",
"network": "TRX",
"token": "USDT",
"amount": 0,
"balance": 48250,
"time": "2026-03-11 08:42:13",
"block": 70512345,
"tx": "9af31c…e07b"
},
{
"event": "DestroyedBlackFunds",
"kind": "burned",
"network": "TRX",
"token": "USDT",
"amount": 48250,
"balance": 0,
"time": "2026-04-02 15:09:51",
"block": 71148802,
"tx": "12bd84…aa90"
}
],
"onchain": true, // true | false | "unknown"
"checkedOnChainAt": "2026-11-07T10:21:04.512Z",
"indexStatus": "burned", // what our index alone says
"mismatch": null, // null | "not_in_index" | "not_on_chain"
"explorerUrl": "https://tronscan.org/#/address/TXyZ…demo"
}Значения статуса
- ✓frozen — адрес в блэклисте. Для USDT это говорит контракт Tether, а если его не удалось прочитать (onchain "unknown"), — действующая заморозка в нашем индексе. Для USDC — действующая заморозка в нашем индексе; контракт Circle не читается.
- ✓unfrozen — сейчас адрес не в блэклисте (так говорит контракт), а в нашем индексе есть более ранняя заморозка. При mismatch "not_on_chain" самого снятия в нашем индексе нет.
- ✓burned — эмитент уничтожил замороженный баланс (DestroyedBlackFunds); адрес остаётся в блэклисте.
- ✓not_found — контракт USDT от Tether говорит, что адрес не в блэклисте, и в нашем индексе нет ни одного события по нему; ответ тогда {"status":"not_found","events":[]} плюс поля ниже, начиная с onchain.
- ✓unknown — текущий статус установить не удалось: контракт не прочитан (onchain "unknown"), а в нашем индексе нет действующей заморозки, или сеть — не TRON и не Ethereum, или в индексе есть записи, которые проверка не может классифицировать. Никогда не считайте это ответом «не в блэклисте».
Поля
- ✓network — код сети в индексе: TRX или ETH.
- ✓token — USDT, если у адреса есть хотя бы одно событие USDT; иначе токен его последнего события. События блэклиста USDC от Circle лежат в том же индексе.
- ✓frozenBalance — баланс, записанный при действующей заморозке, а не текущий баланс; 0 после разморозки или сжигания и 0, если действующей заморозки нет в нашем индексе (mismatch "not_in_index"). burnedAmount — сколько всего уничтожено.
- ✓events — все события по адресу в индексе, от старых к новым, не больше 1000. time — «YYYY-MM-DD HH:MM:SS», как хранит индекс; amount — уничтоженная сумма при сжигании и 0 в остальных случаях; tx сокращён до первых 6 и последних 4 символов.
- ✓onchain — true, false или "unknown": getBlackListStatus контракта USDT от Tether для этого адреса. Прочитанный ответ используется повторно до 2 минут. "unknown" — контракт не удалось прочитать примерно за 3 секунды, сервер исчерпал свой лимит чтений контракта (общий для всех или около 30 проверок в минуту от одного клиента; ответ всё равно приходит, по нашему индексу), второй хост не подтвердил ответ false, который снял бы действующую заморозку из нашего индекса, или сеть не TRON и не Ethereum. Только USDT.
- ✓checkedOnChainAt — когда прочитан контракт, ISO 8601 в UTC; null, если onchain равен "unknown".
- ✓indexStatus — что говорит один только наш индекс, с теми же значениями, что и status: статус, который эта проверка возвращала до чтения контракта.
- ✓mismatch — null, если контракт и наш индекс согласны; "not_in_index", если контракт говорит «в блэклисте», а в нашем индексе нет действующей заморозки (тогда firstSeen, lastSeen и баланс при заморозке отсутствуют или относятся к более ранним событиям); "not_on_chain", если в нашем индексе есть действующая заморозка, а контракт говорит «не в блэклисте».
- ✓explorerUrl — адрес в Tronscan или Etherscan, где можно проверить собственную запись контракта; null для других сетей.
cURL
curl -X POST https://usdt.lawyer/api/check/lookup \
-H "Content-Type: application/json" \
-d '{"network":"TRC20","address":"<TRON address>"}'GET /api/wallet/info
Информация о кошельке
Читает из блокчейна текущий баланс USDT и баланс нативной монеты адреса в TRON, Ethereum, Solana или TON. Ответы кэшируются на 60 секунд. По санкционным спискам адрес не проверяется; криптоадреса из списка OFAC SDN отдают GET /api/sanctions/ofac и GET /api/sanctions/ofac/check. AML-скоринг рисков транзакций не входит в этот эндпоинт — это отдельный продукт на AMLOfficer.org.
Запрос
GET /api/wallet/info?network=TRC20&address=<TRON address>
Параметры
- ✓network — обязательный: «TRC20», «ERC20», «SOL» или «TON» (также «TRX», «TRON», «ETH», «ETHEREUM» и «SOLANA» в любом регистре).
- ✓address — обязательный, в формате этой сети.
- ✓totalTxCount и lastActivity читаются по возможности и могут быть null: в Ethereum это число транзакций, отправленных с адреса, в Solana счёт останавливается на 1000 (тогда totalTxCountIsFloor равен true), а в TON он всегда null.
Ответ 200
{
"ok": true,
"info": {
"network": "TRC20",
"address": "TXyZ…demo",
"usdtBalance": 48250,
"nativeBalance": 12.5,
"nativeSymbol": "TRX",
"totalTxCount": 214,
"lastActivity": "2026-03-10T19:02:11.000Z",
"explorerUrl": "https://tronscan.org/#/address/TXyZ…demo"
}
}cURL
curl "https://usdt.lawyer/api/wallet/info?network=TRC20&address=<TRON address>"
GET /api/sanctions/ofac/check
Проверка по OFAC SDN
Проверяет один адрес по криптоадресам из списка OFAC SDN. Сервер хранит копию файла SDN.XML из Sanctions List Service OFAC[1] и раз в 24 часа проверяет, не вышел ли новый файл; скачивает его, только если он изменился, а при неудачной загрузке оставляет последнюю исправную копию. Совпадение точное, как в поиске самого OFAC[2]: адреса 0x и bech32 сравниваются в нижнем регистре, адреса base58 (TRON, старые адреса Bitcoin) — как написаны. Сверяются адреса с любой пометкой валюты в списке, а не только TRON и Ethereum.
Запрос
GET /api/sanctions/ofac/check?address=<address>
Параметры
- ✓address — обязательный, не длиннее 128 символов, пробелы по краям отбрасываются. Формат сети не проверяется: адрес только сверяется со списком.
Ответ 200
{
"ok": true,
"listed": true, // true | false
"hits": [
{
"list": "OFAC SDN",
"address": "TXyZ…demo",
"currency": "USDT",
"uid": 12345,
"entity": null, // null for an individual
"type": "Individual",
"programs": ["…"],
"firstSeen": null,
"entryUrl": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=12345"
}
],
"publishDate": "2026-11-06",
"checkedAt": "2026-11-09T17:32:39.912Z",
"baselineDate": "2026-11-06"
}Поля
- ✓listed — true, если адрес — идентификатор хотя бы одной записи SDN в проверенной копии. false не означает, что адрес чист: по словам OFAC, его списки адресов вряд ли исчерпывающие[3].
- ✓hits — по одному на каждое включение: list ("OFAC SDN"), address в написании списка, currency (пометка после "Digital Currency Address -"), uid (ID записи SDN), entity (название записи; null для физического лица), type, programs и entryUrl (запись в поиске OFAC).
- ✓firstSeen — дата публикации первого файла, в котором наша загрузка увидела адрес; null, если адрес был уже в первом прочитанном файле. В файле SDN нет даты по каждому адресу.
- ✓publishDate — дата публикации проверенного файла. checkedAt — когда сервер в последний раз убедился, что у него текущий файл OFAC, ISO 8601 в UTC. baselineDate — дата публикации первого прочитанного файла.
cURL
curl "https://usdt.lawyer/api/sanctions/ofac/check?address=<address>"
Весь список
GET /api/sanctions/ofac возвращает всё прочитанное: sourceUrl, publishDate, recordCount, sha256, fetchedAt, checkedAt, baselineDate, сводку summary (identifiers, addresses, entries, byCurrency) и строки rows (address, currency, uid, name, type, programs, firstSeen). ?currency=USDT,TRX фильтрует строки, но не сводку. GET /api/sanctions/ofac.csv — тот же список в CSV. Оба кэшируются на час (max-age=3600); проверка отдаётся с no-cache.
Ошибки
Тело ошибки (проверка)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{ "error": "invalid_address" }- ✓400 invalid_address — проверка: адрес отсутствует, короче 10 символов, некорректен или не в формате переданной сети. Тело без Content-Type: application/json не читается, и на него приходит тот же ответ.
- ✓500 internal_error — проверка: сервер не смог ответить, например не удалось прочитать индекс или тело не было корректным JSON. Повторите позже.
- ✓Информация о кошельке отвечает HTTP 200, даже когда не удалась: {"ok":false,"info":null,"reason":…}, где reason — "invalid" (адрес отсутствует или некорректен), "unsupported" (сеть не указана или не одна из четырёх) или "fetch_failed" (не удалось прочитать блокчейн).
- ✓404 — неизвестный путь или метод. Тело — HTML-страница, а не JSON.
- ✓Проверка OFAC, 400 invalid_address — адрес не передан или длиннее 128 символов; тело — {"ok":false,"error":"invalid_address"}.
- ✓Эндпоинты OFAC, 503 unavailable — копия списка ещё не загружена, так бывает только сразу после первого запуска; тело JSON — {"ok":false,"error":"unavailable"}, CSV отвечает простым текстом. Повторите через 10 минут.
Источники
- [1] OFAC, Sanctions List Service: “the SDN list contains the names of individuals, entities and groups designated by OFAC”
- [2] OFAC, вопросы о виртуальной валюте, FAQ 594: “only exact matches will be returned when searching for digital currency addresses”
- [3] OFAC, вопросы о виртуальной валюте, FAQ 562: “OFAC’s digital currency address listings are not likely to be exhaustive.”
Похожее
Ещё по теме
- Проверка блэклиста USDT
Вставьте адрес TRON или Ethereum, чтобы узнать, заморозил ли его Tether.
- USDT заморожен: что делать
Подтвердить заморозку, сохранить доказательства, не платить тем, кто обещает разморозку.
- Скам с разморозкой USDT или настоящая заморозка?
Как отличить заморозку Tether от мошенников, которые просят плату за разморозку.
- Как разморозить USDT
Как строится дело о снятии необоснованной заморозки. Результат не гарантирован.
- Почему Tether замораживает кошельки?
Запросы правоохранительных органов, санкции и собственные правила Tether.
- Что такое блэклист USDT?
Функция контракта, которая позволяет Tether заморозить адрес.