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

Создание адресов Ethereum и Tron через API

Адрес создаётся одним запросом: POST /api/v2/{chain}/addresses. Если тело запроса содержит password, Chaingateway хранит приватный ключ в зашифрованном виде, а в ответе возвращается только адрес. Без пароля ответ содержит приватный ключ. В руководстве показаны оба варианта для Ethereum и Tron. Те же запросы работают для BNB Smart Chain, Polygon и Arbitrum.

Для запросов ниже нужен API-токен. Как его создать, описано в разделе Быстрый старт.

Создание адреса: POST-запрос на /addresses с паролем или без него, в ответе адрес, а без пароля ещё и приватный ключ POST /api/v2/{chain}/addresses Authorization: Bearer token С паролем ключ хранится зашифрованным, в ответе адрес Без пароля в ответе адрес и приватный ключ, ключ хранитевы
Пароль определяет, у кого хранится приватный ключ.

Передайте поле password в JSON-теле запроса. Для EVM-сетей Chaingateway создаёт keystore, то есть зашифрованный файл с приватным ключом. Его формат описан в определении Web3 secret storage. Keystore шифруется вашим паролем. Тот, у кого есть только keystore или только пароль, не получит доступа к адресу, а для ваших транзакций вместо приватного ключа нужен пароль.

password вы выбираете сами. Chaingateway не хранит его и не может восстановить. Если вы потеряете пароль, вы потеряете доступ к адресу, поэтому храните его в менеджере паролей или в хранилище секретов.

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

Ответ приходит со статусом 201. В файле OpenAPI ключ с адресом записан как adderess:

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

Не передавайте password. Тогда в ответе придёт приватный ключ, и каждая транзакция с этого адреса требует передать его в поле privatekey. Используйте этот режим только для одноразовых адресов, потому что приватный ключ, который уходит в каждом запросе, легко утечь. В примере создаётся адрес Tron.

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

Адрес Tron, созданный без пароля, сразу возвращает ключевые данные:

{
"status": 201,
"ok": true,
"message": "Address created",
"data": {
"privateKey": "59f1c6200e01a2ca9471411f10198bfa63678d0e87cc2ca30f9c4a68dee78edc",
"publicKey": "040fe6e677442c36f7fdd5535ba3ff1cef0110d78363420f7e24b65298990e3467aed68b9a67e1396d84753db25b32a2fa3e1fc0a673f01638e9bcfab2d8f4ceb5",
"hexAddress": "41a56a6505ffbee78eb916dd44f4846874deddaebd",
"address": "TR3qx91smURF3R455V1ubqtoUsZbgqikfg"
}
}

Храните privateKey вместе с address в надёжном месте. Ключ в этом примере — условное значение, поэтому никогда не пополняйте его. Как связаны адрес в base58 и hex-адрес, объясняет документация Tron по аккаунтам.

Прочитайте баланс, пополните адрес и затем отправляйте с него средства. GET /api/v2/ethereum/balances/{address} возвращает баланс адреса в виде строки:

{
"status": 200,
"ok": true,
"message": "Balance fetched",
"data": "0.000000000000000000"
}

Новый адрес начинается с нулевого баланса. Отправьте на него монеты с кошелька, которым вы управляете, или из testnet-крана сети, если вы работаете с X-Network: testnet. GET /api/v2/ethereum/addresses выводит список всех созданных вами и ещё не удалённых адресов. Если вам нужно уведомление о поступлении средств, создайте вебхук для адреса. Отправка средств с адреса описана в разделе Отправка транзакций ETH, BNB, TRX и BTC.

Bitcoin и Solana отличаются. В Bitcoin сначала создаётся кошелёк через POST /api/v2/bitcoin/wallets, а затем в него добавляются адреса. В Solana адрес создаёт POST /api/v2/solana/addresses. Оба случая описаны в разделе Управление кошельками.

Какие ошибки может вернуть создание адреса?

Заголовок раздела «Какие ошибки может вернуть создание адреса?»

Запросы к адресам используют стандартную обёртку ответа, в которой при ошибке ok равен false. Отсутствующий или неверный токен даёт статус 401 и {"message":"Unauthenticated."}. Тело, не прошедшее проверку, даёт статус 422 с сообщением Data validation failed и именами полей в errors. Когда лимит адресов вашего тарифа исчерпан, API отвечает статусом 422 и сообщением Your address limit exceeded. Please upgrade your plan. Файл OpenAPI показывает это сообщение для кошельков Bitcoin.

DELETE /api/v2/ethereum/addresses/{address} удаляет адрес и уменьшает число адресов, которые учитываются в вашем тарифе. Удаляйте ненужные адреса, но сначала сохраните приватный ключ, если на адресе ещё могут быть средства.

Ethereum и другие EVM-сети используют 20-байтовые адреса, записанные как 40 hex-символов с префиксом 0x. Как внешний аккаунт выводится из пары ключей, описывает документация Ethereum по аккаунтам. Адреса Tron начинаются с T и состоят из 34 символов. API проверяет этот формат по шаблону T[a-zA-Z0-9]{33}. Основной источник по формату — документация TRON по аккаунтам.