Bittensor Wallet

Common errors

• KeyFileError: Keyfile at: /path/to/.bittensor/wallets/some-coldkey/hotkeys/somehotkey does not exist

  cause The specified coldkey or hotkey file does not exist at the expected path, likely because it hasn't been created or was moved/deleted.
  fix Ensure the wallet and hotkey are created using `wallet.create()` before attempting to access them, or provide the correct path/name. You can also regenerate keys from a mnemonic if you have it.

• bittensor.errors.KeyFileError: Provided password does not match with the password stored in keyfile

  cause An incorrect password was supplied when attempting to decrypt an encrypted coldkey or hotkey file.
  fix Verify the password used for wallet creation or decryption. If forgotten and no mnemonic backup exists, recovery may be impossible.

• {'code': 1014, 'message': 'Priority is too low: (18446744073709551615 vs 18446744073709551615)', 'data': 'The transaction has too low priority to replace another transaction already in the pool. '}

  cause This error occurs when attempting to submit transactions too rapidly, resulting in the blockchain rejecting a duplicate or low-priority transaction already in the transaction pool.
  fix Wait for a few minutes before resubmitting the transaction, or ensure your application logic accounts for transaction finalization delays.

Warnings

• breaking In version 4.0.0, the `when_created` field for JSON wallet file imports became optional. If you have scripts or tools that relied on this field always being present or strictly required, they might need adjustment.
  Fix: Review any code that imports Bittensor wallet JSON files and ensure it handles the `when_created` field as optional.
• gotcha It is critical to securely store your wallet's mnemonic (seed phrase) offline. Anyone with access to this phrase can regenerate your keys and gain full control over your funds. The library often prints it to the console upon creation, but it is *not* stored by the library in an easily retrievable form once created.
• gotcha Bittensor utilizes a dual-key structure: a 'coldkey' for securing TAO tokens and high-security operations (like staking and transfers), and a 'hotkey' for operational tasks such as mining and validating. These keys serve different purposes and should be managed with appropriate security considerations; the coldkey should ideally remain in cold storage.
• breaking There have been reports of malicious packages masquerading as `bittensor-wallet` (e.g., version 4.0.2 in a security report, though 4.0.1 is the latest official on PyPI). Always verify the package source and version to avoid supply chain attacks that could exfiltrate wallet keys.
  Fix: Always install `bittensor-wallet` directly from PyPI using `pip install bittensor-wallet` and verify the installed version against official announcements. Do not use unofficial distribution channels.

Install

• pip install bittensor-wallet Install latest version

Imports

• Wallet

  from bittensor_wallet import Wallet

Quickstart

This quickstart demonstrates how to initialize the `Wallet` object and create (or load) a coldkey and hotkey pair. The mnemonic (seed phrase) is crucial for recovery and is printed to the console upon creation, requiring secure offline storage. For production use, consider using passwords and robust key management strategies.

import os
from bittensor_wallet import Wallet

# Create a new wallet with a specific name and hotkey
# This will create directories and key files at ~/.bittensor/wallets/<wallet_name>/hotkeys/<hotkey_name>
# Replace with your desired wallet and hotkey names
wallet_name = os.environ.get('BT_WALLET_NAME', 'my_coldkey_wallet')
hotkey_name = os.environ.get('BT_HOTKEY_NAME', 'my_hotkey')

my_wallet = Wallet(name=wallet_name, hotkey=hotkey_name)

try:
    # Attempt to create the wallet. If it already exists, it will load it.
    my_wallet.create(coldkey_use_password=False, hotkey_use_password=False, overwrite=False)
    print(f"Wallet '{wallet_name}' with hotkey '{hotkey_name}' created or loaded successfully.")
    print(f"Coldkey address: {my_wallet.coldkeypub.ss58_address}")
    print(f"Hotkey address: {my_wallet.hotkey.ss58_address}")
    # The mnemonic for a newly created wallet is printed to console upon creation
    # and should be stored securely offline.

except Exception as e:
    print(f"Error creating or loading wallet: {e}")

# Example of retrieving keypairs
coldkey_keypair = my_wallet.coldkey
hotkey_keypair = my_wallet.hotkey

print(f"\nAccessed coldkey public address: {coldkey_keypair.ss58_address}")
print(f"Accessed hotkey public address: {hotkey_keypair.ss58_address}")