SUBMIT A PRSUBMIT AN ISSUElast edit: Mar 23, 2026

Coldkey and Hotkey Workstation Security

danger

Neither the Opentensor Foundation nor Latent Holdings has the technical or legal ability to intervene if your tokens are lost due to theft, scam, or accidental loss of your keys. If you believe you have been the victim of a crime, contact your local law enforcement.

See also:

• Intro to Wallets, Coldkeys and Hotkeys in Bittensor
• Bittensor CLI: Permissions Guide
• Handle your Seed Phrase/Mnemonic Securely

Security model

Bittensor operations fall into three security tiers based on which key is required:

Tier	Key required	Recommended environment
Permissionless	Public key only	Any device
Operational	Scoped proxy coldkey	Internet-connected workstation
Custody	Primary coldkey	Hardware wallet only

The core principle: your primary coldkey should never be loaded onto a machine running btcli or the Bittensor SDK. Neither tool has hardware wallet integration — both require the key present on disk to sign transactions. The proxy system exists to bridge this gap, but it is not a substitute for hardware wallet custody. A proxy coldkey on a hot machine is still a coldkey on a hot machine; the safety comes from limiting its scope, requiring a delay, and revoking it when not in active use.

Permissionless workstation

You can check public information about Bittensor wallets (including your TAO and alpha stake balances), subnets, validators, and more without using a private key. Transaction information is public on the Bittensor blockchain, with parties identified by their coldkey public key.

Whenever possible, do read-only work on a device that does not have any private key loaded.

To use btcli as a permissionless workstation, import only your coldkey public key:

btcli w regen-coldkeypub --ss58 <YOUR COLDKEY PUBLIC KEY>

Then view balances, stakes, and blockchain state:

btcli view dashboard

Websites that offer permissionless browsing of Bittensor data:

• bittensor.com/scan
• TAO.app (without loading a private key)

Cold custody: hardware wallets

Your primary coldkey is the ultimate authority over your Bittensor wallet. It controls all TAO and alpha balances. This key should live in a hardware wallet and never be exported to any machine.

Hardware wallets keep the private key inside the device. Signing happens on the device itself; the key is never exposed to the host machine's operating system.

Ledger

Ledger hardware wallets, used with a compatible wallet app, support TAO transfers, staking, unstaking, and proxy creation. Compatible wallet apps include Crucible, Talisman, Nova Wallet, and SubWallet.

See Using Ledger Hardware Wallet.

Bittensor mobile wallet

The Bittensor mobile wallet app (bittensor.com/wallet) supports TAO management and alpha staking. If using it, dedicate a device to this purpose with no other apps installed to minimize the risk of key exposure.

Polkadot Vault

Polkadot Vault (formerly Parity Signer) turns a dedicated offline smartphone into a cold-signing device. The private key is generated on the device, which is then kept in airplane mode permanently. Transactions pass between the hot and cold device exclusively via QR code — the key never leaves the air-gapped phone.

Unlike Ledger wallet apps, which expose a limited set of supported operations, Polkadot Vault loads the full Bittensor chain metadata and can therefore decode and sign any Subtensor extrinsic — including proxy creation, hotkey registration, subnet operations, and governance.

Setup:

1. Install Polkadot Vault on a dedicated smartphone.
2. Enable airplane mode and disable all wireless communications permanently.
3. Generate your coldkey on the device.
4. Load Bittensor chain metadata via QR code from a trusted portal:
   • metadata.opentensor.ai (maintained by OTF)
   • metadata.novasama.io (maintained by Nova Wallet)
   • Metadata must be re-loaded after each Bittensor runtime upgrade.
5. Use polkadot.js/apps connected to Subtensor to construct transactions, signing via QR code on the Vault device.

Proxy architecture: bridging cold custody to hot operations

The Bittensor SDK and btcli require a coldkey on the machine for most financial operations. The solution is to use your hardware wallet to create proxy coldkeys — separate coldkeys with scoped, limited permissions that act on behalf of your primary coldkey.

This keeps your primary coldkey in cold storage while allowing btcli and SDK use with a proxy coldkey whose blast radius is constrained by type and delay.

Recommended proxy configuration

For automated or routine operations, configure proxies with:

• Least-privileged proxy type: use only the permission level the operation requires:

  • Staking — stake and unstake only, no transfers
  • SmallTransfer — TAO and alpha transfers below 0.5 TAO/alpha per transaction only
  • Transfer — unlimited transfers; treat with nearly the same care as the primary coldkey
  • Registration — hotkey registration only
  • Owner — subnet owner operations only

