Перевірки адрес

Перевірка адреси скринить одну адресу в одному активі й відповідає вердиктом: score, band, знахідками, що змінили оцінку, та всім, що потрібно, щоб правильно прочитати його й пізніше відтворити. Щоб перевірити транзакцію, див. Перевірки транзакцій.

Запит

POST /v1/checks зі scope checks:write (див. Автентифікація).

Поле	Обов'язкове	Опис
`subject`	так	`"address"`.
`asset`	так	Символ активу точно так, як у Підтримуваних активах, не більше 20 символів.
`address`	так	Адреса для перевірки, не більше 160 символів. Її форма має бути чинною для активу.

Невідомі поля відхиляються. Надсилайте заголовок Idempotency-Key зі своїм ідентифікатором операції, щоб повторений запит ніколи не виконував перевірку чи списання вдруге; див. Ідемпотентність.

curl
Node.js
Python

curl -s -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Idempotency-Key: customer-8841-onboarding" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"TRX","address":"'"$ADDRESS"'"}'

const response = await fetch('https://api.leeri.ai/v1/checks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Idempotency-Key': 'customer-8841-onboarding',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ subject: 'address', asset: 'TRX', address }),
});
const { data } = await response.json();

if (data.status === 'completed') console.log(data.band, data.score);
else console.log('pending, poll', data.check_id);

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/checks",
    headers={
        "Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
        "Idempotency-Key": "customer-8841-onboarding",
    },
    json={"subject": "address", "asset": "TRX", "address": address},
    timeout=30,
)
data = response.json()["data"]

if data["status"] == "completed":
    print(data["band"], data["score"])
else:
    print("pending, poll", data["check_id"])

Відповідь

Успішні відповіді мають один конверт: зовнішній status дорівнює "ok", перевірка лежить у data, а errors порожній. Помилки натомість використовують конверт помилки.

Сама перевірка має одну форму для кожного стану. Розгалужуйтеся лише за data.status:

`data.status`	Значення
`completed`	Вердикт завершився в межах запиту й міститься у відповіді.
`pending`	Перевірку передано в чергу. Опитуйте `GET /v1/checks/{check_id}` або чекайте вебхук; див. Pending і опитування.
`failed`	Перевірка завершилася без вердикту. За неї ніколи не списують. `POST` відповідає `422` `CHECK_FAILED`; цей статус ви побачите, читаючи перевірку пізніше.

Кожне поле присутнє в кожному стані. Якщо перевірці в стані pending або failed ще нічого повідомити, поле дорівнює null (або це порожній список). Нижче скорочений приклад завершеної перевірки; значення умовні.

{
  "status": "ok",
  "data": {
    "check_id": "5b0c3f64-1a52-4c8e-9f3e-2f6c1d7a9e10",
    "verdict_id": "0f4d7e1c-6b2a-4d39-8e55-3a9c2b8f7d41",
    "status": "completed",
    "subject": "address",
    "asset": "TRX",
    "chain": "tron",
    "address": "TEXAMPLEexampleEXAMPLEexample00000",
    "score": 74,
    "band": "high",
    "analysis_depth": "full",
    "partial": false,
    "partial_reasons": [],
    "degraded_sources": [],
    "ruleset_version": "v23",
    "label_snapshot_id": "412345",
    "chain_height": "68000000",
    "findings": [
      {
        "rule_id": "heuristic:transit",
        "category": "unknown",
        "weight": "25",
        "source": "chain-engine",
        "source_url": "https://leeri.ai/rules/transit?v=v23",
        "source_kind": "methodology",
        "provider": null,
        "observed": { "role": "subject", "score": 62 }
      }
    ],
    "report": {
      "id": "r1_…",
      "pdf_url": "…",
      "json_url": "…",
      "verification_url": "…"
    },
    "created_at": "2026-10-27T09:14:02.118Z",
    "completed_at": "2026-10-27T09:14:04.907Z"
  },
  "errors": []
}

Як читати вердикт

Ідентифікація і час

Поле	Значення
`check_id`	Ідентифікатор перевірки. Використовуйте його для опитування та повторного читання перевірки.
`verdict_id`	Ідентифікатор вердикту, який створила перевірка, і той, який приймає `POST /v1/verdicts/{verdict_id}/rederive`. `null`, доки перевірка не завершиться.
`status`	`completed`, `pending` або `failed`.
`subject`	`address` або `transaction`.
`asset`	Символ активу, який ви надіслали.
`chain`	Блокчейн, у якому живе актив, наприклад `tron`. `null`, якщо в активу його немає.
`address`	Адреса, яку перевірено.
`created_at`, `completed_at`	Коли перевірку прийнято і коли вона завершилася. `completed_at` дорівнює `null` до того часу.

Оцінка і рівень ризику

