← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Сценарии использования blockchain API: шесть примеров

Шесть сценариев использования blockchain API с эндпоинтами Chaingateway: платежи, выплаты, кошельки, мониторинг, поиск данных и проверка NFT.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) 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 заказа.

Terminal window
# 1. Create a password-protected deposit address
curl -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 transfers
curl -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-дневный бесплатный пробный период без карты, и для начала не нужна проверка личности. Шаги короткие:

  1. Создайте аккаунт и скопируйте API-токен из панели управления.
  2. Создайте тестовый адрес и пополните его из публичного крана выбранной тестовой сети.
  3. Зарегистрируйте вебхук, который указывает на публичный URL вашего приёмника.
  4. Отправьте тестовый перевод и проверьте, что уведомление пришло и его подпись проверяется.

Наше руководство по быстрому старту проходит эту последовательность с примерами кода.

Какие сценарии плохо подходят?

API такого типа плохо подходит для задач, которым нужна полная история транзакций любых адресов, например аналитика, налоговая отчётность или решения о кредитовании. Этим задачам нужен индексатор, который сохраняет каждую транзакцию, а не сервис, который отправляет транзакции и уведомляет о зарегистрированных вами адресах. Эту часть создайте или купите отдельно, а API используйте для транзакций и уведомлений.

Как мы пишем эти статьи

Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.