REST API

REST API · v1

Документация RiskScan API

RiskScan API даёт программный доступ к нашим инструментам: AML-скоринг адресов и транзакций, поиск и жалобы по чёрному списку контрагентов и форензика PDF-чеков. Один HTTPS-эндпоинт, JSON на входе и выходе, аутентификация по ключу.

Все ответы — JSON с полем ok. Успех: { "ok": true, … }. Ошибка: { "ok": false, "error": "…" } с соответствующим HTTP-кодом.

Базовый URL

https://api.riskscan.net

первый запрос

curl "https://api.riskscan.net/health"
# → { "ok": true, "dbAuth": true }

Аутентификация

Все защищённые ручки требуют заголовок X-API-Key. Ключ выдаётся каждому пользователю в Telegram-боте (раздел API) — один живой ключ на аккаунт, с возможностью пересоздания без потери баланса токенов. Запросы без ключа получают 401. Если вашему клиенту привычнее Authorization: Bearer <ключ> — он тоже принимается.

заголовок ключа

curl -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/profile/full?value=98765432"

🔑 Храните ключ как секрет. Утёк — пересоздайте его в боте: старый мгновенно перестанет работать.

Токены и тарификация

Платные ручки списывают токены: чем тяжелее операция, тем больше токенов. Каждому аккаунту сразу начисляется 100 тестовых токенов. Токены принадлежат пользователю — пересоздание ключа их не сбрасывает. Кончились токены → любой платный вызов вернёт 402.

Функция	Токенов
/profile/full · проверить контрагента	3
/v1/aml/address	10
/v1/aml/txid	15
/v1/receipts/check	10
/v1/blacklist/report · добавить в ЧС	5

На платном ответе — заголовки списания:

headers

X-Tokens-Cost: 10
X-Tokens-Remaining: 90

Когда токены кончились — 402 с деталями:

402 Payment Required

{
  "ok": false,
  "error": "insufficient_tokens",
  "function_code": "aml_address",
  "required": 10,
  "available": 4
}

Лимиты запросов

Помимо токенов действует анти-флуд по частоте — по умолчанию 60 запросов/мин и 2000/сутки на ключ. Он защищает инфраструктуру и срабатывает до списания токенов: превышение — 429, токены не тратятся. Текущие остатки — в заголовках.

headers

X-RateLimit-Remaining-Minute: 58
X-RateLimit-Remaining-Day: 4972
X-RateLimit-Total-Used: 1284

Ошибки

Единый формат ошибки — JSON с ok:false. При нехватке/недоступности данных AML и проверка чеков работают fail-closed: возврат ошибки, а не выдуманный «чистый» результат, и токены не списываются.

400	bad_request	Некорректный запрос
401	Unauthorized	Нет/неверный ключ
402	insufficient_tokens	Недостаточно токенов
403	forbidden	Ключ/функция запрещены
404	Not found	Функция выключена флагом
429	Rate limit exceeded	Лимит частоты или дневной лимит токенов
503	busy / needs_async	Перегрузка / дедлайн
500	internal_error	Внутренняя ошибка

Сервис

GET/health

Проверка доступности

без ключа

Лёгкий пинг сервиса. Не требует ключа и не тратит токены — используйте для мониторинга аптайма.

Ошибки

500

internal_error

Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  "https://api.riskscan.net/health"

Ответ · 200 OK

{
  "ok": true,
  "dbAuth": true
}

Проверка контрагента

GET/profile/full

Проверить контрагента

🔑 X-API-Key3 ток.ПДза флагом

Основная проверка контрагента: статус, нарушения, статистика и — при наличии — контактные данные. Нужно указать субъект: свободный запрос value ИЛИ ровно один типизированный параметр (uid/card/phone/nick/link). Содержит персональные данные, доступ регулируется политикой сервера.

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

value	string	Свободный запрос (или используйте типизированные uid/card/phone/nick/link).
base	string	Площадка контрагента.bybit · mexc · tg_wallet · all
ads	boolean	Включить объявления контрагента (тяжелее).
currency	string	Валюта для денежных полей.
limit	integer	Размер страницы.
offset	integer	Смещение пагинации.

Ошибки

400	bad_request	Некорректные или отсутствующие параметры. Тело ответа содержит конкретный код ошибки.
401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
402	insufficient_tokens	Недостаточно токенов для вызова. См. заголовок X-Tokens-Remaining и поле required.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/profile/full?value=98765432&base=bybit"

Ответ · 200 OK