Поле	Значення
`score`	Число від 0 до 100. `null`, доки перевірка не завершиться.
`band`	Рівень ризику, у який потрапляє оцінка: `low`, `medium`, `high` або `severe`. `null`, доки перевірка не завершиться.
`analysis_depth`	`full` для активів, що перевіряються з обходом графа та експозицією за кроками; `label_only` для активів, що перевіряються пошуком мітки за адресою без обходу. Обидві відповіді справжні й тарифікуються; це поле каже, яку саме ви отримали, тож результат `label_only` ніколи не сплутають із глибшим. Див. Підтримувані активи.

У поточному наборі правил рівні такі: low для оцінок 0–30, medium для 31–70, high для 71–90 і severe для 91–100. Межі належать версії набору правил, тому читайте рівень із поля band, а не перераховуйте його з оцінки.

Наскільки повний вердикт

Збій стороннього джерела даних не перетворюється на помилку. Перевірка відповідає вердиктом, який каже, що він неповний, і чому. Сприймайте частковий вердикт як вердикт із меншою кількістю свідчень, а не як чистий.

Поле	Значення
`partial`	`true`, коли джерело, від якого залежить вердикт, було недоступне чи застаріле, обхід був неповним або відповідь обмежена заявленою межею рушія.
`partial_reasons`	Причини у вигляді стабільних кодів. Деякі вказують на межу аналізу (ліміт глибини чи розміру обходу, лише прямі контрагенти в Ethereum, BNB Smart Chain і Base); тоді вердикт є повним сервісом для цієї адреси й тарифікується. Інші вказують, що джерело було недоступне; за такий вердикт не списують, і його можна виконати знову пізніше. Повний перелік — в довіднику API.
`degraded_sources`	Джерела, що були недоступні, подані як `provider` і ніколи за назвою. Будь-який запис тут робить вердикт безкоштовним.
`provider_fallback`	Які збережені відповіді стороннього джерела даних підмінили відповідь, бо це джерело не відповіло, і наскільки стара найстаріша з них (`addresses`, `reasons`, `oldest_answer_at`, `oldest_answer_age_days`). `null`, доки перевірка в стані pending чи failed. Об'єкт із порожнім списком `addresses`, якщо нічого не використовувалося.
`coverage_limitations`	Чого не може показати джерело даних блокчейну для цього активу, зазначено у вердикті: `evm_internal_transfers` (нативна монета, переміщена викликом контракту, не видима), `untraced_inbound_majority` (понад половину вхідних коштів не вдалося простежити до джерела, тож оцінка може занижувати експозицію) і `unpriced_assets` (переміщено актив, який не вдалося оцінити в USD). Це твердження, а не часткові результати: вони не встановлюють `partial` і не змінюють тарифікацію.
`exposureIndexLag`	`true`, коли існує новіший запуск атрибуції депозитів, ніж дані експозиції, використані цим вердиктом. Прямі мітки доступні; глибша атрибуція чекає наступного перерахунку.

Вердикт виводиться з трьох координат, записаних у ньому, щоб його можна було відтворити точно так, як його видано.

Поле	Значення
`ruleset_version`	Версія застосованих правил оцінювання.
`label_snapshot_id`	Позиція в історії міток, яку прочитав вердикт.
`chain_height`	Висота ланцюга, на якій виведено вердикт.
`pin`	Ті самі три координати в одному об'єкті плюс те, що вердикт прочитав з індексу експозиції (`index`, а також `exposure` із `method`, `execution_mode` та іншими полями). `null`, доки перевірка в стані pending чи failed.

Зберігайте check_id, verdict_id і pin разом зі своїм записом про рішення. Rederive вердикту (POST /v1/verdicts/{verdict_id}/rederive, scope checks:read) відтворює його за закріпленим набором правил і знімком міток, ніколи не за новішими; див. Rederive.

Знахідки

findings перелічує правила, що змінили оцінку. Знахідка ніколи не є числом без пояснення: кожна вказує, що спрацювало й де лежать свідчення.

