Интеграция нескольких блокчейнов через REST API
Как подключить несколько блокчейнов через один REST API: сети, эндпоинты токенов для каждой цепочки, поток депозитов и выводов и различия, которые сохраняются.
Проверил(а) Maurice Sobiera
Интеграция нескольких блокчейнов означает, что один бэкенд работает с несколькими сетями через единый интерфейс, а не через отдельную библиотеку для каждой сети. В Chaingateway вы вызываете REST-эндпоинты с bearer-токеном. Тот же подход работает для Ethereum, BNB Smart Chain, Polygon, Arbitrum, Tron, Bitcoin и Solana в пределах ограничений, которые задаёт каждая сеть.
Какие блокчейны и стандарты токенов поддерживает API?
API охватывает семь сетей, и у каждой есть тестовая сеть. Чтобы переключиться на тестовую сеть, передайте заголовок X-Network: testnet. На странице поддерживаемых сетей перечислены тестовые сети. Для переводов токенов есть отдельный эндпоинт для каждой сети:
| Сеть | Эндпоинты токенов и NFT в файле OpenAPI | Тестовая сеть |
|---|---|---|
| Ethereum | transactions/erc20, transactions/erc721 | Sepolia |
| BNB Smart Chain | transactions/bep20, transactions/bep721 | BSC testnet |
| Polygon | transactions/erc20, transactions/erc721 | Amoy |
| Arbitrum | transactions/erc20, transactions/erc721 | Arbitrum Sepolia |
| Tron | transactions/trc20, transactions/trc721, transactions/trc10 | Nile |
| Solana | transactions/SPL | Devnet |
| Bitcoin | transactions (только нативная монета) | Testnet3 |
Каждый путь начинается с /api/v2/<chain>/. Полный список находится в файле OpenAPI.
Как построить на нём сервис депозитов и выводов?
Поток по типу кастодиального сервиса состоит из трёх частей: адрес для каждого клиента, вебхук для каждого адреса и вызов вывода. Каждая часть выполняется одним запросом, и в каждой сети, которая её поддерживает, она выглядит одинаково.
- Создайте адрес для депозита. В EVM-сетях и Tron это
POST /api/v2/<chain>/addresses, а в ответе находится адрес. Передайтеpassword, чтобы ключ хранился в зашифрованном виде. Без пароля ответ содержит приватный ключ, и его придётся хранить самостоятельно. - Зарегистрируйте вебхук для адреса.
POST /api/v2/<chain>/webhooksпринимаетurlполучателя, адрес в полеto,typeвидаERC20илиTRC20и, по желанию,contractaddressиreferenceдлиной до 255 символов. - Выполните выплату. Вывод токена ERC20 — это один запрос:
curl -X POST https://app.chaingateway.io/api/v2/ethereum/transactions/erc20 \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": "0xHotWalletAddress", "to": "0xCustomerAddress", "contractaddress": "0xTokenContract", "amount": 100, "password": "hot-wallet-password" }'В BNB Smart Chain замените ethereum/transactions/erc20 на bsc/transactions/bep20. В Tron используйте tron/transactions/trc20: он принимает те же поля, кроме настроек газа. Solana устроена иначе: solana/transactions/SPL требует privatekey отправителя и не принимает пароль кошелька. Статья о персональных секретах объясняет, как проверять получаемые уведомления.
Что происходит, когда запрос не проходит?
API возвращает JSON с полями status, ok и message. Ответ 401 с сообщением «Wrong password provided» означает, что пароль кошелька не совпадает. Ответ 422 содержит собственную ошибку ноды, например insufficient funds for gas * price + value. Причина зависит от сети: перевод ERC20 в Ethereum требует ETH на адресе отправителя для газа, а перевод TRC20 требует energy и bandwidth или TRX для их оплаты. Проверьте балансы перед повтором, потому что повтор не устраняет нехватку комиссии.
Неудачные уведомления вебхуков не отправляются повторно автоматически. Получите их списком через GET /api/v2/<chain>/webhooks/notifications/failed и отправьте каждое заново через эндпоинт повтора. Повторное уведомление может прийти позже других, поэтому сделайте обработчик идемпотентным по txid.
Что остаётся различным между сетями?
Несколько вещей остаются различными, и API их не скрывает:
- Комиссии: Ethereum, BNB Smart Chain, Polygon и Arbitrum используют газ, для каждой есть эндпоинт
gasprice. Tron использует energy и bandwidth. - Вебхуки: поддерживаются во всех сетях, кроме Solana.
- Кошельки: в Bitcoin работают именованные кошельки, в которых хранится несколько адресов. Они создаются через
POST /api/v2/bitcoin/wallets. - Активы: один и тот же токен в двух сетях — это два разных актива, и API не выполняет между ними мост.
С какой сети начать?
Начните с той сети, которую уже используют ваши клиенты, а остальные добавьте, переиспользуя те же обработчики. В формах вывода бирж указана сеть, например ERC-20, BEP-20 или TRC-20. Прежде чем строить вторую интеграцию, спросите первых клиентов, в какой сети они хранят USDT.
Что сохранять для каждой сети?
Сервису с несколькими сетями нужна сеть в каждой записи, потому что одна и та же строка может быть валидной в нескольких сетях. Храните как минимум эти поля:
| Поле | Зачем оно нужно |
|---|---|
chain и network | Адреса 0x валидны в Ethereum, BNB Smart Chain, Polygon и Arbitrum, а мейннет и тестнет выглядят одинаково |
address в формате сети | Адреса Tron в Base58 начинаются с T, а шестнадцатеричная запись с префиксом 41 встречается в сырых данных ноды |
contractaddress и type | У одного и того же токена в каждой сети свой контракт |
txid | Ключ для дедупликации уведомлений вебхуков и для поиска |
reference | Ваш номер заказа или клиента, задаётся при регистрации вебхука |
| Сумма в базовой единице сети | Количество десятичных знаков различается у токенов, поэтому переводите значения только на уровне отображения |
Добавьте уникальное ограничение на (chain, network, txid). Сверяйте данные по расписанию со вторым источником, например со списком неудачных уведомлений и обозревателем блоков.
Как начать?
Начните с тестовых сетей. Создайте адрес в Sepolia и один в Nile, зарегистрируйте вебхук для каждого, отправьте тестовый перевод и проверьте, что ваш обработчик принимает оба уведомления. Бесплатный пробный период на 7 дней не требует карты и KYC.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.