API BNB Smart Chain: что можно построить
Что предоставляет API BNB Smart Chain (BSC): кошельки, переводы BNB и BEP-20, балансы и вебхуки, примеры запросов и ограничения публичного RPC.
Проверил(а) Maurice Sobiera
API BNB Smart Chain — веб-интерфейс для BNB Smart Chain (BSC), ранее Binance Smart Chain. Он позволяет приложению создавать кошельки, отправлять BNB и токены BEP-20, читать балансы и получать уведомления о депозитах без собственной ноды BSC. Ваш бэкенд отправляет HTTPS-запросы, а провайдер берёт на себя подпись, рассылку транзакций и доступ к сети.
В этой статье перечислено, что охватывает такой API, показаны два запроса к эндпоинтам Chaingateway для BSC и объяснено, когда публичных RPC-эндпоинтов достаточно.
Что охватывает API BSC?
API BSC охватывает операции, которые нужны платёжному или кошельковому бэкенду. Эндпоинты Chaingateway, перечисленные в файле OpenAPI, делятся на пять групп:
| Группа | Эндпоинты |
|---|---|
| Адреса | POST /api/v2/bsc/addresses создаёт кошелёк, GET возвращает список кошельков, POST /api/v2/bsc/addresses/import импортирует приватный ключ |
| Балансы | GET /api/v2/bsc/balances/{address} для BNB, GET /api/v2/bsc/balances/{address}/bep20/{contract_address} для токена BEP-20 |
| Переводы | POST /api/v2/bsc/transactions для BNB, POST /api/v2/bsc/transactions/bep20 для токенов BEP-20, POST /api/v2/bsc/transactions/bep721 для NFT |
| Данные цепочки | Последний блок, блок по номеру или хешу, транзакция, квитанция, цена газа, владелец NFT и URI токена |
| Вебхуки | Создание, обновление и удаление вебхуков, список уведомлений, список неудачных уведомлений и их повторная отправка |
Все запросы используют bearer-токен в заголовке Authorization. Отправьте X-Network: testnet, чтобы использовать тестовую сеть. Без этого заголовка запрос уходит в mainnet.
Как проверить баланс и отправить BNB?
Баланс проверяется одним запросом GET, затем BNB отправляется одним запросом POST. Оба примера используют базовый URL https://app.chaingateway.io и токен из панели управления.
curl https://app.chaingateway.io/api/v2/bsc/balances/0x0000000000000000000000000000000000001000 \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "X-Network: testnet"Ответ содержит баланс в виде десятичной строки:
{"status": 200, "ok": true, "message": "Balance fetched", "data": "0.000000000000000000"}Чтобы отправить BNB с кошелька, созданного через API, передайте в POST-запросе отправителя, получателя, сумму и пароль кошелька. Поля газа необязательны.
curl -X POST https://app.chaingateway.io/api/v2/bsc/transactions \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "X-Network: testnet" \ -H "Content-Type: application/json" \ -d '{"from": "0x...", "to": "0x...", "amount": "0.001", "password": "wallet-password"}'Если у отправителя не хватает BNB на сумму и газ, API возвращает статус 422 с сообщением ноды insufficient funds. Неверный пароль кошелька возвращает 401.
Как прочитать баланс токена и транзакцию?
Баланс токена BEP-20 читается по адресу кошелька и адресу контракта токена в пути запроса. Транзакцию читают по её хешу. Оба варианта — запросы GET с теми же заголовками, что и выше.
# BEP-20 token balancecurl https://app.chaingateway.io/api/v2/bsc/balances/0xWalletAddress/bep20/0xTokenContract \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN"
# Transaction with decoded datacurl https://app.chaingateway.io/api/v2/bsc/transactions/0xTransactionHash/decoded \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN"
# Current gas pricecurl https://app.chaingateway.io/api/v2/bsc/gasprice \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN"Эндпоинт баланса возвращает сумму токена в виде десятичной строки, поэтому на decimals умножать самостоятельно не нужно. Эндпоинт декодированной транзакции возвращает её в читаемых полях вместо сырых hex-данных. Неизвестный хеш даёт ответ 422 с сообщением transaction not found.
GET /api/v2/bsc/transactions выводит историю ваших транзакций. В неё входят только транзакции, созданные через API Chaingateway, потому что Chaingateway сам не индексирует ваши адреса. Чтобы видеть входящие переводы, используйте вебхук.
Если кошелёк у вас уже есть, POST /api/v2/bsc/addresses/import импортирует его приватный ключ. Импортированные и новые кошельки используют одни и те же эндпоинты отправки и вебхуков.
Как получать уведомления о депозитах?
Создайте вебхук запросом POST /api/v2/bsc/webhooks. Поле url обязательно. Фильтруйте по to (адрес получения), по from или по contractaddress для токена, а в type укажите BNB, BEP20 или BEP721. Когда найдена подходящая транзакция, Chaingateway отправляет её данные на ваш URL.
Вебхуки не повторяются автоматически. Неудачная доставка появляется в GET /api/v2/bsc/webhooks/notifications/failed, а POST /api/v2/bsc/webhooks/notifications/{id}/retry отправляет её повторно. Сделайте принимающий эндпоинт идемпотентным, с ключом по ID транзакции, чтобы повтор не зачислил средства на аккаунт дважды.
Что такое BEP-20?
BEP-20 — стандарт токенов BNB Smart Chain. Согласно его спецификации, он основан на ERC-20 из Ethereum и требует функции symbol(), decimals(), totalSupply(), balanceOf(), transfer(), transferFrom(), approve() и allowance(). Поэтому один и тот же код кошелька работает с токенами в BSC и в Ethereum. По той же причине эндпоинты Chaingateway для BSC повторяют эндпоинты для Ethereum.
Когда достаточно публичных RPC-эндпоинтов?
BNB Chain публикует публичные JSON-RPC-эндпоинты для mainnet и testnet. В документации BNB Chain указан лимит 10 000 запросов за 5 минут. Там же сказано, что eth_getLogs отключён на публичных эндпоинтах mainnet.
Для прототипов и редких чтений этого достаточно. Сервису, который следит за множеством адресов, нужны либо собственная нода, либо провайдер, либо API, который отправляет события вам. Путь с собственной нодой описан в статье как работать с нодой через JSON-RPC. Подробнее о стороне Chaingateway — на странице API BSC.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API Binance Smart Chain для полного справочника по эндпоинтам.