Один Blockchain API для криптоплатежей, семь сетей
Принимайте и отправляйте криптоплатежи в Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon и Arbitrum. Один REST API для кошельков, переводов токенов и вебхуков депозитов.
Chaingateway — это REST API для блокчейн-платежей. Вы генерируете адреса кошельков и отправляете токены обычными HTTPS-вызовами, а когда депозит приходит на один из ваших адресов, вебхук уведомляет ваш сервер в реальном времени. Один и тот же API покрывает Bitcoin, Ethereum, TRON, Solana, BNB Smart Chain, Polygon и Arbitrum.
Это покрытие важнее любой отдельной функции. Большинство blockchain API работают с одной сетью; команды, добавляющие вторую сеть, обычно получают вторую кодовую базу, потому что у каждой сети свой формат RPC и свои клиентские библиотеки. Chaingateway убирает это разделение. Маршрут для перевода ERC-20 в Ethereum — POST /api/v2/ethereum/transactions/erc20; в Polygon — POST /api/v2/polygon/transactions/erc20. Поменяйте один сегмент пути, и ваш существующий код заработает в следующей сети.
Здесь нет ноды для синхронизации и SDK для установки. Аутентификация — Bearer-токен в заголовке Authorization. Один дополнительный заголовок, X-Network: testnet, направляет любой вызов в тестовую сеть вместо mainnet. Бесплатный 7-дневный пробный период начинается без KYC.
Что покрывает API
Кошельки и адреса
Создавайте защищённые паролем кошельки для Ethereum, BSC, Polygon и TRON, либо переносите существующие ключи через эндпоинты импорта, такие как POST /api/v2/ethereum/addresses/import. Приватные ключи хранятся зашифрованными паролем, который знаете только вы, — Chaingateway не хранит в открытом виде ни ключи, ни пароли, поэтому без ваших учётных данных средства остаются на месте. Адреса Solana создаются через POST /api/v2/solana/addresses. Для платёжных продуктов обычный паттерн — один адрес на клиента или на счёт, что делает атрибуцию тривиальной: всё, что приходит на адрес X, принадлежит клиенту X, без сопоставления по сумме или метке.
Нативные и токен-транзакции
Отправляйте ETH, BNB, POL, TRX или BTC одним вызовом и перемещайте ERC-20, BEP-20, TRC-20 и SPL-токены через тот же интерфейс. Gas, цена gas и nonce — необязательные поля запроса: опустите их, и API заполнит их сам, так что вы передаёте получателя и сумму вместо сборки сырых транзакций. Суммы указываются в единицах токена, а не в базовых единицах: 100 означает 100 токенов того контракта, который вы указали. TRON идёт дальше остальных сетей: эндпоинты freeze и delegate покрывают стейкинг (с unfreeze и undelegate для отмены), а TRC-10 стоит рядом с TRC-20.
Декодированные данные блокчейна
Ответы приходят как читаемый JSON, а не hex. Декодированная транзакция TRON включает отправителя, получателя, сумму в единицах токена, номер блока и текущее число подтверждений. Именно это должен возвращать blockchain data API — значения, которые ваше приложение может хранить и показывать без парсера ABI.
Вебхуки для входящих платежей
Подпишитесь на события в сети и получайте уведомление сразу, как только депозит расчитается в сети. Задайте личный секрет в своём профиле, и каждое уведомление будет нести заголовок X-Signature, который может проверить ваш сервер. Доставки, завершившиеся неудачей, перечислены API и могут быть повторно отправлены одним вызовом.
Что работает в какой сети
Таблица сжимает текущий справочник API в одном виде: у каких сетей есть маршруты адресов, какие стандарты токенов можно отправлять и где задокументированы вебхуки депозитов.
| Сеть | Адреса | Переводы токенов | Вебхуки депозитов |
|---|---|---|---|
| Bitcoin | POST /api/v2/bitcoin/wallets/{wallet}/addresses | — (нет стандарта токенов) | GET /api/v2/bitcoin/webhooks/notifications |
| Ethereum | POST /api/v2/ethereum/addresses/import | ERC-20: POST /api/v2/ethereum/transactions/erc20 | GET /api/v2/ethereum/webhooks/notifications |
| TRON | POST /api/v2/tron/addresses/import | TRC-20 и TRC-10: POST /api/v2/tron/transactions/trc20 и .../trc10 | GET /api/v2/tron/webhooks/notifications |
| Solana | POST /api/v2/solana/addresses | SPL: POST /api/v2/solana/transactions/SPL | — |
| BNB Smart Chain | POST /api/v2/bsc/addresses/import | BEP-20: POST /api/v2/bsc/transactions/bep20 | GET /api/v2/bsc/webhooks/notifications |
| Polygon | POST /api/v2/polygon/addresses/import | ERC-20: POST /api/v2/polygon/transactions/erc20 | GET /api/v2/polygon/webhooks/notifications |
| Arbitrum | POST /api/v2/arbitrum/addresses/import | ERC-20: POST /api/v2/arbitrum/transactions/erc20 | GET /api/v2/arbitrum/webhooks/notifications |
Две сноски для правильного прочтения таблицы. Во-первых: TRON — самая глубокая интеграция на платформе. Помимо перечисленных выше маршрутов, в справочнике описаны стейкинг (POST /api/v2/tron/freeze и /delegate), параметры сети и пара для самостоятельного подписания — /transactions/trc20/build для построения транзакции и /transactions/broadcast для отправки транзакции, подписанной локально. Если ваша служба комплаенса настаивает, что приватные ключи никогда не покидают ваши серверы, этот паттерн build-and-broadcast — ваш путь.
Во-вторых: прочерк означает, что текущий справочник не документирует маршрут v2 для этой ячейки, а не то, что сеть второсортна. У Bitcoin нет стандарта токенов, поэтому ячейка токенов пуста — нативный BTC работает через собственную модель кошелька: создайте зашифрованный паролем кошелёк через POST /api/v2/bitcoin/wallets, деривируйте депозитные адреса под ним и отправляйте через POST /api/v2/bitcoin/transactions. Справочник Solana охватывает создание адресов, переводы SOL и SPL, а также запросы баланса и блоков, но пока без вебхуков. Для всего, что не перечислено здесь, актуальное состояние — в справочнике API.
Пример blockchain API: первый вызов на четырёх языках
Получите API-ключ (следующий раздел), затем убедитесь, что он работает. GET /api/account возвращает данные вашего аккаунта и подтверждает валидность ключа.
curl https://app.chaingateway.io/api/account \
-H "Authorization: Bearer YOUR_API_KEY"Это вся проверка аутентификации — создайте аккаунт, и тот же вызов подтвердит, что ваш собственный ключ работает.
Как получить ключ blockchain API
Зарегистрируйтесь на app.chaingateway.io/register. 7-дневный пробный период начинается без KYC.
Скопируйте API-ключ из своей панели.
Отправляйте его с каждым запросом как Authorization: Bearer ВАШКЛЮЧ и храните только на стороне сервера. Клиентский код раскроет его любому, кто откроет консоль браузера. Панель аккаунта дополнительно может ограничить ключ IP-адресами ваших серверов, так что утёкший ключ будет бесполезен где-либо ещё. Больше шагов усиления безопасности — в наших советах по безопасности для blockchain API.
Приём депозитов: поток вебхука
Платёжная интеграция обычно выглядит так:
Создайте или импортируйте депозитный адрес для каждого клиента.
Клиент отправляет монеты или токены на этот адрес.
Как только перевод расчитается, Chaingateway отправит POST-уведомление на ваш callback URL — с заголовком X-Signature, если вы задали личный секрет.
Ваш сервер проверяет подпись и зачисляет на счёт клиента.
Безопасность вебхуков на практике
Конечная точка вебхука — это дверь в ваш бэкенд, и эта конкретная дверь зачисляет деньги. Chaingateway даёт вам три механизма для её защиты; продакшн-обработчик должен использовать все три. Это применимо к шести сетям с вебхуками депозитов — обнаружение депозитов Solana использует опрос вместо этого, описано ниже.
1. Проверьте подпись
Задайте личный секрет в настройках профиля — с этого момента каждое уведомление будет нести заголовок X-Signature, построенный как base64 от HMAC-SHA256 по полю txid payload, с ключом из этого секрета. Пересчитайте его из полученного txid, сравните со значением заголовка перед зачислением чего-либо и используйте сравнение с постоянным временем — большинство стандартных библиотек его предоставляют. Отклоняйте сбои с кодом 401. Это закрывает очевидную атаку: любой, кто обнаружит ваш callback URL, может отправить туда POST с сфабрикованными депозитами, и без проверки подписи ваш магазин отгрузил бы товар за платежи, которых никогда не было.
2. Проектируйте под повторную доставку
Уведомление может дойти до вас более одного раза — вы можете повторно отправить неудачные через API, и между этим ничто не гарантирует доставку строго один раз. Привязывайте логику зачисления к хэшу транзакции, а не к числу полученных callback-вызовов — INSERT ... ON CONFLICT DO NOTHING по столбцу хэша стоит одной строки и убирает весь класс багов с двойным зачислением. Отвечайте кодом 2xx сразу после сохранения уведомления и выполняйте медленную обработку после этого; обработчик, делающий тяжёлую работу инлайн, натыкается на таймауты и превращает один депозит в обращение в поддержку.
3. Используйте маршруты восстановления
Если ваша конечная точка была недоступна или ответила ошибкой, доставка попадает в список неудачных: GET /api/v2/{chain}/webhooks/notifications/failed показывает, что не дошло, а POST /api/v2/{chain}/webhooks/notifications/{id}/retry повторно отправляет каждую по вашей команде. Для всего остального — отказ базы данных, неудачный деплой, истёкший TLS-сертификат — GET /api/v2/{chain}/webhooks/notifications возвращает полную историю доставок, так что ночная задача сверки может сравнить её с вашим реестром и исправить пробелы. Детали payload и код проверки — в руководстве по вебхукам.
Тестируйте в testnet, поставляйте тот же код
Каждый маршрут принимает один дополнительный заголовок, X-Network: testnet, и выполняется против тестовой сети вместо mainnet. Эндпоинты, тела запросов и формы ответов остаются идентичными; монеты ничего не стоят. Именно это последнее свойство и важно. Ваши интеграционные тесты могут создавать адреса, перемещать токены и получать вебхуки хоть весь день, не трогая реальные средства.
Практическая настройка выглядит так. Поместите заголовок за переменную окружения, чтобы staging его отправлял, а продакшен — нет, без разницы в коде между ними. Дайте staging собственный callback URL, иначе тестовые депозиты попадут в ваш продакшн-обработчик вебхуков и запутают реестр. Тестовые монеты бесплатно приходят из публичных кранов, которые держит каждая экосистема; страница поддерживаемых сетей в документации называет тестовую сеть для каждой цепи — Sepolia для Ethereum, Nile для TRON, Amoy для Polygon, testnet3 для Bitcoin.
Когда поток работает от начала до конца — адрес создан, депозит обнаружен, вебхук проверен, баланс зачислен, — удалите заголовок. Больше ничего не меняется. Эта симметрия намеренна, и именно поэтому запуск в продакшен — это изменение конфигурации, а не второй проект интеграции.
Три интеграции по шагам
Списки функций мало говорят об усилиях на интеграцию, поэтому вот три сборки, которые мы видим часто, каждая сведена к своим движущимся частям.
Депозиты для интернет-магазина
Магазин хочет принимать USDT на кассе. Когда клиент выбирает крипто, ваш бэкенд назначает адрес для этого заказа и показывает его рядом с суммой. Дальше работает вебхук. Уведомление приходит, как только перевод расчитается в сети; отметьте заказ как «платёж обнаружен» и покажите это клиенту, потому что быстрая обратная связь — вот что делает крипто-кассу заслуживающей доверия. Если ваша политика требует большей глубины для крупных сумм, проверяйте транзакцию через GET /api/v2/{chain}/transactions/{txid}, пока не достигнут ваш порог, затем отметьте заказ оплаченным и начните выполнение.
Два граничных случая решают, готова ли эта сборка для продакшена. Недоплата: клиенты иногда отправляют чуть меньше суммы счёта, обычно потому что их кошелёк вычел сетевую комиссию из введённой суммы. Определите допуск заранее — поглотите небольшую недостачу или задержите заказ и запросите разницу. Переплата встречается реже и решается проще: зачислите её или верните, но логируйте в любом случае. Оба случая вытекают из сравнения уведомлённой суммы с суммой счёта, а не из трактовки любого callback как «оплачено».
Пакетные выплаты
Партнёрская платформа платит сотням партнёров в стейблкоинах каждый месяц, в Polygon, потому что там комиссии остаются небольшими относительно сумм выплат. Сборка — это очередь и цикл:
import requests
payouts = load_pending_payouts() # [{"address": ..., "amount": ...}, ...]
for p in payouts:
r = requests.post(
"https://app.chaingateway.io/api/v2/polygon/transactions/erc20",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"contractaddress": "0xTokenContract...",
"from": "0xTreasuryWallet...",
"to": p["address"],
"amount": p["amount"],
"password": "treasury-wallet-password",
},
)
record_result(p, r.json()) # сохранить перед следующей итерацией
Очередь важнее цикла. Сохраняйте состояние каждой выплаты перед отправкой, немедленно записывайте ответ API и никогда не повторяйте отправку только потому, что HTTP-вызов завершился по таймауту — транзакция могла всё же пройти. Проверьте сохранённые результаты и GET /api/v2/polygon/transactions, который перечисляет каждую транзакцию, созданную через API, и отправляйте повторно только то, что доказуемо никогда не произошло. Именно это правило отделяет системы выплат, переживающие аудит, от систем выплат, заканчивающихся археологией по таблицам Excel.
Биллинг для SaaS в блокчейне
B2B-инструмент выставляет клиентам ежемесячные счета в стейблкоинах, потому что карточные процессоры постоянно отклоняют его категорию продавца. Сборка повторяет паттерн магазина с одним отличием: свежий депозитный адрес на каждый счёт, а не на клиента. Адрес на счёт делает сопоставление тривиальным — любая сумма, пришедшая на адрес счёта №4711, принадлежит счёту №4711, — и убирает необходимость угадывать при сопоставлении платежей по сумме, когда два счёта случайно складываются в одну и ту же сумму. Вебхук отмечает счета оплаченными; запланированная задача просрочивает устаревшие и рассылает напоминания. Ничто в этом потоке не требует интерфейса кошелька, расширения браузера или каких-либо крипто-знаний со стороны клиента, кроме способности отправить перевод.
Поддерживаемые блокчейны
У каждой сети своя страница с эндпоинтами и примерами кода:
- Bitcoin API — исходная сеть. Нативные переводы BTC из зашифрованных паролем кошельков плюс вебхуки депозитов для входящих платежей.
- Ethereum API — самая широко распространённая платформа смарт-контрактов, с переводами токенов ERC-20 и поддержкой NFT ERC-721.
- TRON API — транзакции TRC-10 и TRC-20, стейкинг через freeze и delegate, и маршруты самостоятельной подписи build/broadcast. Оцените стоимость перевода заранее с помощью калькулятора комиссий TRON.
- Solana API — создание адресов и транзакции SPL-токенов в высокопроизводительной сети.
- BNB Smart Chain API — переводы BEP-20 по той же схеме маршрутов, что вы используете в Ethereum.
- Polygon API — переводы ERC-20 в масштабирующей сети Ethereum по цене малой доли комиссий mainnet. Это blockchain API для сети Polygon, а не сервис биржевых данных Polygon.io.
- Arbitrum API — Layer 2 Ethereum для высокой пропускной способности, с той же структурой эндпоинтов, что в mainnet.
Миграция с JSON-RPC на REST
Blockchain API заменяет сырые вызовы JSON-RPC одним аутентифицированным REST-запросом на действие. Там, где JSON-RPC требует несколько циклов на перевод, плюс ручное кодирование ABI, отслеживание nonce и подпись, вызов вроде POST /api/v2/{chain}/transactions/erc20 (bep20 в BNB Smart Chain) сворачивает всё это в один запрос.
Многие команды приходят сюда с уже работающей интеграцией: web3.js против платного RPC-эндпоинта, либо самодельный клиент JSON-RPC из более ранней эпохи кодовой базы. Миграция менее драматична, чем звучит, потому что API поглощает целые категории кода, а не заменяет его вызов за вызовом.
Возьмём канонический путь отправки в EVM. Через JSON-RPC перевод токена — это последовательность: eth_getTransactionCount для nonce, eth_gasPrice или вызов истории комиссий для ценообразования, eth_estimateGas против ABI-закодированных calldata, локальная подпись, затем eth_sendRawTransaction для трансляции. У каждого шага есть сценарии сбоев, которые ваш код сейчас обрабатывает — или молча не обрабатывает. Все пять сворачиваются в один аутентифицированный POST к /api/v2/{chain}/transactions/erc20, а учёт nonce, обычный источник обращений о «застрявшей транзакции», полностью покидает вашу кодовую базу.
Обнаружение событий меняет форму сильнее, чем логику. Там, где вы опрашивали eth_getLogs с курсором блока или держали открытой WebSocket-подписку через каждый баг переподключения, теперь вы регистрируете вебхук и удаляете опрашивающий цикл. Ваша нижестоящая логика — разобрать перевод, сопоставить клиента, зачислить баланс — остаётся как есть; меняется только входная сторона, с pull на push.
Что не переносится: инструменты консенсуса, собственные индексаторы, всё, что требует сырого доступа к блокам. Держите RPC-эндпоинт для этих задач; оба подхода сосуществуют без трения. Платежи обычно первая нагрузка, которую стоит перенести, потому что они несут наибольший операционный риск на строку кода. Более длинное сравнение, включая случаи, где нода выигрывает, — в статье blockchain API против blockchain node.
Когда запрос завершается неудачей
Обработка ошибок для платёжного API заслуживает большего, чем общий catch-блок, потому что неудачный запрос и неудачная транзакция — разные события.
HTTP-уровень следует соглашениям REST. 401 означает, что Bearer-токен отсутствует, неверен или истёк — исправьте учётные данные, не повторяйте. Другие ответы в диапазоне 4xx говорят, что виноват сам запрос: некорректный адрес, отсутствующее поле, ошибка валидации. Логируйте тело ответа, называющее конкретную проблему, и относитесь к этому как к багам, которые нужно исправить, а не к временным условиям для повтора. Диапазон 5xx и сетевые таймауты формируют временный класс, где повтор с экспоненциальной задержкой — правильный рефлекс.
С одним исключением, и это исключение важно. Никогда не повторяйте вслепую запрос, перемещающий средства. Таймаут говорит вам, что вы не получили ответ, а не что транзакция провалилась. Безопасная последовательность: проверьте, ушёл ли перевод, используя ваши сохранённые результаты и GET /api/v2/{chain}/transactions (список транзакций, созданных вашим ключом), и отправляйте повторно только когда можете показать, что этого никогда не произошло. Ключи идемпотентности на вашей стороне, привязанные к вашим собственным ID выплат или заказов, делают эту проверку дешёвой.
Встройте наблюдаемость с первого дня. Логируйте пары запрос-ответ для каждого вызова, перемещающего деньги, и оповещайте по частоте 4xx, а не только 5xx — внезапный всплеск ошибок валидации обычно означает, что деплой сломал формат вашего запроса. Поймать это за минуты вместо дней — разница между инцидентом и сноской.
Запускать собственные ноды или использовать API?
Самостоятельный запуск нод даёт полный контроль и отсутствие зависимости от третьей стороны. Это также означает по одной машине на сеть, бюджеты диска и пропускной способности, мониторинг синхронизации и обновления версий — умноженные на семь, если вы хотите покрытие, описанное выше. Наше сравнение blockchain API против blockchain node проходит через этот компромисс. Кратко: запускайте ноду, когда вам нужен контроль уровня консенсуса, используйте API, когда вам нужны работающие платежи уже на этой неделе.
Часто задаваемые вопросы
Готовы принимать криптоплатежи?
Создайте аккаунт на app.chaingateway.io/register, выберите сеть из семи выше и отправьте тестовый перевод. Полный справочник эндпоинтов — в документации, а тарифы и лимиты запросов перечислены на отдельной странице.