Управление кошельками и хранение ключей
Кошелёк в Chaingateway — это адрес, приватный ключ которого либо хранится в зашифрованном виде под выбранным вами паролем, либо возвращается вам один раз и остаётся только у вас. Chaingateway не хранит ваш пароль и поэтому не может восстановить потерянный ключ. Режим выбирается при создании адреса: отправьте password для защищённого режима или не указывайте его для незащищённого.
Чем отличаются кошельки с паролем и без пароля?
Заголовок раздела «Чем отличаются кошельки с паролем и без пароля?»В защищённом режиме 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"}'<?php$ch = curl_init();curl_setopt($ch, CURLOPT_URL, 'https://app.chaingateway.io/api/v2/ethereum/addresses');curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);curl_setopt($ch, CURLOPT_POST, 1);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["password" => "choose-a-strong-password"]));curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer YOUR_API_TOKEN', 'Content-Type: application/json']);$response = curl_exec($ch);curl_close($ch);echo $response;fetch('https://app.chaingateway.io/api/v2/ethereum/addresses', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ password: 'choose-a-strong-password' })}).then(response => response.json()).then(data => console.log(data));import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json'}data = {"password": "choose-a-strong-password"}response = requests.post('https://app.chaingateway.io/api/v2/ethereum/addresses', headers=headers, json=data)print(response.json())Ответ содержит новый адрес. В файле 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/import | address, 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?
Заголовок раздела «Как работают кошельки в Bitcoin и Solana?»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 описывает, как кошельки хранят и выводят ключи.