API мониторинга адресов: как он работает
Что делает API мониторинга криптоадресов, как вебхуки доставляют события депозитов и выводов, как обрабатывать подтверждения, повторы и безопасность.
Проверил(а) Maurice Sobiera

API мониторинга адресов следит за блокчейн-адресами и сообщает вашему приложению, когда что-то происходит: приходит депозит, средства уходят, токен перемещается или транзакция подтверждается. Вы регистрируете адрес и URL для обратного вызова. Сервис отправляет вебхук с деталями транзакции, поэтому узлы опрашивать и логи декодировать самостоятельно не нужно.
«Мониторинг адресов» означает две разные задачи. Первая — операционная: знать, когда деньги поступают на адрес, которым управляет ваше приложение, или уходят с него, чтобы зачислить клиенту или выдать заказ. Вторая — комплаенс: анализ поведения адресов во времени, чтобы выявить рискованную активность. Эта статья посвящена первой задаче, которая нужна большинству продуктовых команд, и показывает, где начинается вторая.
TL;DR
- API мониторинга адресов отслеживает выбранные блокчейн-адреса и передаёт события вашему серверу вебхуком. Поэтому ноды запускать и опрашивать их не нужно.
- События должны приходить декодированными: отправитель, получатель, токен, сумма и статус, а не сырые hex-логи.
- Проверяйте подпись каждого вебхука, устраняйте дубликаты по ID транзакции и зачисляйте средства только после выбранного уровня подтверждения.
- Вебхуки Chaingateway не повторяются автоматически. Сверяйте данные с API, чтобы поймать пропущенные события.
- Операционный мониторинг (платежи) отличается от комплаенс-мониторинга (рисковые паттерны во времени). Многим командам нужны оба, из разных инструментов.
- Chaingateway предлагает кошельки, переводы, декодированные данные транзакций и подписанные вебхуки для Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain и Arbitrum. Solana поддерживается, но вебхуков у неё нет.
Содержание
- Что на самом деле делает API мониторинга адресов
- Почему не запустить собственные ноды и не опрашивать их?
- Как работает мониторинг адресов на вебхуках
- Какие сети и типы адресов нужно поддерживать?
- Подтверждения, задержки и реорги: когда платёж настоящий?
- Повторные попытки и дубликаты уведомлений
- Безопасность, аутентификация и лимиты запросов
- На что смотреть при выборе API мониторинга адресов
- Строить мониторинг самому или использовать API?
- Проверьте на своих адресах
- Минимальный чек-лист внедрения
- FAQ
- Источники
Что на самом деле делает API мониторинга адресов
Блокчейн — публичный реестр, но он не звонит, когда что-то происходит. Протокол не отправит вашему бэкенду сообщение о том, что адрес 0xABC... получил 250 USDT. Кто-то должен читать новые блоки, фильтровать их по нужным адресам, декодировать результат во что-то осмысленное и уведомлять вас. API мониторинга адресов — и есть этот «кто-то», предлагаемый как сервис.
На практике API делает пять вещей:
- Регистрирует адреса. Вы добавляете адреса для наблюдения, обычно те, что сгенерированы для клиентов, счетов или внутренних кошельков.
- Читает цепочку. Провайдер запускает ноды или индексаторы для каждой сети и сканирует каждый новый блок.
- Сопоставляет активность. Он находит переводы нативной монеты и токенов, которые затрагивают ваши адреса.
- Декодирует данные. Сырые транзакции и логи событий превращаются в читаемые поля: направление, символ токена, сумма с правильными decimals, комиссия, блок, статус.
- Доставляет события. Он отправляет их на ваш эндпоинт, обычно HTTPS POST-вебхуком, и позволяет запросить те же данные по требованию.
Что именно обнаруживается, зависит от сети. В Bitcoin — выходы, оплаченные на адрес. В Ethereum и других EVM-сетях — нативные переводы и события токенов, например логи Transfer ERC-20. В Tron — TRX и токены TRC-20. Наша страница API адресов TRC20 показывает, как генерация и мониторинг адресов сочетаются в этой сети.
Операционный мониторинг и комплаенс-мониторинг
Этот термин встречается и в мире комплаенса, и две вещи не стоит путать. Провайдеры для комплаенса описывают мониторинг транзакций как непрерывный анализ активности блокчейна во времени. Они ищут паттерны вроде структурирования, многоступенчатого дробления, необычной скорости движения средств, использования миксеров, обхода санкций и активности спящих кошельков. Риск виден в поведении по множеству транзакций, а тревоги расследуют люди.
API операционного мониторинга отвечает на более простой вопрос: «Пришёл ли платёж, которого я жду, и финален ли он?» Если вы работаете в регулируемом бизнесе, вам, скорее всего, нужны оба уровня. Операционный уровень питает ваш учёт и клиентский опыт. Комплаенс-уровень питает команду рисков. Когда тревогу нужно разобрать глубже, например проследить средства через несколько переходов, эта работа относится к специалистам, а не к вебхуку платежей.

