Create Wallet

The Bittensor wallet holds the core ownership. It is the identity technology underlying all the operations in the Bittensor network.

Coldkey and hotkey

A Bittensor wallet consists of a coldkey and a hotkey. The coldkey and hotkey are responsible for different functionalities within the Bittensor ecosystem. These two keys are logically connected via the Bittensor API.

The coldkey is encrypted on your device. It is used to store funds securely and perform high risk operations such as transfers and staking.

The hotkey is by default unencrypted. However, you can encrypt the hotkey. The hotkey is used for less secure operations such as signing messages into the network, running subnet miners, and validating the network. The hotkey is generated from the coldkey.

Coldkey and hotkey are pairings of separate private and public keys

Each key is a pairing of two seperate EdDSA cryptographic keypairs. Hence, a coldkey is a pairing of a private key and a public key. Similarly, a hotkey is a pairing of another set of private key and public keys. In this sense, a coldkey or a hotkey is each analogous to an account on a blockchain, where the account is defined by a pair of a public and a private key.

Ways of creating wallet

You can:

• Create a wallet locally on your machine. This requires that you install Bittensor on your machine.
• Create an external wallet, either through the Bittensor website or by using a tool like subkey. An external wallet created in this way will allow you to use TAO without installing Bittensor.

Creating a local wallet

After you have installed Bittensor, you can create a wallet locally on your machine in the following two ways:

• Using btcli.
• Using Python.

Using btcli

Using btcli to create a local wallet is a two step process:

• First create a coldkey.
• Provide this coldkey as a parameter to generate a hotkey.

Step 1: Generate a coldkey

Run the following command on your terminal by giving a name to your wallet, replacing the my_coldkey.

btcli wallet new_coldkey --wallet.name <my_coldkey>

For example,

btcli wallet new_coldkey --wallet.name test-coldkey

You will see the following terminal output. The mnemonic is hidden for security reasons.

IMPORTANT: Store this mnemonic in a secure (preferably offline place), as anyone who has possesion of this mnemonic can use it to regenerate the key and access your tokens.
The mnemonic to the new coldkey is:
**** *** **** **** ***** **** *** **** **** **** ***** *****
You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
btcli regen_coldkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** *****

Regenerating a key

Make a note of the above command option regen_coldkey showing how to regenerate your coldkey in case you lose it.

Step 2: Generate a hotkey

Next, use the below command to generate the hotkey. Replace <my_coldkey> with the coldkey generated above, and <my_first_hotkey> with a name for your hotkey.

btcli wallet new_hotkey --wallet.name <my_coldkey> --wallet.hotkey <my_first_hotkey>

For example,

btcli wallet new_hotkey --wallet.name test-coldkey --wallet.hotkey my_first_hotkey

You will see the terminal log like below. The mnemonic is hidden for security reasons.

IMPORTANT: Store this mnemonic in a secure (preferably offline place), as anyone who has possesion of this mnemonic can use it to regenerate the key and access your tokens.
The mnemonic to the new hotkey is:
**** *** **** **** ***** **** *** **** **** **** ***** *****
You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
btcli regen_hotkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** *****

Regenerating a key

Make a note of the above command option regen_hotkey showing how to regenerate your hotkey in case you lose it.

Encrypting the hotkey

By default, the hotkey is not encrypted on the device whereas the coldkey is encrypted. To encrypt your hotkey, run this command:

btcli new_hotkey --use_password

Using Python

Copy and paste the following three lines into your Python interpreter. You can replace the string values for name (my_coldkey) and hotkey (my_first_hotkey) with your own.

import bittensor as bt
wallet = bt.wallet(name = 'my_coldkey', hotkey = 'my_first_hotkey' )
wallet.create_if_non_existent()

You will see a terminal output like this for an example wallet with name as tst1_coldkey and hotkey as tst1_hotkey. The mnemonic is hidden for security reasons.