• Non-zero delay: a delayed proxy must announce its intent on-chain and wait a specified number of blocks before the call executes. During this window, the primary coldkey holder can reject and veto the transaction from their hardware wallet.

A SmallTransfer proxy with a meaningful delay is a robustly safe configuration for automated operations: a compromised proxy key can only attempt small transactions, announced on-chain in advance, with a cancellation window.

Transfer proxy type

A proxy with Transfer permissions and zero delay provides little protection over direct coldkey access. It can drain your entire TAO balance in a single transaction. If transfer capability is needed, prefer SmallTransfer with a delay. Treat any Transfer-capable proxy coldkey with the same security rigor as a primary coldkey.

Coldkey mobile device

You can use the Bittensor mobile wallet app: bittensor.com/wallet. If so, it is recommended to use a dedicated mobile phone for the purpose that you do not install other software on, to minimize the risk of the coldkey or seed phrase being leaked.

This option is suitable for alpha staking and TAO balance management.

Coldkey laptop

This is required for using btcli or the Bittensor Python SDK for advanced use cases such as hotkey management and scripting.

Operational Hygiene

Even on a minimal or air-gapped machine, follow standard security hygiene:

• Always Handle your Seed Phrase/Mnemonic Securely.
• Use strong passwords for your encryption passphrases.
• Do not reuse credentials across different environments.
• Keep your workstation’s operating system and critical software updated with the latest security patches.
• Disable all network services (SSH, RDP, or anything else) that are not strictly needed.
• Maintain logs of important oprations.

Rotating your coldkey

If you suspect your coldkey may have been leaked, you can request to swap it out of your wallet, using an extrinsic blockchain transaction. This operation has a 5 day waiting period, during which your coldkey will be locked. The cost of this coldkey swap transaction is 0.1 TAO.

See Rotate/Swap your Coldkey

Effectively, this transfers all of your TAO and alpha stake balances, as well as your sudo control over any subnets you have created:

• For each hotkey owned by the old coldkey, its stake and block transfer to the new coldkey.
• For each subnet, if the old coldkey is the owner, ownership transfers to the new coldkey.
• For each hotkey staking for the old coldkey, transfer its stake to the new coldkey.
• Total stake transfers from the old coldkey to the new coldkey.
• The list of staking hotkeys transfers from the old coldkey to the new coldkey.
• For each hotkey owned by the old coldkey, ownership transfers to the new coldkey. The list of owned hotkeys for both old and new coldkeys updates.
• Any remaining balances transfer from the old coldkey to the new coldkey.

Proxy wallets for coldkey protection

Proxies are one of the most effective tools for protecting your coldkey while maintaining operational flexibility. By setting up proxy relationships, you can perform routine operations like staking without exposing your coldkey to any online environment.

Key benefits:

• Least-privilege permissions: Configure proxies with only the specific permissions needed (e.g., Staking type for stake management only)
• Time-delayed operations: Set a non-zero delay so you have time to reject unauthorized transactions if a proxy is compromised
• Coldkey stays in cold storage: Your high-value coldkey never needs to leave secure offline storage for day-to-day operations

Zero-delay proxies

A proxy with delay: 0 executes immediately with no veto window. Always set a non-zero delay for proxies that control financial operations.

Set up proxies from your hardware wallet so the primary coldkey is never involved in day-to-day operations. See:

• Proxies: Overview
• Working with Proxies
• Staking with a Proxy

Using btcli and the SDK: proxy coldkeys

btcli and the Bittensor SDK run on internet-connected machines. Any coldkey loaded onto such a machine is exposed to network risk regardless of how the machine is configured. The way to use these tools safely is not to harden the machine — it is to never load your primary coldkey onto it in the first place.

Instead, use a scoped proxy coldkey: one with the minimum permissions needed for the specific operation, a non-zero delay, and a short lifespan.

Proxy lifecycle

The safest pattern for any btcli or SDK operation requiring a coldkey:

1. Create a proxy with the narrowest type and a delay sufficient to let you detect and cancel misuse.
2. Use it for the specific operation.
3. Revoke it immediately after.

Keeping long-lived proxies with broad permissions around indefinitely defeats the purpose. The goal is to minimize the window during which a leaked key can cause damage.