Почему не запустить собственные ноды и не опрашивать их?
Это справедливый вопрос, и некоторым командам имеет смысл сделать именно так. Вот что вы берёте на себя:
- Эксплуатация нод. Каждой цепочке нужна своя нода или размещённый эндпоинт, с обновлениями, ростом хранилища и аптаймом. Каждая дополнительная сеть означает ещё одну настройку.
- Логика, специфичная для цепочки. Модель UTXO в Bitcoin, логи в Ethereum, модель ресурсов в Tron и модель аккаунтов в Solana требуют собственного кода разбора.
- Декодирование. Суммы токенов приходят целыми числами, которым нужны правильные decimals. События контрактов требуют ABI. Внутренние переводы и пакетные транзакции легко пропустить.
- Обработка реорганизаций. Недавние блоки могут быть заменены. Ваш сканер должен это заметить и исправиться.
- Доставка. Когда событие обнаружено, всё равно нужны очередь, повторы и схема подписи, чтобы безопасно доставить его вашим сервисам.
API мониторинга сворачивает большую часть этого в одну интеграцию. Цена — зависимость от провайдера, поэтому оценивайте его по надёжности, качеству данных и тому, насколько аккуратно он передаёт события. Более широкий взгляд на альтернативы — в нашем сравнении шести типов блокчейн-API и когда какой выбирать.
Как работает мониторинг адресов на вебхуках
Типичный поток состоит из четырёх шагов. Он одинаков, строите вы его сами или покупаете.
1. Создайте или зарегистрируйте адрес
Для платежей самый чистый шаблон — один адрес на клиента, счёт или заказ. Когда платёж приходит на уникальный адрес, вы знаете, кто заплатил, и не нужно запрашивать memo или референс. С Chaingateway можно создавать кошельки через API и сразу использовать полученные адреса. Если клиенты указывают собственные адреса для выводов, сначала проверьте их. Наш бесплатный валидатор криптоадресов охватывает форматы Tron, Ethereum и BSC и пригодится как справочник при написании собственных проверок.
2. Подпишитесь на события
Вы сообщаете API, какие адреса и типы событий важны и куда их отправлять: на ваш HTTPS-эндпоинт. Подписки могут быть узкими, например один адрес и один токен, или широкими, как все адреса вашего аккаунта. Подробности модели — на странице вебхуков блокчейна и уведомлений о событиях.
3. Получите декодированную полезную нагрузку
Полезная нагрузка полезна тогда, когда без дополнительных запросов сообщает отправителя, получателя, актив, сумму, блок и хеш транзакции. Вебхук Chaingateway для перевода TRC-20 выглядит так (руководство по вебхукам):
{ "id": "9d18457f-c71c-4be4-ae7c-ce04e48359ed", "webhook_id": "9ced86a9-b8d9-4bc2-bbd8-5ffe5b456bc8", "from": "TTd9qHyjqiUkfTxe3gotbuTMpjU8LEbpkN", "to": "DScWVXehzWdV2YS8fA2ryNsiHpKiLgAxM", "blocknumber": "65542464", "datetime": "2024-09-25 14:48:27", "tokenid": null, "type": "TRC20", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "txid": "18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988", "amount": 108935}id идентифицирует уведомление, а txid — транзакцию. В этом разница между декодированными данными и сырыми данными цепочки. С сырыми данными вы пишете парсер, с декодированными вы читаете поле. В полезной нагрузке нет счётчика подтверждений, поэтому момент, когда транзакция считается финальной, определяет ваш собственный код.
4. Подтвердите получение, проверьте и действуйте
Ваш сервер проверяет подпись, сохраняет событие, быстро возвращает 2xx и асинхронно выполняет бизнес-логику. Всё дальнейшее, например зачисление на счёт или отправка заказа, зависит от правил подтверждений, которые вы задали.

