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

Управление кошельками и хранение ключей

Кошелёк в Chaingateway — это адрес, приватный ключ которого либо хранится в зашифрованном виде под выбранным вами паролем, либо возвращается вам один раз и остаётся только у вас. Chaingateway не хранит ваш пароль и поэтому не может восстановить потерянный ключ. Режим выбирается при создании адреса: отправьте password для защищённого режима или не указывайте его для незащищённого.

Кошелёк, защищённый паролем: адрес создаётся с паролем, Chaingateway хранит зашифрованный ключ, а последующие транзакции подписываются паролем вместо приватного ключа POST /api/v2/{chain}/addresses тело: password Ключ хранится в зашифрованном виде Chaingateway не хранит копию вашего пароля POST /api/v2/{chain}/transactions тело: from, to, amount, password Транзакция подписана и отправлена ответ: txid
В этом режиме приватный ключ не появляется ни в запросе, ни в ответе.

Чем отличаются кошельки с паролем и без пароля?

Заголовок раздела «Чем отличаются кошельки с паролем и без пароля?»

В защищённом режиме Chaingateway шифрует приватный ключ вашим паролем и собственной цепочкой шифрования. В незащищённом режиме ключ возвращается в ответе на создание, и вы передаёте его в каждой транзакции. Таблица сравнивает оба режима.

Защищённый паролемНезащищённый
Запрос на созданиетело содержит passwordбез password
Приватный ключ в ответенетда, один раз
Где хранится ключв зашифрованном виде в Chaingatewayтолько у вас
Подпись транзакциипередайте passwordпередайте privatekey
Потерянный пароль или ключвосстановить нельзявосстановить нельзя
Для чего использоватьдолгоживущие адреса и адреса для депозитоввременные и одноразовые адреса

::: danger Храните свой пароль в безопасности Мы никогда не храним пароли, поэтому, если вы потеряете пароль, мы не сможем восстановить приватный ключ вашего кошелька. Храните пароль в менеджере секретов, а не в репозитории. :::

Отправьте запрос POST на /api/v2/{blockchain}/addresses с password в теле JSON. Замените {blockchain} на ethereum, bsc, polygon, arbitrum или tron. Пример создаёт адрес Ethereum.

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

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

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

Чтобы отправить средства с адреса, передайте тот же пароль в запросе транзакции. Приватный ключ в запрос не входит. Неверный пароль возвращает статус 401 с сообщением Wrong password provided.

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

Как сменить пароль, экспортировать ключ или импортировать существующий ключ?

Заголовок раздела «Как сменить пароль, экспортировать ключ или импортировать существующий ключ?»

Каждое из этих действий — один эндпоинт для каждого блокчейна. Ниже в путях указан ethereum, и те же пути есть для bsc, polygon и arbitrum. Tron предлагает те же операции с адресами, кроме списка адресов.

ДействиеЗапросТело
Сменить парольPOST /api/v2/ethereum/addresses/{address}old_password, new_password (оба обязательны)
Экспортировать приватный ключPOST /api/v2/ethereum/addresses/export/{address}password
Импортировать существующий ключPOST /api/v2/ethereum/addresses/importaddress, privatekey, password (все обязательны)
Получить список ваших адресовGET /api/v2/ethereum/addressesнет
Удалить адресDELETE /api/v2/ethereum/addresses/{address}нет

Смена пароля выполняется запросом POST, а не PUT или PATCH. Импорт ключа превращает существующий адрес в адрес, защищённый паролем. Так защищённый режим применяют к адресу, созданному в другом месте или в незащищённом режиме. Ответ на экспорт возвращает ключ как data.private_key. Удаление адреса уменьшает число адресов, которые учитываются в вашем плане.

Когда использовать незащищённый кошелёк?

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

Используйте незащищённый кошелёк только для временных или одноразовых адресов. Если не указать пароль, ответ на создание содержит приватный ключ, и вы должны хранить его сами. Тот, кто получит ключ, управляет всеми средствами на адресе, а ключ, который вы отправляете с каждой транзакцией, попадает в каждый ваш запрос. Запрос ниже создаёт адрес Tron без пароля.

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

Ответ содержит privateKey, publicKey, hexAddress и address. Сохраните ключ в первую очередь, потому что он понадобится для каждой следующей транзакции. Чтобы отправить средства с такого адреса, передайте в теле транзакции privatekey вместо password. Переводы TRX и TRC20 в Tron описаны в руководствах Создание транзакций и Создание токен-транзакций.

::: danger Использовать только для непостоянных кошельков Поскольку приватный ключ включён в ответ, вы сами отвечаете за его хранение и защиту. Если кто-то получит доступ к вашему приватному ключу, он сможет распоряжаться всеми средствами в кошельке. :::

Bitcoin и Solana используют эндпоинт addresses не так, как сети EVM и Tron.

В Bitcoin кошелёк — это контейнер для адресов. Запрос POST /api/v2/bitcoin/wallets с password создаёт кошелёк и возвращает его идентификатор как data.bitcoinwallet. Затем POST /api/v2/bitcoin/wallets/{wallet}/addresses добавляет в него адреса, а POST /api/v2/bitcoin/wallets/{wallet}/addresses/{address}/export экспортирует ключ одного адреса с паролем кошелька. Транзакция Bitcoin указывает кошелёк в walletname и передаёт пароль кошелька password. Когда лимит адресов по плану исчерпан, API отвечает статусом 422 и сообщением Your address limit exceeded. Please upgrade your plan.

В Solana POST /api/v2/solana/addresses создаёт адрес, а каждый запрос транзакции содержит privatekey отправителя. В файле OpenAPI для транзакций Solana нет режима с паролем, поэтому работа с ключом остаётся на вашей стороне.

Относитесь к API-токену, паролям кошельков и приватным ключам как к трём отдельным секретам. Не храните их в одном месте и не записывайте в лог тела запросов, которые их содержат. OWASP Key Management Cheat Sheet охватывает жизненный цикл ключа от генерации до хранения и вывода из обращения. Сам формат зашифрованного ключа Ethereum описывает в определении Web3 secret storage: там показано, как пароль шифрует ключ. Руководство по кошелькам Bitcoin описывает, как кошельки хранят и выводят ключи.