Monitor proxy announcements

A delayed proxy must broadcast its intent on-chain before executing. If you are not actively monitoring those announcements, the delay provides no protection. The delay creates a veto window — it does not enforce one. An attacker who steals a proxy key can announce a call and wait out the delay undetected if no one is watching.

Requirements:

• Check for pending announcements on a schedule shorter than your configured delay period. A 100-block delay (~20 minutes) requires checks more frequent than that.
• Revoke any proxy relationship you are not actively monitoring. A dormant delayed proxy with no observer is no safer than a zero-delay proxy.
• Be ready to reject unexpected announcements from your hardware wallet immediately.

See Monitor and Reject Announcements for how to query pending announcements, run a monitoring script, and reject from your hardware wallet.

Do not mine with primary coldkeys

Miners need coldkeys for currency management and hotkeys for serving requests. The primary coldkey should never be present in an environment running untrusted ML code, containers, or third-party frameworks. Use a proxy coldkey with the minimum permissions required, and revoke it when not actively mining.

Rotating a compromised proxy coldkey

If a proxy coldkey is leaked, remove it from your hardware wallet immediately. Because the primary coldkey is unaffected, the blast radius is limited to what the proxy was permitted to do and what it had time to execute before revocation.

Team and multi-signature setups

If a team collectively manages a coldkey, use a multisig to prevent a single compromised team member from acting unilaterally.

See Multi-signature wallets.

Operations requiring the primary coldkey

Initial proxy setup and coldkey rotation require the primary coldkey. For these, use your hardware wallet (Ledger or Polkadot Vault). Both support proxy creation and coldkey rotation.

If you find yourself needing to load your primary coldkey onto a machine to perform an operation, that is a signal to reconsider the approach — not to harden the machine. Hardening does not make a hot machine safe for primary coldkey operations; it only reduces the probability of compromise. The goal is to avoid the situation entirely.

Emergency operations

If you face an urgent operation with no time for a delayed proxy — a subnet emergency requiring immediate hyperparameter changes, for example — you are choosing between intervention risk and financial risk. This is a difficult position to be in. The best preparation is to have scoped proxies already configured in advance for predictable emergency operations, so this tradeoff never arises.

Rotating your coldkey

If you suspect the primary coldkey has been compromised, you can swap it out using an on-chain extrinsic. This operation has a 5-day waiting period during which the coldkey is locked. The cost is 0.1 TAO.

See Rotate/Swap your Coldkey.

Hotkey workstation

Hotkeys in Bittensor serve as the operational keys for mining, validation, and weight commits, requiring moderately high availability. Because hotkeys do not control direct movement of TAO balances, they pose a lower risk if compromised. Nonetheless, a malicious actor who gains control of a hotkey can damage your reputation, submit invalid weights (if you are a validator), or serve malicious responses to requests as a miner.

A hotkey workstation is an operational environment. Losing a hotkey is less of a direct financial loss than losing a coldkey, but the reputational and operational risks are serious. Use general best practices for managing secrets, monitor hotkey activity continuously, and have a rapid mitigation strategy ready if a hotkey is compromised.

Secrets management

Hotkeys must be created in coldkey workstation environments and then provisioned to the mining or validation server. Options:

• A secrets management solution such as HashiCorp Vault, AWS Secrets Manager, or GCP Secret Manager to provision the hotkey to the server at runtime.
• Ephemeral secret injection via CI/CD pipelines (GitLab, GitHub Actions) to inject secrets at runtime without storing them on the server.
• Never put keys in code repositories.

Hotkey rotation

If you suspect a hotkey has been leaked, rotate it as soon as possible:

btcli wallet swap-hotkey

This moves the subnet registration to a newly created hotkey owned by the same coldkey, including all stake delegated by other users. The operation incurs a 1 TAO recycling fee.

Minimize dependency risk

Bittensor nodes often run complex software stacks with many dependencies. Steps to reduce risk:

• Keep your Python environment or Docker images updated with the latest patches.
• Avoid installing unnecessary packages.
• Pin exact package versions and verify SHA-256 hashes with pip install --require-hashes.
• Consider sandboxing ML libraries using solutions like custom Docker seccomp profiles.

For an additional layer of defense against supply chain attacks, configure network egress control — a host-level firewall that restricts outbound connections to an explicit allowlist. Even if a malicious package executes, it cannot exfiltrate key material if it cannot reach attacker-controlled infrastructure.