Registry / ai-ml / bittensor-wallet

bittensor-wallet

JSON →
library4.1.0pypypi✓ verified 85d ago

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.

pip install bittensor-wallet
INSTALL
IMPORT
SIG · BITTENSOR-WALLET
B
bittensor-wallet
ai-mlpythonv4.1.0
Install
1.8s avg
Import
Disk
24MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.8s · import 0.000s · 26MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Wallet
from bittensor_wallet import Wallet

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}")
Debug
Known issues
breakingIn 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.
affects: >=4.0.0
gotchaIt 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.
gotchaBittensor 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.
breakingThere 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.
affects: All versions, especially when downloading from unofficial sources or falling for typosquatting.
Errors
Common errors & fixes
KeyFileError: Keyfile at: /path/to/.bittensor/wallets/some-coldkey/hotkeys/somehotkey does not exist
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
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. '}
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.
Upgrade
Version history
4.1.0latest on PyPI · released May 28, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
22
OpenAI (training)
1
Resources
bittensor-wallet — pip install bittensor-wallet · libregistry