Перейти к содержимому

Массовые выплаты в криптовалюте через API: архитектура отправки тысяч переводов в USDT

6 нояб. 2026 г. 7 мин чтения Paymos Tech Paymos Tech
Архитектура API для массовых выплат в криптовалюте и пакетных выводов

Кратко

Для массовых выплат через API нужна очередь с ограниченным числом одновременных запросов. Каждый POST /v1/withdrawals создает выплату одному получателю. Сохраните external_order_id вместе с заявкой до первой отправки и используйте тот же идентификатор и данные при повторных запросах. Стандартный лимит 30 запросов в секунду общий для аккаунта и не означает скорость завершения переводов. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production. Комиссия Paymos за вывод — 0 %, сетевая комиссия субсидируется.

Массовые автоматические выплаты в криптовалюте — критически важная часть инфраструктуры современного финтеха. Партнерские сети (CPA), выплачивающие вознаграждения тысячам вебмастеров, гемблинг-платформы с моментальным выводом выигрышей, Web3-протоколы и международные IT-компании с распределенной зарплатной сеткой ежедневно генерируют тысячи исходящих транзакций.

Однако масштабирование криптовалютных выплат кардинально отличается от работы с банковскими шлюзами. Если в банковской системе реестр выплат отправляется одним файлом, то в блокчейне действуют правила строгого распределенного консенсуса, последовательные номера nonce, аукционы газа в мемпуле и полная необратимость транзакций. Любая неотработанная ошибка может привести к повторному списанию средств или полной парализации очереди выплат.

Для построения надежного конвейера массовых выплат требуется специализированная распределенная архитектура.

Почему последовательные выплаты зависают под нагрузкой: проблема Nonce

Типичная ошибка начинающих разработчиков — реализация выплат простым синхронным циклом: бэкенд выбирает 300 заявок из базы данных и по очереди дергает метод отправки транзакции. В боевых условиях такая схема ломается из-за порядкового номера nonce.

В сетях на базе Ethereum (EVM) транзакции одного отправителя выполняются в порядке nonce: $0, 1, 2, \dots$ Если одна из них остается в ожидании, следующие переводы с того же адреса могут ждать за ней. Частота запросов API и число завершенных переводов в блокчейне — разные показатели.

Попытки хаотично поднимать nonce в параллельных потоках приводят к коллизиям и ошибкам узла nonce too low или replacement transaction underpriced. Для стабильной работы под нагрузкой требуется разделение потоков.

Архитектура 1: Паттерн Transactional Outbox для финансовой надежности

Шаблон Transactional Outbox позволяет записать заявку на выплату и изменение внутреннего баланса одной транзакцией базы данных. Вместе с заявкой сохраните external_order_id, чтобы после сбоя воркер повторил исходный запрос с тем же идентификатором.

sequenceDiagram autonumber participant App as Ядро сервиса мерчанта participant DB as База данных (PostgreSQL) participant Worker as Воркер очереди выплат participant Gateway as Шлюз выплат Paymos participant Chain as Сеть Блокчейн App->>DB: BEGIN Transaction App->>DB: Списание баланса пользователя и запись в таблицу outbox App->>DB: COMMIT Transaction Worker->>DB: Выборка заявок (FOR UPDATE SKIP LOCKED) loop Один получатель на запрос, число одновременных запросов ограничено Worker->>Gateway: POST /v1/withdrawals (сохраненный external_order_id) Gateway-->>Worker: HTTP 201 (created) или 200 (существующая выплата) Worker->>DB: Сохранение withdrawal_id и полученного статуса end Gateway->>Chain: Отправка после проверки адреса Gateway->>Worker: Вебхук event_type=withdrawal.completed Worker->>DB: Установка финального статуса 'completed'

Принципы надежного конвейера:

  1. Атомарность списания: Списание баланса пользователя в приложении и создание задачи на выплату выполняются в одной транзакции базы данных.
  2. Ключи идемпотентности (Idempotency Keys): Сохраните уникальный external_order_id до первой отправки и повторяйте запрос с тем же идентификатором и данными. Новый идентификатор нужен только для новой выплаты. Подробнее о защите от дублей читайте в статье об идемпотентности платежных вебхуков.
  3. Асинхронные воркеры: Воркеры выбирают заявки из очереди, например через FOR UPDATE SKIP LOCKED. Ограничьте общее число одновременных запросов и увеличивайте паузу между попытками при ошибках. При HTTP 429 учитывайте заголовок Retry-After.

Архитектура 2: Устранение коллизий Nonce через несколько кошельков-отправителей

В собственном сервисе выплат несколько кошельков позволяют разделить последовательности nonce. Это вариант архитектуры, который сам по себе не задает скорость завершения переводов:

