POST /apiv2/aml
Замінено на POST /apiv2/screening
POST /apiv2/screening — це контракт версії 2: єдина структура відповіді для кожного провайдера та будь-якого стану замовлення, десяткові числа у вигляді рядків замість чисел JSON, частки в єдиній шкалі та єдиний формат помилок. Цей ендпоінт продовжує працювати і не буде відключений без попередження.
Надіслати адресу на AML-перевірку (протидія відмиванню коштів). Повертає оцінку ризику, рівень ризику та детальний аналіз зв'язків.
Усі часові мітки у відповіді наведені за UTC. Формат рядка залишається незмінним — "2026-09-09 23:01:44", без суфікса часового поясу.
URL кінцевої точки
POST https://netts.io/apiv2/amlЗаголовки запиту
| Заголовок | Обов'язковий | Опис |
|---|---|---|
| Content-Type | Так | application/json |
| X-API-KEY | Так | Ваш API-ключ із панелі керування Netts |
Тіло запиту
{
"address": "YOUR_ADDRESS_HERE",
"network": "trx",
"provider": "elliptic",
"wait": true
}Параметри запиту
| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
| address | string | Так | Блокчейн-адреса для перевірки (10-100 символів) |
| network | string | Так | Ідентифікатор блокчейн-мережі (див. Підтримувані мережі нижче) |
| provider | string | Ні | AML-провайдер: elliptic (за замовчуванням) |
| wait | boolean | Ні | Якщо true, очікувати на результат синхронно (до 15 секунд). Якщо false або пропущено, відповідь повертається негайно зі статусом pending та client_order_id — використовуйте його для опитування результату через GET /apiv2/aml/{order_id} |
| response_format | string | Ні | Рівень деталізації відповіді: rate (тільки оцінка), full (за замовчуванням, повні дані) |
| report_language | string | Ні | Мова звіту: en (за замовчуванням) |
Провайдери
| Провайдер | Діапазон оцінки | Опис |
|---|---|---|
elliptic | 0 — 10 | Оцінка ризику Elliptic. 0 = ризик відсутній, 10 = максимальний ризик. null = тригери не виявлені |
Приклади
cURL (синхронний)
curl -X POST https://netts.io/apiv2/aml \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key" \
-d '{
"address": "YOUR_ADDRESS_HERE",
"network": "trx",
"provider": "elliptic",
"wait": true
}'cURL (асинхронний)
curl -X POST https://netts.io/apiv2/aml \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key" \
-d '{
"address": "YOUR_ADDRESS_HERE",
"network": "trx",
"provider": "elliptic"
}'Python
import requests
url = "https://netts.io/apiv2/aml"
headers = {
"Content-Type": "application/json",
"X-API-KEY": "your_api_key",
}
payload = {
"address": "YOUR_ADDRESS_HERE",
"network": "trx",
"provider": "elliptic",
"wait": True
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()
if response.status_code == 200:
result = data.get("data", {})
print(f"Order ID: {result.get('client_order_id')}")
print(f"Status: {result.get('status')}")
print(f"Risk Score: {result.get('risk_score')}")
print(f"Risk Level: {result.get('risk_level')}")
print(f"Sanctioned: {result.get('is_sanctioned')}")
else:
print(f"Error: {data}")Відповідь
Успіх — Очікує на обробку (200 OK)
Коли параметр wait не задано або перевірка ще триває:
{
"success": true,
"data": {
"client_order_id": "A4C666ABE24BD4A",
"status": "pending",
"address": "T...example...",
"provider": "elliptic",
"price_usdt": 0.98,
"price_trx": 4.136286,
"currency": "TRX",
"message": "AML check order accepted. Use GET /apiv2/aml/A4C666ABE24BD4A to check status."
},
"timestamp": "2026-03-10 09:56:31"
}Успіх — Elliptic завершено (200 OK)
Повна відповідь Elliptic з усіма структурами даних:
{
"success": true,
"data": {
"client_order_id": "A019540900E55CA",
"status": "completed",
"address": "T...example...",
"provider": "elliptic",
"report_language": "en",
"risk_score": 0.802904,
"risk_level": "low",
"is_sanctioned": true,
"created_at": "2026-03-10 15:56:28",
"completed_at": "2026-03-10 15:56:28",
"result": {
"risk_score": 0.802904473154148,
"risk_score_detail": {
"source": 0.233206,
"destination": 0.802904
},
"contributions": {
"source": [
{
"entities": [
{
"name": "Capitalist",
"is_vasp": true,
"actor_id": 53979,
"category": "Payment Services Provider",
"entity_id": "b73a9c87-...",
"category_id": "54f55bfe-...",
"is_primary_entity": true
}
],
"indirect_value": { "usd": 40194.03 },
"contribution_value": { "usd": 40194.03 },
"counterparty_value": { "usd": 0 },
"min_number_of_hops": 2,
"indirect_percentage": 31.57,
"is_screened_address": false,
"contribution_percentage": 31.57,
"counterparty_percentage": 0
},
{
"entities": [
{
"name": "KuCoin",
"is_vasp": true,
"actor_id": 11620,
"category": "Exchange",
"entity_id": "e54292da-...",
"category_id": "0a52f7a2-...",
"is_primary_entity": true
}
],
"indirect_value": { "usd": 28436.45 },
"contribution_value": { "usd": 29434.17 },
"counterparty_value": { "usd": 997.72 },
"min_number_of_hops": 1,
"indirect_percentage": 22.34,
"is_screened_address": false,
"contribution_percentage": 23.12,
"counterparty_percentage": 0.78
}
],
"destination": [
{
"entities": [
{
"name": "Bybit",
"is_vasp": true,
"actor_id": 23354,
"category": "Exchange",
"entity_id": "bddde8b7-...",
"category_id": "0a52f7a2-...",
"is_primary_entity": true
}
],
"indirect_value": { "usd": 26333.43 },
"contribution_value": { "usd": 27458.30 },
"counterparty_value": { "usd": 1124.86 },
"min_number_of_hops": 1,
"indirect_percentage": 20.69,
"is_screened_address": false,
"contribution_percentage": 21.57,
"counterparty_percentage": 0.88
}
]
},
"cluster_entities": [
{
"name": "Unknown",
"is_vasp": null,
"actor_id": -4,
"category": "Unknown",
"entity_id": "00000000-...",
"category_id": "00000000-...",
"is_primary_entity": true,
"is_after_sanction_date": false
}
],
"evaluation_detail": {
"source": [
{
"rule_id": "6c2dcb03-...",
"rule_name": "Obfuscating & Misc.",
"rule_type": "exposure",
"risk_score": 0.2332,
"matched_elements": [
{
"category": "Coin Swap Service",
"category_id": "ff85b715-...",
"contributions": [
{
"entity": "FixedFloat",
"risk_triggers": {
"category": "Coin Swap Service",
"category_id": "ff85b715-..."
},
"indirect_value": { "usd": 2891.09, "native": 0, "native_major": 0 },
"contribution_value": { "usd": 2968.66, "native": 0, "native_major": 0 },
"counterparty_value": { "usd": 77.58, "native": 0, "native_major": 0 },
"min_number_of_hops": 1,
"indirect_percentage": 2.27,
"is_screened_address": false,
"contribution_percentage": 2.33,
"counterparty_percentage": 0.06
}
],
"indirect_value": { "usd": 2891.09, "native": 0, "native_major": 0 },
"contribution_value": { "usd": 2968.66, "native": 0, "native_major": 0 },
"counterparty_value": { "usd": 0, "native": 0, "native_major": 0 },
"indirect_percentage": 100,
"contribution_percentage": 2.33,
"counterparty_percentage": 0
}
],
"matched_behaviors": []
},
{
"rule_id": "0a2b68fd-...",
"rule_name": "Illicit Activity",
"rule_type": "exposure",
"risk_score": 0.0026,
"matched_elements": [
{
"category": "Token Blacklisting",
"category_id": "94b50de8-...",
"contributions": [
{
"entity": "Tether USD",
"risk_triggers": {
"category": "Token Blacklisting",
"category_id": "94b50de8-..."
},
"contribution_value": { "usd": 1022.45, "native": 0, "native_major": 0 },
"min_number_of_hops": 3,
"contribution_percentage": 0.08
}
]
}
],
"matched_behaviors": []
},
{
"rule_id": "df59fab5-...",
"rule_name": "Sanctions",
"rule_type": "exposure",
"risk_score": 0.0024,
"matched_elements": [
{
"category": "Sanctioned Entity",
"category_id": "c1648b7a-...",
"contributions": [
{
"entity": "Garantex",
"risk_triggers": {
"category": "Sanctioned Entity",
"category_id": "c1648b7a-..."
},
"contribution_value": { "usd": 863.21, "native": 0, "native_major": 0 },
"min_number_of_hops": 3,
"contribution_percentage": 0.07
}
]
}
],
"matched_behaviors": []
}
],
"destination": []
},
"detected_behaviors": []
},
"sanctions": {
"self": false,
"self_entities": null,
"exposure": {
"share": 8.029045,
"proximity": "mixed",
"hops": 1,
"entity": "Garantex Europe OU - OFAC SDN - 5 Apr 2022",
"category": "OFAC Sanctioned Entity",
"direction": "destination",
"rule_name": "Sanctioned, TF & CSAM"
},
"items": [
{
"entity": "Garantex Europe OU - OFAC SDN - 5 Apr 2022",
"category": "OFAC Sanctioned Entity",
"share": 8.02904473154148,
"counterparty_share": 2.472410320321629,
"indirect_share": 5.556634411219852,
"hops": 1,
"proximity": "mixed",
"is_sanctioned": true,
"trigger": "sanctions_list",
"value_usd": 7494.407584232807,
"direction": "destination",
"rule_name": "Sanctioned, TF & CSAM"
}
]
}
},
"timestamp": "2026-03-10 15:56:28"
}Поля відповіді
| Поле | Тип | Опис |
|---|---|---|
| data.client_order_id | string | Унікальний ідентифікатор замовлення для опитування статусу |
| data.status | string | pending, processing, completed, failed, skipped |
| data.risk_score | number | null | Оцінка ризику. Elliptic: 0-10. null = тригери відсутні |
| data.risk_level | string | null | none, low, medium, high або severe. Elliptic повертає low, medium, high; BitOK додає none та severe. null, якщо провайдер взагалі не виявив тригерів |
| data.is_sanctioned | boolean | true, якщо виявлено зв'язок із підсанкційними суб'єктами. Не змінювалося з моменту запуску ендпоінта: не розрізняє безпосередньо підсанкційну адресу від адреси, що просто пов'язана з нею — для цього див. data.sanctions |
| data.sanctions | object | null | Деталізація висновку щодо санкцій: чи внесена сама адреса до списку, наскільки близьким є зв'язок і який його обсяг. Див. Санкції |
| data.result | object | Повна відповідь провайдера (якщо вказано response_format=full) |
Санкції
is_sanctioned є єдиним логічним значенням, і воно повертає true у двох абсолютно різних ситуаціях: перевірена адреса сама перебуває в санкційному списку, або ж перевірена адреса одного разу отримала частку відсотка через двох посередників від когось, хто там є. Прапорець зберігає своє початкове значення для зворотної сумісності; data.sanctions дозволяє розрізнити ці два випадки.
| Поле | Тип | Опис |
|---|---|---|
| sanctions.self | boolean | true, якщо сама перевірена адреса є підсанкційним суб'єктом |
| sanctions.self_entities | array | null | Назви власних підсанкційних суб'єктів, якщо self має значення true |
| sanctions.exposure | object | null | Єдиний найбільший санкційний зв'язок — те, що слід показувати у зведенні |
| sanctions.exposure.share | number | Частка залучених коштів у відсотках (8.03 означає 8.03%) |
| sanctions.exposure.proximity | string | screened_address, counterparty, indirect або mixed |
| sanctions.exposure.hops | number | null | Мінімальна кількість транзакційних переходів (hops) до підсанкційного суб'єкта |
| sanctions.exposure.entity | string | null | Назва підсанкційного суб'єкта, включно зі списком та датою |
| sanctions.exposure.direction | string | null | source для вхідних коштів, destination для вихідних |
| sanctions.items | array | Кожен внесок санкційного зв'язку, починаючи з найбільшої частки; ті самі поля, що й в exposure, плюс counterparty_share, indirect_share, value_usd та trigger |
| sanctions.related | array | null | Тільки для BitOK: зв'язок із біржами під санкціями ЄС або Великобританії, відокремлений від самого санкційного списку |
Proximity відображає стовпчик Closest Proximity у звіті Elliptic:
| Значення | Значення (пояснення) |
|---|---|
screened_address | Сама перевірена адреса є тригером, а не контрагентом |
counterparty | Прямий контрагент перевіреної адреси |
indirect | Зв'язок через посередників — див. hops |
mixed | Як прямі, так і непрямі потоки до одного й того ж суб'єкта |
Внесок вважається санкційним зв'язком лише тоді, коли провайдер позначає його як такий — risk_triggers.is_sanctioned для Elliptic, категорія sanctions для BitOK. Правило Elliptic з назвою Sanctioned, TF & CSAM також спрацьовує на тригери країн та категорій, тому сама лише назва правила не є висновком про санкції.
Об'єкт result Elliptic
| Поле | Тип | Опис |
|---|---|---|
| risk_score | number | Точна оцінка ризику (0-10) |
| risk_score_detail | object | Розподіл: оцінки для source та destination |
| contributions | object | Масиви source та destination учасників руху коштів |
| contributions[].entities | array | Відомі суб'єкти, пов'язані з внеском |
| contributions[].entities[].name | string | Назва суб'єкта (наприклад, "Binance", "KuCoin") |
| contributions[].entities[].category | string | Тип суб'єкта (наприклад, "Exchange", "Payment Services Provider") |
| contributions[].entities[].is_vasp | boolean | null | Чи є суб'єкт постачальником послуг віртуальних активів (VASP) |
| contributions[].contribution_value.usd | number | Загальний обсяг внеску в USD |
| contributions[].contribution_percentage | number | Відсоток загального обсягу коштів від цього суб'єкта |
| contributions[].indirect_value.usd | number | Обсяг в USD, отриманий опосередковано (через посередників) |
| contributions[].indirect_percentage | number | Відсоток коштів, отриманих опосередковано |
| contributions[].counterparty_value.usd | number | Обсяг в USD як прямого контрагента |
| contributions[].counterparty_percentage | number | Відсоток як прямого контрагента |
| contributions[].min_number_of_hops | number | Мінімальна кількість переходів від суб'єкта (0 = напряму) |
| contributions[].is_screened_address | boolean | true, якщо це сама перевірена адреса |
| cluster_entities | array | Відомі суб'єкти, безпосередньо пов'язані з кластером адреси |
| cluster_entities[].name | string | Назва суб'єкта |
| cluster_entities[].category | string | Категорія суб'єкта |
| cluster_entities[].is_vasp | boolean | null | Статус VASP |
| cluster_entities[].is_after_sanction_date | boolean | true, якщо активність відбулася після накладення санкцій на суб'єкта |
| evaluation_detail | object | Масиви source та destination правил ризику, що спрацювали |
| evaluation_detail[].rule_name | string | Назва правила (наприклад, "Sanctions", "Illicit Activity", "Obfuscating & Misc.") |
| evaluation_detail[].rule_type | string | Тип правила (наприклад, "exposure") |
| evaluation_detail[].risk_score | number | Внесок цього правила в оцінку ризику |
| evaluation_detail[].matched_elements | array | Категорії та суб'єкти, які активували правило |
| evaluation_detail[].matched_elements[].category | string | Категорія ризику (наприклад, "Sanctioned Entity", "Gambling", "Token Blacklisting") |
| evaluation_detail[].matched_elements[].contributions | array | Суб'єкти в межах зіставленої категорії |
| evaluation_detail[].matched_elements[].contributions[].entity | string | Назва суб'єкта |
| evaluation_detail[].matched_elements[].contributions[].contribution_percentage | number | Відсоток впливу (зв'язку) |
| evaluation_detail[].matched_elements[].contributions[].min_number_of_hops | number | Кількість транзакційних переходів |
| evaluation_detail[].matched_elements[].contributions[].is_screened_address | boolean | true, коли сама перевірена адреса активувала правило |
| evaluation_detail[].matched_elements[].contributions[].risk_triggers | object | Причина спрацьовування правила: is_sanctioned для санкційного списку, country для юрисдикції, category для типу суб'єкта |
| evaluation_detail[].matched_behaviors | array | Виявлені поведінкові патерни |
| detected_behaviors | array | Глобальні поведінкові патерни, виявлені на адресі |
Рівні ризику
Elliptic (шкала 0-10):
| Діапазон | Рівень | Опис |
|---|---|---|
| 0 — 3 | low | Мінімальний ризик. Значного зв'язку не виявлено |
| 3 — 7 | medium | Помірний ризик. Виявлено деякі ризиковані категорії |
| 7 — 10 | high | Високий ризик. Підсанкційні, незаконні або високого ризику суб'єкти |
| null | - | Тригери ризику не виявлені |
BitOK (шкала 0-1): провайдер сам повертає рівень — none, low, medium, high або severe.
risk_level є єдиним висновком, який використовується всюди: у відповіді API, на панелі керування та в PDF-звіті для однієї й тієї самої перевірки вказується однакове слово.
Відповіді з помилками
Помилка автентифікації (401)
{
"detail": {
"code": -1,
"msg": "API key not provided"
}
}Помилка валідації (400)
{
"success": false,
"error": {
"code": 4001,
"msg": "Invalid or missing address"
}
}{
"success": false,
"error": {
"code": 4002,
"msg": "Invalid provider. Use: elliptic"
}
}Недостатній баланс (402)
{
"success": false,
"error": {
"code": 4020,
"message": "Insufficient balance"
},
"timestamp": "2026-03-10 10:00:00"
}Провайдер недоступний (503)
{
"success": false,
"error": {
"code": 5030,
"message": "Provider elliptic not available"
},
"timestamp": "2026-03-10 10:00:00"
}Довідник кодів помилок
| Код | Опис | HTTP-статус |
|---|---|---|
-1 | Помилка автентифікації | 401 |
4001 | Недійсна або відсутня адреса | 400 |
4002 | Недійсний провайдер | 400 |
4020 | Недостатній баланс | 402 |
5030 | Провайдер недоступний | 503 |
Обмеження частоти запитів
До всіх ендпоінтів AML застосовуються такі ліміти запитів (на одну IP-адресу):
| Період | Ліміт | Опис |
|---|---|---|
| 1 секунда | 2 запити | Не більше 2 запитів на секунду |
| 1 хвилина | 30 запитів | Не більше 30 запитів на хвилину |
Перевищення ліміту запитів (429)
{
"message": "API rate limit exceeded"
}Кешування результатів
Якщо комбінація однакової адреси та провайдера вже перевірялася протягом останніх 60 секунд, кешований результат повертається безкоштовно.
Підтримувані мережі
Параметр network є обов'язковим. Використовуйте тікер із таблиці нижче.
Elliptic — Цілісна перевірка (Holistic)
Перевірка виконується для конкретної адреси в певній мережі. Проте Elliptic відстежує всі активи, пов'язані з цією адресою, включно з токенами, кросчейн-переказами та взаємодіями з відомими суб'єктами в інших мережах.
| Мережа | Тікер | Базовий актив |
|---|---|---|
| Algorand | algo | ALGO |
| Aptos | apt | APT |
| Arbitrum | arb | ETH |
| Avalanche (C-Chain) | avax | AVAX |
| Base | base | ETH |
| Binance Chain | bnb | BNB |
| Binance Smart Chain | bsc | BNB |
| Bitcoin | btc | BTC |
| Bittensor | tao | TAO |
| Cardano | ada | ADA |
| Celo | celo | CELO |
| Cosmos | atom | ATOM |
| Crypto.com | cro | CRO |
| Dogecoin | doge | DOGE |
| dYdX | dydx | DYDX |
| Ethereum | eth | ETH |
| Ethereum Classic | etc | ETC |
| Fantom | ftm | FTM |
| Filecoin | fil | FIL |
| Flare | flr | FLR |
| Gnosis | gnosis | xDai |
| Hedera | hbar | HBAR |
| HyperEVM | hype | HYPE |
| Injective | inj | INJ |
| Internet Computer | icp | ICP |
| Linea | linea | LINEA |
| Litecoin | ltc | LTC |
| MobileCoin | mob | MOB |
| Near | near | NEAR |
| Optimism | op | ETH |
| Polkadot | dot | DOT |
| Polygon | matic | MATIC |
| Ripple | xrp | XRP |
| Sei | sei | SEI |
| Solana | sol | SOL |
| Starknet | strk | STRK |
| Stellar | xlm | XLM |
| Sui | sui | SUI |
| Tezos | xtz | XTZ |
| TON | ton | TON |
| Tron | trx | TRX |
| XDC | xdc | XDC |
| XLayer | okb | OKB |
| Zilliqa | zil | ZIL |
| zkSync | zksync | ETH |
Перевірка окремих активів (Single Asset)
Ці мережі підтримують індивідуальну перевірку адрес/транзакцій:
| Мережа | Тікер | Базовий актив |
|---|---|---|
| Bitcoin Cash | bch | BCH |
| Horizen | zen | ZEN |
| ZCash | zec | ZEC |
Сумісність провайдерів та мереж
При використанні provider: "elliptic" доступні всі мережі з таблиць Holistic та Single Asset (47 мереж). Якщо передано непідтримувану мережу, API повертає код помилки 4001.
Примітки
- Вартість: Elliptic — $0.98 за перевірку. Ціни відображаються в TRX за поточним курсом
- Синхронний таймаут:
wait: trueочікує до 15 секунд. Якщо перевірка триває довше, повертається статусpending - Час обробки: Більшість перевірок завершуються за кілька секунд. Однак обробка деяких запитів (особливо для адрес зі складною історією транзакцій) може тривати до 3 хвилин. У таких випадках використовуйте асинхронний режим (пропустіть
waitабо встановітьwait: false) та опитуйте результат через GET /apiv2/aml/{order_id} - Неактивні адреси: Для адрес без активності в блокчейні повертається статус
skippedбез списання коштів