Быстрый старт и API-ключи Chaingateway
API Chaingateway — это REST API, который создаёт кошельки, отправляет транзакции, читает балансы и доставляет вебхуки для нескольких блокчейнов по HTTPS и в формате JSON. Для вызова нужны аккаунт, API-токен и HTTP-клиент. Это руководство описывает все три шага и завершается первым запросом, который создаёт адрес Ethereum.
Как создать аккаунт и API-ключ?
Заголовок раздела «Как создать аккаунт и API-ключ?»Зарегистрируйте аккаунт, откройте страницу API-ключей и создайте токен. Новый аккаунт получает бесплатный пробный период на 7 дней, карта для начала не нужна. Создайте аккаунт по ссылке аккаунт Chaingateway или войдите в существующий, затем откройте страницу API-ключей.
Введите имя токена и нажмите «+ Create Token». Новый токен появится в списке. Храните его в надёжном месте и никому не передавайте. Любой, у кого есть токен, может вызывать API от имени вашего аккаунта. Не добавляйте токен в систему контроля версий, а загружайте его из переменной окружения или из файла .env.
Какой HTTP-клиент использовать?
Заголовок раздела «Какой HTTP-клиент использовать?»Подойдёт любой клиент, который умеет отправлять HTTPS-запросы. Справочник API генерирует примеры для гораздо большего числа языков, чем эта страница. Здесь используются такие клиенты:
- curl для shell-скриптов
- Requests для Python
- Axios для JavaScript и Node.js
- Guzzle для PHP или HTTP-клиент Laravel
Что означают методы REST в этом API?
Заголовок раздела «Что означают методы REST в этом 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"}'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"payload = {"password": "choose-a-strong-password"}headers = { "Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json", "Content-Type": "application/json",}response = requests.post(url, json=payload, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'POST', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json', 'Content-Type': 'application/json', }, data: { password: 'choose-a-strong-password' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('POST', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'json' => ['password' => 'choose-a-strong-password'], 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();Успешный вызов возвращает статус 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'import requests
url = "https://app.chaingateway.io/api/v2/ethereum/addresses"headers = {"Authorization": "Bearer YOUR_API_TOKEN", "Accept": "application/json"}response = requests.get(url, headers=headers)print(response.json())import axios from 'axios';
const options = { method: 'GET', url: 'https://app.chaingateway.io/api/v2/ethereum/addresses', headers: { Authorization: 'Bearer YOUR_API_TOKEN', Accept: 'application/json' },};
try { const { data } = await axios.request(options); console.log(data);} catch (error) { console.error(error.response?.data ?? error);}<?php$client = new \GuzzleHttp\Client();$response = $client->request('GET', 'https://app.chaingateway.io/api/v2/ethereum/addresses', [ 'headers' => [ 'Authorization' => 'Bearer YOUR_API_TOKEN', 'Accept' => 'application/json', ],]);echo $response->getBody();Как выполнить тот же вызов в тестовой сети?
Заголовок раздела «Как выполнить тот же вызов в тестовой сети?»Добавьте заголовок 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 перечисляет все эндпоинты, параметры и примеры ответов.