$$\text{Кластер хранилищ} = {V_1, V_2, V_3, \dots, V_m}$$

При такой схеме нужно учитывать состояние каждого отправителя:

  • Отдельно отслеживать последовательность nonce и ожидающие транзакции каждого кошелька.
  • Распределять новые заявки с учетом ожидающих транзакций; дополнительные кошельки не завершают уже задержанный перевод.
  • Проверять баланс и необходимые сетевые ресурсы до отправки.

О принципах безопасной изоляции приватных ключей читайте в материале о безопасности горячих кошельков.

Архитектура 3: Мультичейн-выплаты в сетях TRON, EVM и TON

Платформам часто приходится платить получателям в нескольких сетях: получатели держат средства в разных сетях и на разных биржах.

API выплат сводит различия между сетями к единой схеме:

  • TRON (USDT TRC-20): Поддерживает выплаты USDT. Энергия влияет на стоимость перевода; подробнее — в материале об аренде энергии TRON.
  • EVM-сети (Arbitrum, BSC, Polygon): Поддерживают выплаты USDT и USDC. Base поддерживает только USDC; выбирайте доступное направление для своего актива.
  • TON (USDT): Поддерживает выплаты USDT. Срок перевода зависит от текущих условий сети.

Шлюз нормализует ответы разных сетей в единый формат вебхуков, избавляя мерчанта от поддержки специфичных протокольных клиентов. Всего для выплат доступно 11 сетей (сети NEAR и Sui работают только на прием депозитов).

Предварительный AML-скрининг получателей

Серьезный риск автоматических выплат — случайно перевести средства санкционному лицу, даркнет-маркетплейсу или на адрес с украденными активами. Если горячий кошелек отправит стейблкоины на адрес из санкционного списка OFAC, бизнесу грозят серьезные регуляторные последствия.

  1. Оценка риска адреса: перед маршрутизацией выплаты адрес получателя проверяется по источникам TRM Labs, Binance AML, AMLBot, PureFi и базе провайдера проверки.
  2. Остановка рискованной выплаты: если адрес не проходит проверку, выплата не отправляется. Она переходит в статус failed (вебхук withdrawal.failed), а вся зарезервированная сумма amount + fee возвращается на доступный баланс мерчанта.

Проверка может задержать или остановить выплату: принятый запрос API не гарантирует немедленной отправки в сеть.

Сетевые комиссии: субсидии на выплаты и энергия TRON

При расчете расходов учитывайте комиссию сервиса и сетевые ресурсы:

  1. 0% комиссии Paymos за вывод и субсидированная комиссия сети: Paymos берет 0% комиссии за вывод. Мерчант платит только указанную комиссию сети для выбранного направления, причем каждое направление выплат субсидируется: мерчант платит меньше, чем списывает блокчейн. Если выплата не состоялась или отменена, вся зарезервированная сумма и комиссия возвращаются на доступный баланс.
  2. Энергия TRON и указанная комиссия: Энергия и другие ресурсы сети влияют на стоимость перевода в TRON. Ориентируйтесь на указанную комиссию выбранного направления, а не на фиксированную цену в долларах. Информация о комиссиях доступна на странице цен Paymos.

Интеграция через REST API Paymos

Через Host-to-Host REST API Paymos вы создаете отдельные выплаты из своей очереди и отслеживаете их статус.

1. Отправка выплаты через API

Бэкенд отправляет отдельный POST /v1/withdrawals для каждого получателя. Используйте ключ Payout (rk_) и подпись HMAC-SHA256. Значения заголовков ниже — шаблоны: вычисляйте подпись для точных байтов запроса и текущего времени Unix. По умолчанию адрес получателя должен быть в белом списке выводов.

POST /v1/withdrawals HTTP/1.1
Host: api.paymos.io
Authorization: HMAC-SHA256 rk_live_<key_id>:<base64_signature>
X-Request-Timestamp: <current_unix_seconds>
Content-Type: application/json

{
  "currency": "USDT",
  "network": "TRC20",
  "amount": "25.00",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "external_order_id": "payout_usr_101"
}

Новая выплата возвращается с HTTP 201 Created и статусом created. Повторный запрос с тем же external_order_id возвращает HTTP 200 OK и существующую выплату. Сумма и комиссия в примере условные и не являются тарифом:

{
  "withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
  "external_order_id": "payout_usr_101",
  "status": "created",
  "is_final": false,
  "is_test": false,
  "amount": "25.00",
  "fee": "0.50",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "created_at": 1739277600
}

Стандартный лимит 30 запросов в секунду общий для API-запросов аккаунта. Ограничьте число одновременных запросов, делайте паузы при повторных попытках и учитывайте Retry-After при HTTP 429. Этот лимит не задает скорость завершения переводов. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production.

2. Получение вебхука об исполнении

