Keypair
A Keypair holds a cryptographic key pair and is the core primitive of a Bittensor wallet. It can be constructed from a mnemonic, seed, URI, or raw key material, and supports signing, verification, and (for ED25519 keypairs) asymmetric message encryption.
For background on what coldkeys and hotkeys are and how they're used in Bittensor, see Wallets, Coldkeys and Hotkeys. This page covers the SDK API for working with them programmatically.
from bittensor_wallet import Keypair, CRYPTO_ED25519, CRYPTO_SR25519
The CRYPTO_ED25519 and CRYPTO_SR25519 constants are also available from the bittensor_wallet.keypair submodule.
Key types: SR25519 and ED25519
Bittensor supports two key types, selected via the crypto_type parameter:
| Constant | Value | Algorithm | Default | Use case |
|---|---|---|---|---|
CRYPTO_SR25519 | 1 | SR25519 (Schnorrkel) | Yes | Coldkeys, hotkeys, all on-chain signing |
CRYPTO_ED25519 | 0 | ED25519 | No | Message encryption/decryption (see Encrypt and decrypt) |
SR25519 is the default throughout the SDK. All existing Bittensor wallets use SR25519.
ED25519 is required for encrypt/decrypt. SR25519 keys cannot be converted to X25519 for sealed-box encryption whereas ED25519 keys can (this conversion is standardized in libsodium).
Creating keypairs
From a URI (development/testing)
URI-based keypairs use well-known derivation paths and are suitable for local development and test networks only.
kp = Keypair.create_from_uri("//Alice") # SR25519 (default)
kp = Keypair.create_from_uri("//Alice", crypto_type=CRYPTO_ED25519) # ED25519
From a mnemonic
mnemonic = Keypair.generate_mnemonic() # 12-word mnemonic
kp = Keypair.create_from_mnemonic(mnemonic) # SR25519 (default)
kp = Keypair.create_from_mnemonic(mnemonic, crypto_type=CRYPTO_ED25519) # ED25519
Generate a 24-word mnemonic:
mnemonic = Keypair.generate_mnemonic(n_words=24)
From a seed
kp = Keypair.create_from_seed(b"\xab\xcd\xef...") # SR25519 (default)
kp = Keypair.create_from_seed(b"\xab\xcd\xef...", crypto_type=CRYPTO_ED25519) # ED25519
From a private key
kp = Keypair.create_from_private_key("0x...", crypto_type=CRYPTO_SR25519)
From an encrypted JSON backup
Substrate-compatible JSON key exports (e.g., from Polkadot.js) can be imported directly:
with open("key-backup.json") as f:
kp = Keypair.create_from_encrypted_json(f.read(), passphrase="your-passphrase")
Public-key only
When you only need to identify or address a participant (e.g., to encrypt a message for them), you can construct a keypair from just an SS58 address. Signing and decryption require the private key.
kp = Keypair(ss58_address="5FHneW46...", crypto_type=0)
Properties
kp.ss58_address # SS58-encoded public address
kp.public_key # raw public key bytes, or None if not loaded
kp.crypto_type # CRYPTO_ED25519 (0) or CRYPTO_SR25519 (1)
kp.ss58_format # SS58 network format (default: 42)
Signing and verification
kp = Keypair.create_from_mnemonic(mnemonic)
signature = kp.sign(b"my message") # returns bytes
valid = kp.verify(b"my message", signature) # returns bool
sign accepts either str or bytes. verify accepts the same. A signature produced by one keypair can only be verified against the matching public key.
Next step: encryption
ED25519 keypairs support asymmetric message encryption. See Encrypt and decrypt.
Example: create a keypair and inspect it
from bittensor_wallet import Keypair, CRYPTO_SR25519, CRYPTO_ED25519
# Generate a fresh mnemonic and create an SR25519 keypair (the Bittensor default)
mnemonic = Keypair.generate_mnemonic()
kp = Keypair.create_from_mnemonic(mnemonic)
print("Mnemonic: ", mnemonic)
print("SS58 address:", kp.ss58_address)
print("Public key: ", kp.public_key.hex())
print("Crypto type: ", kp.crypto_type, "(SR25519)" if kp.crypto_type == CRYPTO_SR25519 else "(ED25519)")
print("SS58 format: ", kp.ss58_format)
# Sign a message and verify it
message = b"hello bittensor"
signature = kp.sign(message)
print("Signature: ", signature.hex())
print("Verified: ", kp.verify(message, signature))
Mnemonic: useless maid combine fancy capable plate program paper trade media erupt leopard
SS58 address: 5GEvXU7qb1nDG3jooFduExugxEzcQcLbyntqs4J7EwVQF8sM
Public key: b8bc090e304e2d815c37a0025154462161e48bae4dc034e25dd339e3149fa07f
Crypto type: 1 (SR25519)
SS58 format: 42
Signature: 2e5628d73b24545603a147b65b5db20679176b149796acf09357b0b2831e395f068aae49ec889407328bfe2a98ef8b6dcfb7d87cbdb3e79b3e00a97afedc3a8a
Verified: True