Wallet Management and Key Storage

A wallet in Chaingateway is an address whose private key is either stored encrypted behind a password you choose, or returned to you once and kept only on your side. Chaingateway does not store your password, so it cannot restore a lost key. You pick the mode when you create the address: send a password for the protected mode, or leave it out for the unsecured one.

The private key never appears in a request or response in this mode.

What is the difference between password-protected and unsecured wallets?

In the protected mode Chaingateway encrypts the private key with your password and its own encryption chain. In the unsecured mode the key is returned in the creation response and you send it with every transaction. The table compares the two.

	Password-protected	Unsecured
Create request	body contains password	no password
Private key in the response	no	yes, once
Where the key lives	encrypted at Chaingateway	only with you
Signing a transaction	send password	send privatekey
Lost password or key	cannot be restored	cannot be restored
Use for	long-lived and deposit addresses	temporary and single-use addresses

::: danger Store your password securely We never store passwords, so if you lose the password, we cannot restore your wallet’s private key. Keep the password in a secrets manager, not in the repository. :::

How do I create a password-protected wallet?

Send a POST request to /api/v2/{blockchain}/addresses with a password in the JSON body. Replace {blockchain} with ethereum, bsc, polygon, arbitrum or tron. The example creates an Ethereum address.

Curl

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

<?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;

JavaScript

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));

Python

import requests
headers = {
    '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())

The response carries the new address. The OpenAPI file spells the key adderess:

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

To send from the address, pass the same password in the transaction request. The private key is not part of the request. A wrong password returns status 401 with the message 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"
}'

How do I change the password, export the key or import an existing key?

Each of these actions is one endpoint per chain. The paths below use ethereum, and the same paths exist for bsc, polygon and arbitrum. Tron offers the same address operations, except for listing addresses.

Action	Request	Body
Change the password	POST /api/v2/ethereum/addresses/{address}	old_password, new_password (both required)
Export the private key	POST /api/v2/ethereum/addresses/export/{address}	password
Import an existing key	POST /api/v2/ethereum/addresses/import	address, privatekey, password (all required)
List your addresses	GET /api/v2/ethereum/addresses	none
Delete an address	DELETE /api/v2/ethereum/addresses/{address}	none

The password change is a POST, not a PUT or PATCH. Importing a key turns an existing address into a password-protected one, which is the way to use the protected mode for an address that was created elsewhere or in the unsecured mode. The export response returns the key as data.private_key. Deleting an address lowers the number of addresses counted against your plan.

When should I use an unsecured wallet?

Use an unsecured wallet only for temporary or single-use addresses. If you omit the password, the creation response contains the private key and you must keep it yourself. Anyone who obtains the key controls all funds on the address, and a key that you send with every transaction appears in every request you make. The request below creates a Tron address without a password.

curl --request POST \
  --url https://app.chaingateway.io/api/v2/tron/addresses \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json'

The response contains privateKey, publicKey, hexAddress and address. Store the key before you do anything else, because you need it for every later transaction. To send from such an address, pass privatekey instead of password in the transaction body. TRX and TRC20 transfers on Tron are described in Create Transactions and Create Token Transactions.

::: danger Only use for non-permanent wallets Since the private key is included in the response, it is your responsibility to store and protect it. If someone gains access to your private key, they can control all funds in the wallet. :::

How do wallets work on Bitcoin and Solana?

Bitcoin and Solana do not use the addresses endpoint in the same way as the EVM chains and Tron.

On Bitcoin a wallet is a container for addresses. POST /api/v2/bitcoin/wallets with a password creates the wallet and returns its identifier as data.bitcoinwallet. POST /api/v2/bitcoin/wallets/{wallet}/addresses then adds addresses to it, and POST /api/v2/bitcoin/wallets/{wallet}/addresses/{address}/export exports the key of one address with the wallet password. A Bitcoin transaction names the wallet in walletname and sends the wallet password. When the plan’s address limit is reached, the API answers with status 422 and the message Your address limit exceeded. Please upgrade your plan.

On Solana POST /api/v2/solana/addresses creates an address, and every transaction request carries the sender’s privatekey. There is no password mode for Solana transactions in the OpenAPI file, so the key handling stays on your side.

How should I store keys and passwords?

Treat the API token, wallet passwords and private keys as three separate secrets. Do not keep them in the same place, and do not log request bodies that contain them. The OWASP Key Management Cheat Sheet covers the key lifecycle from generation to storage and retirement. For the encrypted key format itself, Ethereum documents the Web3 secret storage definition, which describes how a password encrypts a key. The Bitcoin wallet guide describes how wallets store and derive keys.