Поле	Значення
`rule_id`	Правило, що спрацювало.
`category`	Наша категорія мітки: `exchange`, `mixer`, `sanctioned`, `scam`, `contract`, `bridge`, `merchant`, `unknown`, `ransomware`, `exploit`, `gambling`, `illicit`, `high_risk_exchange` або `unidentified_service`.
`weight`	Скільки знахідка важить в оцінці, десятковим рядком.
`source`	Звідки знахідка: короткий код публічного джерела, `chain-engine` для наших власних евристик або `provider`, коли вона спирається на стороннє джерело даних. Жодне джерело даних ніколи не називається.
`source_url`	Посилання, що завжди відкривається й ніколи не дорівнює `null`.
`source_kind`	На що вказує `source_url`. `document` — публічний першоджерельний документ, наприклад список органу влади чи опублікована подія заморожування. `methodology` — версійована сторінка на https://leeri.ai/uk/rules, що описує, що виявляє правило й чому воно спрацювало в цій версії набору правил.
`provider`	Завжди `null` для знахідки, що спирається на стороннє джерело даних.
`evidence_chain`, `evidence_tx_hash`	Блокчейн і транзакція, на які вказує знахідка, якщо вони є.
`observed`	Що спостерігала перевірка за знахідкою: роль адреси, кількості, суми в USD, кроки, залучені адреси й транзакції. `null` лише для перевірки, виконаної до того, як почали записувати спостереження. Свідчення, а не оцінка.
`evidence_refs`	Додаткові структуровані свідчення. Невідомі ключі сприймайте як інформаційні.

Експозиція

exposure показує, звідки прийшли або куди пішли кошти адреси, за категорією, кроком і напрямом, щоб ви бачили, наскільки опосередкований ризиковий зв'язок.

Поле	Значення
`category`	Категорія групи контрагентів.
`hop`, `hop_to`	Відстань від перевіреної адреси; `0` — прямий контрагент. Після кроку 8 зріз охоплює діапазон кроків від `hop` до `hop_to`.
`direction`	`in` для отриманих коштів, `out` для надісланих.
`amount_usd`, `share`	Вартість зрізу та його частка від загальної суми, десятковими рядками.
`address_count`	Скільки адрес охоплює зріз.
`scoring`	Чи враховується зріз в оцінці, чи показаний лише для контексту.
`source`	Присутнє як `provider` лише у зрізі, про який повідомило стороннє джерело даних.

Зрізи нашого власного обходу відсутні для активу label_only, а список порожній для адреси, яка сама є відомим контрактом токена; в обох випадках це задумано, а не наслідок збою обходу.

Попередження безпеки гаманця

wallet_security_warnings містить сигнали для власника перевіреної адреси, як-от отруєння адреси, схожа на неї підробка, фальшиві токени. Вони нічого не кажуть про ризикованість адреси й ніколи не змінюють оцінку, рівень ризику чи будь-яку знахідку. Кожне має rule_id, severity (critical, high, warning або info), source, source_url, source_kind (завжди methodology), observed і evidence_refs. Список завжди присутній і порожній, поки перевірка в стані pending чи failed.

Поля транзакції

tx_hash, direction, amount і risky_volume_usd описують перевірку транзакції й дорівнюють null у перевірці адреси. amount і risky_volume_usd — десяткові рядки, ніколи не числа з рухомою комою. Див. Перевірки транзакцій.

Поля очікування

pending_reason, deadline_at і next_attempt_at описують перевірку, що ще в стані pending, і дорівнюють null, коли вона завершена. Див. Pending і опитування.

Доказовий звіт

report містить посилання на доказовий звіт завершеної перевірки; звіт входить у ціну перевірки. Він має id, pdf_url, json_url і verification_url, а в стані pending чи failed дорівнює null. id — це capability: кожен, хто його має, може відкрити звіт, тож ставтеся до нього як до самого звіту. JSON-двійник містить хеш свого вмісту, а сторінка верифікації підтверджує, що звіт справжній і не змінений; див. Доказові звіти.

Тарифікація і помилки

Повторна перевірка тієї самої адреси в тому самому блокчейні протягом 7 днів безкоштовна; див. Обмеження частоти запитів і ліміти. Помилки, яких слід очікувати від POST /v1/checks:

Статус	Код	Коли
`400`	`VALIDATION_ERROR`	Невідоме або відсутнє поле, або адреса з недійсною для активу формою.
`422`	`UNSUPPORTED_ASSET`	Активу немає в Підтримуваних активах.
`402`	`INSUFFICIENT_BALANCE`	Ліміт і попередньо поповнений баланс вичерпані.
`429`	`PROVIDER_CAPACITY_EXCEEDED`	Ємність для запитів заповнена. Повторіть після `Retry-After`; нічого не прийнято й не списано.
`503`	`RULESET_UNAVAILABLE`	Жоден набір правил оцінювання недоступний. Ніколи не вердикт, що виглядає чистим, і ніколи не списується.

Помилки автентифікації та обмеження частоти описано в Автентифікації і Обмеженнях частоти запитів і лімітах. Якщо вебхук зареєстровано, завершена перевірка також доставляється на нього один раз; див. Вебхуки.

Запит​

Відповідь​

Як читати вердикт​

Ідентифікація і час​

Оцінка і рівень ризику​

Наскільки повний вердикт​

Pin​

Знахідки​

Експозиція​

Попередження безпеки гаманця​

Поля транзакції​

Поля очікування​

Доказовий звіт​

Тарифікація і помилки​