{
  "ok": true,
  "query": "98765432",
  "base": "bybit",
  "total": 1,
  "results": [
    {
      "uid": "98765432",
      "base": "bybit",
      "status": "blacklisted",
      "nickname": "fast_otc_deals",
      "complaints": 4,
      "violations": [
        {
          "type": "non_release",
          "reportedAt": "2026-05-30T11:02:00Z"
        }
      ],
      "stats": {
        "totalOrders": 1280,
        "completionRate": 0.91
      }
    }
  ]
}

AML-скоринг

GET/v1/aml/address

AML-скоринг адреса

🔑 X-API-Key10 ток.за флагом

Живая трасса графа транзакций и риск-скор адреса (0–100 %, уровень риска, топ-связи, поток средств). Собственный движок, сети TRC20/BEP20/ETH/TON. Холодная проверка занимает до 30–60 с. Fail-closed: при недоступности данных вернётся 503 + статус insufficient_data, никогда не выдумывается «чисто».

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

networkобяз.	string	Сеть адреса.TRC20 · BEP20 · ETH · TON
addressобяз.	string	Адрес для проверки.

Ошибки

400	bad_request	Некорректные или отсутствующие параметры. Тело ответа содержит конкретный код ошибки.
401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
402	insufficient_tokens	Недостаточно токенов для вызова. См. заголовок X-Tokens-Remaining и поле required.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
503	busy / needs_async	Движок насыщен или превышен синхронный дедлайн. Повторите по Retry-After. Токены не списываются.
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/v1/aml/address?network=TRC20&address=TXk...9pQ"

Ответ · 200 OK

{
  "ok": true,
  "status": "ok",
  "kind": "address",
  "address": "TXk...9pQ",
  "networkCode": "TRC20",
  "scoringVersion": 50,
  "riskLevel": "high",
  "score": 72,
  "scorePercent": "72.0%",
  "decision": "deny",
  "cached": false,
  "degraded": false,
  "coverage": {
    "tier": "ok",
    "hasProviderErrors": false
  },
  "topConnections": [
    {
      "address": "TM...aZ",
      "amount": "12,500 USDT",
      "direction": "in",
      "label": "sanctioned_exchange"
    }
  ],
  "fundFlowSummary": {
    "inflow": "31,200 USDT",
    "outflow": "30,980 USDT",
    "balance": "220 USDT"
  },
  "checkedAt": "2026-06-24T09:15:00Z"
}

GET/v1/aml/txid

AML-скоринг транзакции

🔑 X-API-Key15 ток.за флагом

Резолвит транзакцию по хэшу, определяет основной перевод и скорит риск отправителя. Возвращает те же поля, что и проверка адреса, плюс primaryTransfer.

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

networkобяз.	string	Сеть транзакции.TRC20 · BEP20 · ETH · TON
txidобяз.	string	Хэш транзакции.

Ошибки

400	bad_request	Некорректные или отсутствующие параметры. Тело ответа содержит конкретный код ошибки.
401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
402	insufficient_tokens	Недостаточно токенов для вызова. См. заголовок X-Tokens-Remaining и поле required.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
503	busy / needs_async	Движок насыщен или превышен синхронный дедлайн. Повторите по Retry-After. Токены не списываются.
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/v1/aml/txid?network=BEP20&txid=0xab...7c3d"

Ответ · 200 OK

{
  "ok": true,
  "status": "ok",
  "kind": "transaction",
  "txid": "0xab...7c3d",
  "networkCode": "BEP20",
  "senderAddress": "0x4a2...b9f1",
  "recipientAddress": "0x77c...12ab",
  "riskLevel": "low",
  "score": 6,
  "scorePercent": "6.0%",
  "decision": "allow",
  "degraded": false,
  "coverage": {
    "tier": "full",
    "hasProviderErrors": false
  },
  "primaryTransfer": {
    "from": "0x4a2...b9f1",
    "to": "0x77c...12ab",
    "amount": "500",
    "amountUsd": 500,
    "asset": "USDT"
  },
  "checkedAt": "2026-06-24T09:16:00Z"
}

GET/v1/aml/health

Статус AML-движка

🔑 X-API-Keyза флагом

Версия скоринга, синхронный дедлайн и покрытие по сетям (какие сети считаются синхронно «на лету»).

Ошибки

401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/v1/aml/health"

Ответ · 200 OK

{
  "ok": true,
  "deadlineMs": 60000,
  "scoringVersion": 50,
  "coverage": {
    "TRC20": {
      "sync": true,
      "keyed": true
    },
    "BEP20": {
      "sync": true,
      "keyed": true
    },
    "ETH": {
      "sync": true,
      "keyed": true
    },
    "TON": {
      "sync": true,
      "keyed": true,
      "requiresKeyForSync": true
    }
  }
}

