{"id":7046,"library":"bittensor-wallet","title":"Bittensor Wallet","description":"Bittensor-wallet is a Python SDK that provides an interface for managing cryptographic key-pairs (coldkeys and hotkeys) necessary to interact with the Bittensor decentralized machine learning network. It allows users to prove identity, sign transactions, access TAO tokens, and manage stake in subnets. The library is currently at version 4.0.1 and has a frequent release cadence, with recent updates supporting Python 3.14.","status":"active","version":"4.0.1","language":"en","source_language":"en","source_url":"https://github.com/opentensor/btwallet","tags":["cryptocurrency","blockchain","wallet","bittensor","ai","machine-learning"],"install":[{"cmd":"pip install bittensor-wallet","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Wallet","correct":"from bittensor_wallet import Wallet"}],"quickstart":{"code":"import os\nfrom bittensor_wallet import Wallet\n\n# Create a new wallet with a specific name and hotkey\n# This will create directories and key files at ~/.bittensor/wallets/<wallet_name>/hotkeys/<hotkey_name>\n# Replace with your desired wallet and hotkey names\nwallet_name = os.environ.get('BT_WALLET_NAME', 'my_coldkey_wallet')\nhotkey_name = os.environ.get('BT_HOTKEY_NAME', 'my_hotkey')\n\nmy_wallet = Wallet(name=wallet_name, hotkey=hotkey_name)\n\ntry:\n    # Attempt to create the wallet. If it already exists, it will load it.\n    my_wallet.create(coldkey_use_password=False, hotkey_use_password=False, overwrite=False)\n    print(f\"Wallet '{wallet_name}' with hotkey '{hotkey_name}' created or loaded successfully.\")\n    print(f\"Coldkey address: {my_wallet.coldkeypub.ss58_address}\")\n    print(f\"Hotkey address: {my_wallet.hotkey.ss58_address}\")\n    # The mnemonic for a newly created wallet is printed to console upon creation\n    # and should be stored securely offline.\n\nexcept Exception as e:\n    print(f\"Error creating or loading wallet: {e}\")\n\n# Example of retrieving keypairs\ncoldkey_keypair = my_wallet.coldkey\nhotkey_keypair = my_wallet.hotkey\n\nprint(f\"\\nAccessed coldkey public address: {coldkey_keypair.ss58_address}\")\nprint(f\"Accessed hotkey public address: {hotkey_keypair.ss58_address}\")","lang":"python","description":"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."},"warnings":[{"fix":"Review any code that imports Bittensor wallet JSON files and ensure it handles the `when_created` field as optional.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"message":"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.","severity":"gotcha"},{"message":"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.","severity":"gotcha"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially when downloading from unofficial sources or falling for typosquatting."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"KeyFileError: Keyfile at: /path/to/.bittensor/wallets/some-coldkey/hotkeys/somehotkey does not exist"},{"fix":"Verify the password used for wallet creation or decryption. If forgotten and no mnemonic backup exists, recovery may be impossible.","cause":"An incorrect password was supplied when attempting to decrypt an encrypted coldkey or hotkey file.","error":"bittensor.errors.KeyFileError: Provided password does not match with the password stored in keyfile"},{"fix":"Wait for a few minutes before resubmitting the transaction, or ensure your application logic accounts for transaction finalization delays.","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.","error":"{'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. '}"}]}