При завершении выплаты Paymos отправляет withdrawal.completed в конверте вебхука с версией формата. В data лежит снимок выплаты: status, is_final и хеш завершенной транзакции:

{
  "event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
  "event_type": "withdrawal.completed",
  "version": 1,
  "occurred_at": 1739281200,
  "data": {
    "withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
    "external_order_id": "payout_usr_101",
    "status": "completed",
    "is_final": true,
    "is_test": false,
    "amount": "25.00",
    "fee": "0.50",
    "currency": "USDT",
    "network": "TRC20",
    "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
    "created_at": 1739277600,
    "completed_at": 1739281200
  }
}

Неуспешная выплата вызывает withdrawal.failed, отмена — withdrawal.cancelled. В обоих случаях вся зарезервированная сумма и комиссия возвращаются на доступный баланс. Проверяйте подпись по исходному телу вебхука и отсекайте повторы по event_id. Изменения в учете связывайте с data.withdrawal_id; события могут приходить не по порядку. При withdrawal.completion_rewound завершенная выплата возвращается в signed и требует дальнейшего отслеживания.

Подробнее о механике финализации транзакций читайте в руководстве по скорости вывода криптовалюты и решениях для SaaS-бизнеса.

Сравнение архитектур массовых выплат в криптовалюте (ноябрь 2026)
Архитектурный подходОтправка запросовУправление nonceЗатраты на комиссии сетиОптимально для
1. Синхронный цикл RPCЗависит от сети и реализацииКонтролируется вашей интеграциейЗависит от сети и ее ресурсовНебольшие пет-проекты, внутренние тесты
2. Запуск выплат в дашбордеДо 50 получателей в одном активе и одной сети; только ProductionNonce отправителя контролирует PaymosСубсидированный тариф сетиРегулярные зарплаты, ручные выплаты аффилиатам
3. Автоматический воркер API (POST /v1/withdrawals)Один получатель на запрос; общий лимит аккаунта 30 запросов/сNonce отправителя контролирует PaymosСубсидированный тариф (0% комиссии Paymos)iGaming, биржи, проп-трейдинг, агрегаторы

Частые вопросы

Почему нельзя отправлять выплаты простым циклом со скрипта?

В сетях EVM транзакции одного отправителя выполняются в порядке nonce. Если транзакция #5 остается в ожидании, следующие переводы с того же адреса могут ждать за ней. Это не означает, что все запросы API попадают в одну очередь блокчейна.

Как защититься от повторной отправки выплат при сбое сети?

Сохраните external_order_id с заявкой до первого запроса. После тайм-аута повторите запрос с тем же идентификатором и теми же данными. Paymos вернет существующую выплату. Transactional Outbox позволяет записать заявку и изменение внутреннего баланса одной транзакцией базы данных.

Как снижаются комиссии при массовых выплатах?

Комиссия Paymos за вывод — 0 %, сетевая комиссия субсидируется. Объединение заявок в очередь само по себе не снижает комиссию. В дашборде можно вручную запустить до 50 выплат в одном активе и одной сети, только в Production.

Что происходит, если адрес получателя заблокирован по AML?

Перед маршрутизацией выплаты Paymos проверяет адрес получателя по данным TRM Labs, Binance AML, AMLBot, PureFi и базе провайдера проверки. Если адрес не проходит проверку, выплата не отправляется и получает статус failed. Вся зарезервированная сумма вместе с сетевой комиссией возвращается на доступный баланс мерчанта.

Какие блокчейн-сети поддерживаются для выплат?

Для выплат доступны 11 основных сетей с учетом актива и доступности направления. TRON и TON поддерживают USDT; Arbitrum, BSC и Polygon — USDT и USDC. Base поддерживает только USDC. NEAR и Sui работают только на прием депозитов. Срок перевода зависит от сети и ее текущей нагрузки.

Когда НЕ стоит использовать API массовых выплат в криптовалюте

  • Если ручных выплат в дашборде достаточно и интеграция с API не нужна.
  • Если вы выплачиваете редкие невзаимозаменяемые токены (NFT) или неликвидные альткоины, требующие индивидуальной эскроу-проверки.
  • Если в вашей архитектуре нет возможности развернуть Transactional Outbox с гарантией идемпотентности.
  • Если по правилам комплаенса каждый исходящий перевод, независимо от суммы, должны одобрить два сотрудника: в Paymos нет цепочки согласования несколькими людьми, поэтому постройте ее в своей учетной системе до вызова API.

Источники

  1. 1. Документация Paymos Host-to-Host API: Выплаты
  2. 2. Спецификация Ethereum EIP-1559: Механика газа и транзакций

Последняя проверка: 7 нояб. 2026 г.

#massovye-vyplaty#usdt#crypto-payroll#rest-api#vyvody
Поделиться