Проверка чеков

POST/v1/receipts/check

Форензика PDF-чека

🔑 X-API-Key10 ток.за флагом

Принимает PDF платёжного чека/выписки и возвращает вердикт подлинности: извлечённые поля, набор форензик-проверок и находки. ПД отдаются только при include_pii=1.

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

include_pii

boolean

Вернуть персональные данные из чека (имена, карты, счёт).

Тело запроса

multipart/form-data — multipart/form-data с полем file — либо application/json с { fileBase64, fileName }. Сырое тело application/pdf не принимается (415).

Ошибки

400	bad_request	Некорректные или отсутствующие параметры. Тело ответа содержит конкретный код ошибки.
401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
402	insufficient_tokens	Недостаточно токенов для вызова. См. заголовок X-Tokens-Remaining и поле required.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
503	busy / needs_async	Движок насыщен или превышен синхронный дедлайн. Повторите по Retry-After. Токены не списываются.
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl -X POST \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf \
  "https://api.riskscan.net/v1/receipts/check"

Ответ · 200 OK

{
  "ok": true,
  "verdict": {
    "hasForgerySignals": true,
    "confidence": "высокий",
    "suspiciousCount": 2,
    "warningCount": 1,
    "definitiveCount": 1
  },
  "receipt": {
    "documentType": "transfer",
    "issuer": "Сбербанк",
    "operation": "Перевод",
    "status": "Выполнено",
    "amount": "45 000,00 ₽",
    "operationId": "1234567890",
    "paymentFingerprint": "a1b2c3"
  },
  "pdf": {
    "origin": "screenshot_to_pdf",
    "pages": 1,
    "hasSignature": false,
    "hasQr": false
  },
  "findings": [
    {
      "level": "high",
      "code": "font_mismatch",
      "message": "Шрифт суммы отличается от шаблона банка."
    }
  ],
  "checks": [
    {
      "code": "producer",
      "ok": false,
      "label": "Производитель PDF"
    }
  ],
  "analysisDegraded": false,
  "file": {
    "sizeBytes": 81234,
    "sha256": "9f2c..."
  }
}

GET/v1/receipts/health

Статус форензик-инструментов

🔑 X-API-Keyза флагом

Доступность бинарей форензики на хосте (qpdf, pdftotext, tesseract, magick и др.) и флаг degraded.

Ошибки

401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  "https://api.riskscan.net/v1/receipts/health"

Ответ · 200 OK

{
  "ok": true,
  "tools": {
    "qpdf": true,
    "pdftotext": true,
    "tesseract": true,
    "magick": true
  },
  "degraded": false
}

Чёрный список

POST/v1/blacklist/report

Отправить жалобу в чёрный список

🔑 X-API-Key5 ток.за флагом

Ставит запись в очередь модерации. Тело — ровно один типизированный идентификатор (или value) + обязательный текст жалобы. Идемпотентно по Idempotency-Key. При отклонении модератором токены возвращаются.

Тело запроса

application/json — JSON с субъектом и текстом жалобы.

Поля

base	string	Площадка контрагента.bybit · mexc · tg_wallet
uid \| card \| phone \| nick \| linkобяз.	string	Ровно один типизированный идентификатор субъекта.
reviewобяз.	string	Текст жалобы (обязателен, проходит модерацию).
idempotency_key	string	Ключ идемпотентности (можно также в заголовке Idempotency-Key).

Ошибки

400	bad_request	Некорректные или отсутствующие параметры. Тело ответа содержит конкретный код ошибки.
401	Unauthorized	Отсутствует или неверный заголовок X-API-Key.
402	insufficient_tokens	Недостаточно токенов для вызова. См. заголовок X-Tokens-Remaining и поле required.
403	forbidden	Ключ отключён, либо функция не разрешена для этого ключа / выключена политикой сервера.
404	Not found	Функция выключена флагом на сервере (ручка невидима до включения оператором).
500	internal_error	Внутренняя ошибка сервера. Запрос не выполнен, токены не списываются.

Запрос · cURL

curl -X POST \
  -H "X-API-Key: $RISKSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base":"bybit","uid":"98765432","review":"Не отпустил средства после оплаты, динамил 3 часа."}' \
  "https://api.riskscan.net/v1/blacklist/report"

Ответ · 200 OK

{
  "ok": true,
  "submission_id": "1042",
  "status": "pending",
  "idempotent": false
}