>>> import bittensor as bt
>>> wallet = bt.wallet(name = 'tst1_coldkey', hotkey = 'tst1_hotkey')
>>> wallet.create_if_non_existent()

IMPORTANT: Store this mnemonic in a secure (preferable offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens.

The mnemonic to the new coldkey is:

**** **** **** **** **** **** **** **** **** **** **** ****

You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
btcli w regen_coldkey --mnemonic **** **** **** **** **** **** **** **** **** **** **** ****

Specify password for key encryption:
Password not strong enough. Try increasing the length of the password or the password complexity
Specify password for key encryption:
Retype your password:

IMPORTANT: Store this mnemonic in a secure (preferable offline place), as anyone who has possession of this mnemonic can use it to regenerate the key and access your tokens.

The mnemonic to the new hotkey is:

**** **** **** **** **** **** **** **** **** **** **** ****

You can use the mnemonic to recreate the key in case it gets lost. The command to use to regenerate the key using this mnemonic is:
btcli w regen_hotkey --mnemonic **** **** **** **** **** **** **** **** **** **** **** ****

wallet(tst1_coldkey, tst1_hotkey, ~/.bittensor/wallets/)
>>>

Location of the created wallet

Generated wallets are stored locally on your machine under ~/.bittensor/wallets. Use the below command:

tree ~/.bittensor/

To see the following the directory structure for the above-created Bittensor wallet.

tree ~/.bittensor/
/Users/docwriter/.bittensor/    # The Bittensor root directory.
└── wallets # The folder containing all Bittensor wallets.
    └── tst1_coldkey # The name of the wallet.
        ├── coldkey # The password-encrypted coldkey.
        ├── coldkeypub.txt # The unencrypted public address of the coldkey.
        └── hotkeys # The folder containing all this coldkey's hotkeys.
            └── tst1_hotkey # The unencrypted hotkey information.

List all the local wallets

You can list all the local wallets stored in Bittensor's root directly with:

btcli wallet list

You will see a terminal output like this:

Wallets
└─
    tst1_coldkey (<ss58_string>)
       └── tst1_hotkey (<ss58_string>)

The above shown <ss58_string> are SS58 encoded. These are compact representations of the public keys corresponding to the wallet's coldkey and hotkey.

Use the public keys as destinations for TAO

Use the above shown public keys as wallet addresses, i.e., as destinations for TAO transfers. For example, when using a command: btcli wallet transfer).

Store your mnemonics safely

If someone has your mnemonic, they own your TAO

If you lose the password to your wallet, or if you have lost the access to the machine where the wallet is stored, you can regenerate the coldkey using the mnemonic you saved during wallet creation steps above. You can not retrieve the wallet with the password alone. Remember that if someone has your mnemonic, they own your TAO.

As a reminder, if you need to regenerate your wallets, you can use the btcli with your mnemonic, as shown below:

btcli wallet regen_coldkey --mnemonic **** *** **** **** ***** **** *** **** **** **** ***** *****

Creating an external wallet

To create a wallet without installing Bittensor, use the wallet on Bittensor. Follow these steps:

1. On Bittensor website click the 0.00 on the top right corner.
2. Select Create to create a new wallet or Import to import your mnemonic from an existing wallet.
   • Use the Access option if you have already created a wallet using the website and have not chosen to Forget it. After you have accessed your account, you can send, receive, or stake your TAO.

Update wallet

It is important that you update any legacy Bittensor wallets to the new NaCL format for security. You may accomplish this with the btcli using the wallet update subcommands.

See the below example command and the terminal output:

btcli wallet update
>> Do you want to update all legacy wallets? [y/n]: n
>> =====  wallet(tst1_coldkey, default, ~/.bittensor/wallets/)  =====
>> ✅ Keyfile is updated. 
>> 🔑 Keyfile (NaCl encrypted, ~/.bittensor/wallets/tst1_coldkey/coldkey)>