Команда форензики и комплаенса · Не юридическая фирма · Не аффилированы с Tether · Читать дисклеймер

Разработчикам / Документация

Справочник API скрининга USDT

REST-документация API скрининга USDT.Lawyer: проверка по блэклисту, сверка с OFAC SDN и информация о кошельке. JSON по HTTPS, без ключа, без токена и без регистрации.

—USDT заморожено · за всё время
—Событий блэклиста USDT · за всё время
—Заморозок USDT · за 24 ч

С чего начать

01

Выберите эндпоинт

POST /api/check/lookup — статус адреса в блэклисте; GET /api/sanctions/ofac/check — сверка со списком OFAC SDN; GET /api/wallet/info — его балансы.

02

Вызывайте со своего сервера

Отправьте запрос по HTTPS со своего бэкенда. Ключ, токен и регистрация не нужны. API не отдаёт заголовков CORS, поэтому страница в браузере на другом домене не сможет прочитать его ответы.

03

Отправляйте JSON в проверку

Проверка читает тело в JSON: укажите Content-Type: application/json. Без этого заголовка тело не читается, и ответ — 400 invalid_address.

04

Обработайте ответ

Сначала разберите поля 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. [1] OFAC, Sanctions List Service: “the SDN list contains the names of individuals, entities and groups designated by OFAC”
  2. [2] OFAC, вопросы о виртуальной валюте, FAQ 594: “only exact matches will be returned when searching for digital currency addresses”
  3. [3] OFAC, вопросы о виртуальной валюте, FAQ 562: “OFAC’s digital currency address listings are not likely to be exhaustive.”

Похожее

Все руководства по замороженному USDT →