Какие сети и типы адресов нужно поддерживать?
Прежде чем выбирать, перечислите, с чем ваш продукт будет работать в ближайший год, а не только сегодня. Оформление оплаты, которое начинается с USDT в одной сети, через несколько месяцев часто просят добавить и другую.
Проверьте покрытие:
- Нативные монеты и токены. Bitcoin, ETH, TRX, SOL, активы сети Polygon (MATIC) и BNB Chain, а также стандарты токенов, такие как ERC-20, BEP-20 и TRC-20.
- NFT. Если вы выпускаете или принимаете коллекционные предметы или билеты, нужны и события переводов в стиле ERC-721.
- Форматы адресов. У Bitcoin несколько форматов. EVM-сети используют один формат в разных сетях, что может вызвать ошибки, когда клиент отправляет в неверной сети. Ваше приложение должно указывать ожидаемую сеть рядом с каждым адресом депозита.
- Исходящая активность. Многие инструменты фиксируют только депозиты. Если вы отправляете выплаты, вам нужен тот же декодированный вид исходящих транзакций и их статусов.
Chaingateway покрывает Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain и Arbitrum через единый блокчейн-API, включая основные стандарты токенов и переводы NFT. Вебхуки есть для всех сетей, кроме Solana. Интеграции с Solana нужно опрашивать балансы или транзакции своих адресов.
Подтверждения, задержки и реорги: когда платёж настоящий?
Первое уведомление — не последнее слово. Транзакцию могут увидеть в мемпуле, включить в блок и позже довести до уровня финальности, который вы считаете безопасным. Цепочки сильно различаются. Времена блоков, соглашения о подтверждениях и модели финальности в Bitcoin, Ethereum, Tron и Solana не совпадают. Поэтому пороги стоит задавать отдельно для каждой сети и для каждой суммы.
| Сеть | Что говорит документация | Источник |
|---|---|---|
| Bitcoin | Конкурирующие блоки могут появиться на одной высоте, а узлы отбрасывают устаревшие блоки более короткой ветки. Фиксированной точки финальности нет, поэтому глубину подтверждения выбираете вы. | Руководство разработчика Bitcoin |
| Ethereum | Блок финализируется примерно за 15 минут. | ethereum.org |
| Tron | Блок становится необратимым после подтверждения супер-представителями, примерно за 19 блоков. | TRON developer hub |
Практическая политика выглядит так:
| Этап | Что это значит | Что должно делать приложение |
|---|---|---|
| Обнаружен | Транзакция видна, но ещё не в блоке | Показать «платёж ожидается»; товар не выдавать |
| Включён | Транзакция в блоке, подтверждений мало | Зачислить ожидающий баланс для небольших сумм, если позволяет риск |
| Подтверждён | Достигнута выбранная глубина подтверждения | Зачислить на счёт, выдать заказ |
| Неуспешен или сброшен | Транзакция заменена, откачена или так и не была добыта | Откатить ожидающее состояние и сообщить клиенту |
Два правила помогают избежать проблем. Во-первых, масштабируйте требование подтверждений по стоимости риска: небольшой платёж за подписку может выдержать более низкий порог, чем крупный вывод. Во-вторых, делайте машину состояний явной в базе данных. Состояния «ожидает», «подтверждён» и «неуспешен» должны храниться, а не выводиться.
Также ожидайте, что события могут прийти с задержкой или не по порядку. Уведомление о подтверждении может дойти раньше, чем медленный обработчик закончит обработку уведомления об обнаружении. Источник истины — хеш транзакции и её статус, а не порядок поступления.
Повторные попытки и дубликаты уведомлений
Chaingateway не повторяет вебхуки автоматически. Если ваш сервер не отвечает вовремя или возвращает ошибку, уведомление записывается как неудачное. Неудачные уведомления выводятся по каждой сети, например GET /api/v2/tron/webhooks/notifications/failed, и вы отправляете их повторно через POST /api/v2/tron/webhooks/notifications/{id}/retry. Пока вы этого не сделаете, система не знает о событии.
Дубликаты всё равно возможны, например когда вы повторно отправляете уведомление, которое ваш сервер уже обработал. Проектируйте на оба случая с первого дня. Другие провайдеры могут повторять доставку сами, поэтому тот же дизайн обработчика работает с разными провайдерами.
- Делайте обработчики идемпотентными. Сохраняйте уникальный ключ на каждое событие, например хеш транзакции плюс индекс лога или ID доставки, с уникальным ограничением в базе. Если ключ уже есть, возвращайте успех и ничего не делайте.
- Отвечайте быстро. Запишите сырое событие в очередь или таблицу, верните 2xx, затем обрабатывайте. Медленные обработчики вызывают таймауты, а каждый таймаут становится неудачным уведомлением.
- Сверяйте данные. Вебхуки могут потеряться во время вашего простоя. Запускайте периодическое задание, которое получает неудачные и недавние уведомления (
GET /api/v2/<chain>/webhooks/notifications) и сравнивает их с вашими записями. Так потерянное событие превращается из инцидента в отложенное исправление. - Логируйте всё. Храните сырую полезную нагрузку, заголовок подписи и результат обработки. Когда клиент скажет, что заплатил, доказательства должны находиться за минуту, а не за час.
- Оповещайте о тишине. Если адрес, который обычно получает трафик, необычно долго не даёт событий, проверьте конвейер.
Безопасность, аутентификация и лимиты запросов
Эндпоинт, который зачисляет деньги по запросу, — цель. Относитесь к нему соответственно.
Проверяйте каждый вебхук
Любой, кто найдёт ваш URL, может отправить поддельное сообщение «платёж получен», поэтому требуйте подпись. Как только вы задали личный секрет в профиле, Chaingateway добавляет заголовок X-Signature к каждому вебхуку. Заголовок — HMAC-SHA256 от ID транзакции в кодировке Base64, ключом служит ваш личный секрет. Сервер пересчитывает его и отклоняет всё, что не совпадает (руководство по подписи). Сравнивайте значения функцией с постоянным временем, например hmac.compare_digest в Python. Сам HMAC определён в RFC 2104.
Защищайте API-ключи
Храните ключи в менеджере секретов или переменных окружения, никогда в клиентском коде или репозиториях. Используйте отдельные ключи для каждой среды и меняйте их по расписанию и после любой смены сотрудников. Больше таких привычек собрано в нашей статье шесть советов по безопасности при использовании блокчейн-API.
Укрепите эндпоинт
- Работайте только по HTTPS.
- Используйте трудно угадываемый путь. Там, где провайдер публикует диапазоны исходных IP, разрешайте только их.
- Отклоняйте слишком большие тела запросов и неожиданные типы содержимого.
- Никогда не доверяйте суммам и адресам из вебхука, которые вы не сопоставили со своими записями. Адрес должен быть выданным вами, а сумма должна соответствовать заказу.
Закладывайте лимиты запросов
Когда вы запрашиваете данные для сверки или пакетные проверки адресов, вы упрётесь в лимиты запросов у любого провайдера. Кешируйте то, что не меняется, объединяйте запросы там, где это позволяет API. При ответах о троттлинге применяйте экспоненциальную паузу и распределяйте плановые задания, а не запускайте их все в начале часа. Узнайте лимиты своего тарифа до запуска, а не во время первого всплеска трафика.
На что смотреть при выборе API мониторинга адресов
Используйте этот чек-лист при сравнении провайдеров или при решении, строить ли самому.
| Критерий | Почему это важно | Какой вопрос задать |
|---|---|---|
| Покрытие сетей | Избавляет от второй интеграции при расширении | Есть ли в одном API все сети и стандарты токенов, которые мне нужны? |
| Декодированные данные | Сокращает код парсинга и ошибки | Содержат ли события токен, сумму, направление и статус? |
| Гарантии доставки | Определяют объём работы по идемпотентности и сверке | Повторяются ли неудачные доставки автоматически или по запросу, и есть ли ID уведомления? |
| Подписи | Предотвращают поддельные платежи | Подписан ли каждый вебхук и как его проверить? |
| Помощь с газом и комиссиями | Исходящие переводы падают без верной комиссии | Оценивает ли API газ и комиссии автоматически? |
| Инструменты для кошельков | Экономят на склейке нескольких сервисов | Можно ли создавать кошельки и отправлять переводы из одного API? |
| Модель ценообразования | Предсказуемость при масштабировании | Привязана ли цена к тарифным уровням, которые можно спрогнозировать? |
Полезно также прямо ответить себе: нужен ли вам продукт только для мониторинга или полный цикл — создать кошелёк, принять, отправить и сверить? Многие платёжные проекты начинают только с мониторинга, а потом хотят остальное. Наш обзор сценариев использования блокчейн-API показывает, как эти части обычно сочетаются. Статья об электронной коммерции разбирает пример оформления оплаты.
Строить мониторинг самому или использовать API?
Сканирование цепочки своими силами работает в первой версии. Проблемы появляются позже. Реорг зачисляет платёж, который затем исчезает. Токен с необычными decimals показывает неверную сумму. Нода отстаёт в загруженный час. А поддержка ищет клиента, который говорит, что заплатил.
С Chaingateway вы создаёте кошелёк, создаёте вебхук для его адреса и получаете декодированные подписанные события. Формат запросов одинаков в Ethereum, Bitcoin, Tron, Polygon, BNB Smart Chain и Arbitrum, поэтому добавление сети — это изменение конфигурации. Ноду запускать не нужно.
Три привычки важнее выбора провайдера. Заранее определите политику подтверждений. Напишите идемпотентные обработчики до первого живого платежа. Сверяйтесь по расписанию. API мониторинга должен делать их лёгкими, а не заменять необходимость в них.
Проверьте на своих адресах
Если вы строите платежи, депозиты или функции кошелька, можно посмотреть, как мониторинг встраивается в полную интеграцию с Chaingateway. Вебхуки, создание кошельков, переводы токенов и NFT, а также декодированные данные транзакций приходят из одного REST API. Тарифы выстроены по объёму использования и функциям: Plus — 49 € в месяц (или 490 € в год), Pro — 99 € в месяц (990 € в год), Premium — 249 € в месяц (2 490 € в год), Enterprise — 499 € в месяц (4 990 € в год). Начать можно с пробного периода. Актуальные детали тарифов — на странице тарифов. Чтобы увидеть, как события доходят до вашего приложения, почитайте о вебхуках Chaingateway.
Минимальный чек-лист внедрения
Перед первым живым платежом пройдите этот список.
- Создайте по одному адресу на счёт или клиента и показывайте рядом с ним ожидаемую сеть.
- Подпишите эти адреса на входящие и исходящие события.
- Откройте HTTPS-эндпоинт, который проверяет заголовок
X-Signature. - Сохраняйте каждое событие с уникальным ключом и игнорируйте повторы.
- Переводите платежи по сохранённым состояниям: ожидает, подтверждён, неуспешен.
- Задайте пороги подтверждения отдельно для каждой сети и для каждой суммы.
- Запланируйте задание сверки с историей транзакций API.
- Оповещайте о неудачных доставках, долгой тишине и ошибках подписи.
- Протестируйте небольшими реальными суммами в каждой поддерживаемой сети и с каждым токеном, включая депозит в неверной сети. Так вы заранее знаете, что отвечать в поддержке.
Источники
- Что такое мониторинг транзакций в криптовалюте? | Elliptic
- RFC 2104: HMAC, хеширование с ключом для аутентификации сообщений
- OpenAPI-определение Chaingateway
Рекомендуем
Часто задаваемые вопросы
Это сервис, который наблюдает за блокчейн-адресами и сообщает вашему приложению об активности на них, обычно через вебхуки и эндпоинт запросов. Вы получаете декодированные события, например входящий перевод токена или подтверждённый вывод, без собственных нод.
Нет. Операционный мониторинг адресов сообщает приложению, что платёж пришёл или ушёл. Комплаенс-мониторинг транзакций анализирует поведение во времени, чтобы отметить рискованные паттерны, а тревоги расследуют люди. Регулируемые компании часто используют оба.
Это зависит от сети и стоимости риска, поэтому единого числа нет. Задайте порог для каждой цепочки, повышайте его для крупных сумм и храните ожидание и подтверждение как отдельные состояния в базе данных.
Дайте каждому событию уникальный ключ, например хеш транзакции с индексом лога или ID доставки, и закрепите его уникальным ограничением. Если обработчик видит ключ, который уже сохранён, он возвращает успех и больше ничего не делает.
Да, если API мультичейновый. Chaingateway покрывает Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain и Arbitrum через один REST API. Вебхуки есть для всех, кроме Solana.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.