Tron Password-Protected Wallets via API

A password-protected Tron wallet is an address that you create through the Chaingateway API with a password parameter. The private key is encrypted with that password and is not returned in the response. To send from the address, you pass the password instead of the key. Chaingateway does not store the password, so a lost password cannot be recovered.

What changed with password-protected wallets?

Until 18 February 2025, Tron addresses created through the API returned the private key in the response. That suits temporary addresses, but it leaves the key in your logs, your database and every system that touches the response. Password-protected wallets are the alternative. The wallet management documentation calls them the recommended method and describes the key as encrypted with your password and with Chaingateway’s own encryption mechanisms. The unsecure variant still exists: if you omit password, you get the private key directly and you must store it yourself.

How do you create a password-protected Tron wallet?

Send a POST request to /api/v2/tron/addresses with a password:

curl --request POST \
  --url https://app.chaingateway.io/api/v2/tron/addresses \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "password": "your_secure_password" }'

The response contains the new address in data. It does not contain the private key. Use a long random password from a password manager. The OWASP authentication cheat sheet calls passwords shorter than 15 characters weak when no second factor protects them, and a wallet password has none. Keep it in your secrets store, because the same password is needed for every later request on this address.

How do you send from a password-protected wallet?

Pass the password field instead of privatekey. A TRX transfer needs from, to, amount and password:

curl --request POST \
  --url https://app.chaingateway.io/api/v2/tron/transactions \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "from": "TSenderAddress",
  "to": "TDestinationAddress",
  "amount": 100,
  "password": "your_secure_password"
}'

The same password field works on POST /api/v2/tron/transactions/trc20, .../trc721 and .../trc10. TRC20 transfers also need a contractaddress. A TRC20 transfer from an address without TRX or staked Energy fails with status 422, as the TronFuel and Paymaster tutorial explains. The Chaingateway Paymaster is deprecated, and TronFuel is the recommended way to cover the fee.

How do you export the key, change the password or import a key?

Three more endpoints complete the wallet lifecycle. Each takes the address in the path:

Import is the way to move an existing, unsecured address under password protection. After the import, send from the address with the password and stop passing the key. Delete the key from your own storage once you have verified a test transfer on the testnet. Exporting is the escape hatch: it lets you leave the service with your key, and it needs the password.

What are the limits of password protection?

A Tron account is controlled by its private key, as the Tron documentation puts it, so the key is what you protect. The password protects the key at rest. It does not protect a compromised server that already knows the password, and it does not help with a lost password. Chaingateway cannot restore a wallet whose password is lost, according to the documentation. Back up the password and test the export once before you move real funds. Keep large balances in a wallet whose key you hold yourself, and use the API wallets as hot wallets with limited balances.

Before you move real funds, run this checklist:

1. Create a wallet on the testnet and send a small transfer with the password.
2. Export the private key once and confirm that it matches the address.
3. Change the password and confirm that a send with the old password fails and one with the new password works.
4. Store the password in your secrets manager and remove it from shell history and logs.

Use the testnet first. Add the header X-Network: testnet to every request above, create a wallet on Nile, and run through create, send, export and password change. The supported networks page lists the test networks, and the Tron networks documentation explains Nile and Shasta.

Which questions come up most often?

Does a password wallet work on other chains?

Yes. The wallet management documentation describes the password parameter for /api/v2/{blockchain}/addresses, and the OpenAPI file lists address endpoints with the same pattern for Ethereum, BNB Smart Chain, Polygon and Arbitrum.

Can Chaingateway reset a lost password?

No. The documentation states that Chaingateway cannot restore the private key of a wallet whose password is lost. Export the key once and store it in your own vault.

Do webhooks need the wallet password?

No. A webhook watches an address and needs only the address, a URL and a filter. The password is needed to sign transactions, to export the key and to change the password.

Can I mix password-protected and unsecure wallets?

Yes. Each address is created either with or without a password. In a request, send either password or privatekey, as the OpenAPI file describes for the transaction endpoints.