Сценарии использования blockchain API: шесть примеров
Шесть сценариев использования blockchain API с эндпоинтами Chaingateway: платежи, выплаты, кошельки, мониторинг, поиск данных и проверка NFT.
Проверил(а) Maurice Sobiera
Blockchain API — это веб-сервис, который позволяет приложению создавать адреса, читать балансы, отправлять транзакции и получать уведомления по HTTPS без запуска нод блокчейна. Он оборачивает низкоуровневый интерфейс ноды, обычно JSON-RPC, в меньший набор вызовов. Сценарии ниже показывают, какие вызовы нужны каждому из них.
Для чего используют blockchain API?
Типичные задачи сводятся к шести. Каждая соответствует нескольким эндпоинтам REST API Chaingateway. Тот же принцип работает во всех поддерживаемых сетях, кроме отдельно оговорённых случаев.
| Сценарий | Что делает приложение | Основные эндпоинты (показан Ethereum) |
|---|---|---|
| Приём криптоплатежей | Создаёт адрес для депозита на каждый заказ и ждёт оплаты | POST /addresses, POST /webhooks, GET /balances/{address} |
| Выплаты или airdrop токенов | Отправляет нативные монеты или токены многим адресам | POST /transactions, POST /transactions/erc20 |
| Бэкенд кошелька | Создаёт, импортирует и экспортирует адреса | POST /addresses, POST /addresses/import, GET /addresses/export/{address} |
| Мониторинг адресов | Реагирует на входящие и исходящие переводы | POST /webhooks, GET /webhooks/notifications |
| Поиск данных блокчейна | Читает блоки, транзакции и квитанции | GET /blocks/{block_number}, GET /transactions/{txid} |
| Проверка NFT | Читает владельца токена и URI метаданных | GET /nfts/{contract_address}/owner/{token_id} |
Все пути начинаются с /api/v2/{blockchain}, например /api/v2/ethereum/addresses. Полный список есть в справочнике API.
Как принимать криптоплатежи через API?
Создайте один адрес для депозита на каждый заказ, зарегистрируйте для него вебхук и считайте вебхук сигналом, что платёж пришёл. Вызов создания адреса возвращает новый адрес. Вызов вебхука принимает адрес (to), url и type, например ETH, ERC20 или ERC721, а также необязательный reference длиной до 255 символов, который можно использовать как ID заказа.
# 1. Create a password-protected deposit addresscurl -X POST https://app.chaingateway.io/api/v2/ethereum/addresses \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"password": "a-long-random-password"}'
# 2. Watch it for incoming ERC-20 transferscurl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "0xDepositAddressFromStep1", "contractaddress": "0xTokenContractAddress", "type": "ERC20", "url": "https://shop.example.com/hooks/chaingateway", "reference": "order-10231" }'Когда появляется подходящий перевод, Chaingateway отправляет уведомление на ваш URL. Проверьте заголовок X-Signature, а затем сверьте сумму с блокчейном, прежде чем выдавать товар. Вебхуки не повторяются автоматически: неудачные уведомления перечислены по адресу /webhooks/notifications/failed и могут быть отправлены повторно. Solana не поддерживает вебхуки, поэтому там опрашивайте эндпоинт баланса. Полный процесс описан в нашем руководстве по платёжным вебхукам.
Как отправлять выплаты или airdrop?
Вызывайте эндпоинт транзакций из скрипта по одному разу на каждого получателя. Для токенов используйте POST /api/v2/ethereum/transactions/erc20 с отправителем, адресом контракта, получателем и суммой.
Каждому переводу нужен газ в нативной монете сети на адресе отправителя. Перед большой партией проверьте GET /gasprice и отправляйте переводы последовательно для каждого адреса отправителя, чтобы nonce не совпали. Переводы NFT используют эндпоинт erc721, он описан в статье Перевод NFT через API.
Может ли API работать как бэкенд кошелька?
Да, но в пределах ограничений. Эндпоинты адресов создают адреса, а параметр password хранит приватный ключ на сервере в зашифрованном виде, поэтому отправлять можно с паролем вместо ключа. Существующий адрес можно импортировать, а приватный ключ экспортировать позже. В руководстве по управлению кошельками перечислены компромиссы. А в наших советах по безопасности объясняется, почему средства на долгий срок должны храниться в холодном хранилище.
Балансы читаются через GET /balances/{address} для нативной монеты и через GET /balances/{address}/erc20 для токенов. Эндпоинт списка транзакций показывает только транзакции, созданные через API Chaingateway. Он не индексирует все транзакции адреса, поэтому если нужны ещё и входящие переводы, используйте вебхуки.
Как отслеживать адреса и искать данные блокчейна?
Для событий используйте вебхуки, а для истории — эндпоинты поиска. Вебхуки покрывают адреса и контракты, которые вы зарегистрировали. Для всего остального читайте блоки по номеру, транзакцию по хешу или декодированную транзакцию. У Bitcoin есть собственные эндпоинты на основе кошельков в /api/v2/bitcoin. Если вам нужен прямой доступ к ноде вместо этих вызовов, методы описаны в справочнике JSON-RPC для Ethereum и справочнике RPC для Bitcoin.
Какие сети поддерживают какой сценарий?
Поддержка различается по сетям, что видно в файле OpenAPI. Проверьте эту таблицу, прежде чем проектировать вокруг какой-либо функции.
| Сеть | Вебхуки | Переводы токенов | Поиск владельца и URI NFT | Модель кошелька |
|---|---|---|---|---|
| Ethereum, Polygon, Arbitrum | Да | ERC-20 и ERC-721 | Да | Отдельные адреса |
| BNB Smart Chain | Да | BEP-20 и BEP-721 | Да | Отдельные адреса |
| TRON | Да | TRC-20 и TRC-721 | Нет эндпоинта поиска | Отдельные адреса |
| Solana | Нет | SPL | Да | Отдельные адреса |
| Bitcoin | Да | Только нативная монета | Не применимо | Кошельки, которые содержат адреса |
Поэтому платёжный процесс, который опирается на вебхуки, нуждается в опросе как запасном варианте на Solana. Процессу, который опирается на проверку владения NFT, на TRON нужен другой источник данных.
Как опробовать сценарий без реальных средств?
Сначала запустите его в тестовой сети. Добавьте заголовок X-Network: testnet к любому запросу, и тот же эндпоинт будет работать с тестовой сетью вместо основной. Чтобы вернуться, уберите заголовок или задайте mainnet. Так можно проверить создание адреса, перевод и цикл вебхука, включая проверку подписи, прежде чем в дело вступят реальные средства.
У Chaingateway есть 7-дневный бесплатный пробный период без карты, и для начала не нужна проверка личности. Шаги короткие:
- Создайте аккаунт и скопируйте API-токен из панели управления.
- Создайте тестовый адрес и пополните его из публичного крана выбранной тестовой сети.
- Зарегистрируйте вебхук, который указывает на публичный URL вашего приёмника.
- Отправьте тестовый перевод и проверьте, что уведомление пришло и его подпись проверяется.
Наше руководство по быстрому старту проходит эту последовательность с примерами кода.
Какие сценарии плохо подходят?
API такого типа плохо подходит для задач, которым нужна полная история транзакций любых адресов, например аналитика, налоговая отчётность или решения о кредитовании. Этим задачам нужен индексатор, который сохраняет каждую транзакцию, а не сервис, который отправляет транзакции и уведомляет о зарегистрированных вами адресах. Эту часть создайте или купите отдельно, а API используйте для транзакций и уведомлений.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.