Перейти к содержимому

Быстрый старт и API-ключи Chaingateway

API Chaingateway — это REST API, который создаёт кошельки, отправляет транзакции, читает балансы и доставляет вебхуки для нескольких блокчейнов по HTTPS и в формате JSON. Для вызова нужны аккаунт, API-токен и HTTP-клиент. Это руководство описывает все три шага и завершается первым запросом, который создаёт адрес Ethereum.

Схема запроса: приложение отправляет HTTPS-запрос с Bearer-токеном и необязательным заголовком X-Network в API Chaingateway, тот обращается к блокчейну и отвечает в формате JSON Ваше приложение HTTP-клиент: curl, requests, axios, Guzzle HTTPS-запрос кapp.chaingateway.io/api/v2/{chain}/... Authorization: Bearer-токен, при необходимостиX-Network: testnet API Chaingateway проверяет токен и тело запроса, обращается кблокчейну JSON-ответ status, ok, message, data
Что происходит при каждом вызове API.

Зарегистрируйте аккаунт, откройте страницу API-ключей и создайте токен. Новый аккаунт получает бесплатный пробный период на 7 дней, карта для начала не нужна. Создайте аккаунт по ссылке аккаунт Chaingateway или войдите в существующий, затем откройте страницу API-ключей.

Введите имя токена и нажмите «+ Create Token». Новый токен появится в списке. Храните его в надёжном месте и никому не передавайте. Любой, у кого есть токен, может вызывать API от имени вашего аккаунта. Не добавляйте токен в систему контроля версий, а загружайте его из переменной окружения или из файла .env.

Подойдёт любой клиент, который умеет отправлять HTTPS-запросы. Справочник API генерирует примеры для гораздо большего числа языков, чем эта страница. Здесь используются такие клиенты:

API следует семантике HTTP-методов из RFC 9110. Ресурсы, такие как addresses, transactions и webhooks, находятся в /api/v2/{chain}/, а метод определяет, что происходит с ресурсом. Ответы приходят в формате JSON.

МетодЗначениеПример в этом API
GETПрочитать ресурс или списокGET /api/v2/ethereum/addresses возвращает список ваших адресов
POSTСоздать ресурс или запустить действиеPOST /api/v2/ethereum/addresses создаёт адрес
PUTЗаменить поля существующего ресурсаPUT /api/v2/ethereum/webhooks/{id} обновляет вебхук
DELETEУдалить ресурсDELETE /api/v2/ethereum/addresses/{address} удаляет адрес

Адрес нельзя изменить, потому что его определяют ключи, поэтому для адресов нет PUT и PATCH. Исключение составляет пароль сохранённого ключа: он меняется через POST /api/v2/{chain}/addresses/{address}.

Отправляйте три заголовка: Authorization, Accept и, если у запроса есть тело, Content-Type. Необязательный четвёртый заголовок, X-Network, выбирает тестовую сеть.

  • Authorization: Bearer YOUR_API_TOKEN передаёт токен как Bearer-токен по RFC 6750. Запрос без действительного токена получает HTTP 401 и тело {"message":"Unauthenticated."}.
  • Accept: application/json запрашивает ответ в формате JSON.
  • Content-Type: application/json сообщает серверу, что тело запроса — JSON. API принимает и тела в формате формы, но в примерах используется JSON.
  • X-Network: testnet выполняет запрос в тестовой сети. Не указывайте заголовок или отправьте mainnet, чтобы работать в основной сети. Таблица сетей показывает, какие сети соответствуют каждому значению.

Создайте адрес Ethereum запросом POST. Тело — JSON-объект с одним полем password. Оно защищает приватный ключ, который Chaingateway хранит для этого адреса, и понадобится снова при каждой отправке транзакции с этого адреса. Что произойдёт, если пароль не указать, объясняет раздел Управление кошельками.

Окно терминала
curl --request POST \
--url https://app.chaingateway.io/api/v2/ethereum/addresses \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"password": "choose-a-strong-password"
}'

Успешный вызов возвращает статус 201. В файле OpenAPI ключ поля с адресом записан как adderess, поэтому читайте его под этим именем:

{
"status": 201,
"ok": true,
"message": "Address created",
"data": {
"adderess": "0x7d3bC832A0860fD882FF4C2359e10268f4E5CCf8"
}
}

Для чтения данных используется GET, у него нет тела запроса. Следующий вызов возвращает адреса, которые вы создали и не удалили.

Окно терминала
curl --request GET \
--url https://app.chaingateway.io/api/v2/ethereum/addresses \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Accept: application/json'

Как выполнить тот же вызов в тестовой сети?

Заголовок раздела «Как выполнить тот же вызов в тестовой сети?»

Добавьте заголовок X-Network: testnet и оставьте всё остальное без изменений. Адрес будет создан в Sepolia, а тестовые монеты не имеют рыночной стоимости. Работайте в тестовой сети, пока ваша интеграция не начнёт корректно обрабатывать успешные ответы и ошибки. Чтобы позже перейти на основную сеть, удалите заголовок или задайте значение mainnet.

Ошибки используют тот же JSON-конверт, что и успешные вызовы, с ok, равным false. Файл OpenAPI описывает коды статуса 200, 201, 400, 401, 404 и 422. Ошибка валидации перечисляет отклонённые поля:

{
"status": 422,
"ok": false,
"message": "Data validation failed",
"errors": {
"password": ["The password field is required."]
}
}

Ошибки блокчейна приходят так же. Транзакция без достаточного баланса для газа возвращает 422 с сообщением узла, а неверный пароль кошелька возвращает 401 с текстом Wrong password provided. Записывайте в лог message и errors при каждом неудачном вызове, потому что обычно они называют поле или причину.

  • RFC 9110, HTTP Semantics определяет методы и коды статуса, использованные выше.
  • RFC 6750, Bearer Token Usage определяет заголовок Authorization: Bearer.
  • RFC 8259, JSON определяет формат тел запросов и ответов.
  • Файл OpenAPI этого API перечисляет все эндпоинты, параметры и примеры ответов.