Transactions

swap-hotkey

Swap a hotkey for a new one (all subnets, or one netuid).

Re-keys the neuron identity: the old hotkey's registrations, stake, and history move to new_hotkey_ss58, either everywhere (netuid omitted) or on a single subnet. The all-subnets swap recycles 0.1 TAO from the coldkey; the per-subnet swap recycles 0.001 TAO. Both respect a 7,200-block (one day) per-(subnet, coldkey) cooldown — the all-subnets swap checks and records it on every subnet the old hotkey participates in. The old hotkey stops earning immediately, so update running miners/validators to sign with the new key at the same time. The new hotkey must not already be registered where the swap applies, so plan the change rather than iterating. This wraps the legacy swap_hotkey extrinsic, deprecated on chain in favor of swap_hotkey_v2; behavior is identical to swap_hotkey_v2 with keep_stake=false (stake moves to the new hotkey). This rotates a leaked hotkey without touching the coldkey; a compromised coldkey needs a coldkey swap instead.

Signer	Pallet	Wraps
`coldkey`	SubtensorModule	`SubtensorModule.swap_hotkey`

Parameters

Parameter	Type	Required	Description
`new_hotkey_ss58`	string	yes	Replacement hotkey that takes over the old hotkey's registrations and stake.
`hotkey_ss58`	string	no	Hotkey being replaced; defaults to the wallet's hotkey.
`netuid`	integer	no	Limit the swap to this subnet; omit to swap across all subnets.

Address parameters (--hotkey, --coldkey, --dest, ...) accept a raw ss58 address, an address-book or proxy-book name, or a local wallet/hotkey name.

CLI

Preview with --dry-run (shows fee, effects, and policy result without submitting), then submit:

btcli tx swap-hotkey \
  --new-hotkey <ss58|name> --dry-run
btcli tx swap-hotkey \
  --new-hotkey <ss58|name> -w my_coldkey

Python

import bittensor as sub
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = sub.SwapHotkey(new_hotkey_ss58="5F...")

async with sub.Client("finney") as client:
    plan = await client.plan(intent, wallet)   # fee, effects, policy — no submission
    result = await client.execute(intent, wallet)
    if not result.success:
        print(result.error.code, result.error.remediation)

Or build it by op name, as an agent would:

await client.execute_tool("swap_hotkey", {...}, wallet)