Migrating from v9/v10

Bittensor 11 replaces two packages — the bittensor SDK (v10.x) and the separate bittensor-cli (v9.x, the old btcli) — with one package that contains both. The API is not a rename of the old one: the Subtensor class and its ~165 methods are gone, replaced by a small client with typed reads and a catalog of intents executed through one plan/execute pipeline. This page maps every commonly scripted old call and CLI command to its v11 equivalent.

If you are an LLM migrating a user's scripts, follow this procedure:

1. Read this entire page — the tables are exact, not illustrative.
2. Apply the SDK mappings and CLI mappings mechanically; where a row says "no direct equivalent", use the listed escape hatch.
3. Watch the semantic traps in Money, Weights and take, Results and errors, and Chain and runtime changes — these change behavior, not just names.
4. Verify against the live catalogs rather than guessing: bt.intents.list_tools() and bt.reads.list_reads() in Python, btcli tools and btcli query --help on the CLI, or the generated references under Transactions and Queries.
5. Preview every rewritten mutation with client.plan(...) or --dry-run before submitting anything.

Packages and install

uv pip install bittensor          # library + btcli, one package

The [cli] and [evm] extras still parse (bittensor[cli] installs fine) but are empty — everything is in the base install now.

Remove bittensor-cli and bittensor_wallet from your requirements; both are superseded. Wallets on disk are keyfile-compatible — nothing to convert (see Wallets).

Upgrading an existing environment

Order matters in an environment that already has the old stack, because bittensor-cli 9.x and bittensor 11.x both own the btcli command:

pip uninstall -y bittensor-cli bittensor-wallet
pip install -U bittensor

If you upgraded first and uninstalled bittensor-cli after, pip deletes the btcli script (it is still listed in the old package's file manifest). Nothing is lost — reinstate it with:

pip install --force-reinstall --no-deps bittensor

While a stale bittensor-cli is still installed, the v11 btcli prints a warning with this fix on every run.

Two version pitfalls that fail silently:

• Python 3.14: v10 allowed it, v11 supports 3.10–3.13. On a 3.14 interpreter pip install -U bittensor quietly keeps 10.x (pip picks the newest release whose requires-python matches). If btcli --version still says 9.x/10.x after upgrading, check python --version first.
• Pinned requirements: anything pinning bittensor<11 or bittensor~=10 keeps working against v10 untouched — the new package changes nothing until you move the pin.

Platform support: wheels ship for Linux (x86_64, aarch64) and macOS (Apple Silicon and Intel), Python 3.10–3.13 — the same coverage as the old stack. Windows is unsupported natively (as before); use WSL. On any other platform pip falls back to a source build, which requires a Rust toolchain.

The model change in one example

Old (v10):

import bittensor as bt

subtensor = bt.Subtensor(network="finney")
wallet = bt.Wallet(name="my_coldkey", hotkey="my_hotkey")

balance = subtensor.get_balance("5F...")
response = subtensor.add_stake(
    wallet, netuid=1, hotkey_ss58="5F...validator", amount=bt.tao(10),
)
if not response.success:
    print(response.message)

New (v11):

import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
sub = bt.Subtensor()          # defaults to finney; no close() needed

balance = sub.balances.get("5F...")
result = sub.execute(
    bt.AddStake(hotkey_ss58="5F...validator", netuid=1, amount_tao=10),
    wallet,
)
if not result.success:
    print(result.error.code, result.error.remediation)

The three structural changes:

1. One client, no method zoo. bt.Subtensor keeps its name but is a new class: one entry point that is blocking when used directly and async when awaited (async with bt.Subtensor() as client:) — AsyncSubtensor is gone. The ~165 v10 methods are replaced by typed reads on category namespaces (sub.subnets, sub.staking, sub.delegation, sub.prices, ... — with autocomplete and signature help), dispatchable by name too (sub.read("uid", hotkey_ss58=..., netuid=...)), and anything else is reachable through generic accessors (sub.query(bt.storage...)). See The client.
2. Transactions are intents. Every mutation is a small dataclass (bt.Transfer, bt.AddStake, bt.SetWeights, ...) executed through client.plan(intent, wallet) / client.execute(intent, wallet). See The transaction model.
3. Results are data. ExtrinsicResponse becomes ExtrinsicResult with a classified error.code and a remediation hint instead of prose.

Connecting

Network names finney, test, archive, local resolve to the same endpoints as before, and any ws:// / wss:// URL is accepted directly. The extra v9-CLI aliases (dev, rao, latent-lite) are gone — pass the URL.

Every v10 read took block=. In v11, namespace methods still accept block=, and for multi-read consistency pin a snapshot:

snap = await client.at(block)          # Snapshot: same read surface, one block
bal = await snap.balances.get("5F...")

Environment variables and configuration

The old argparse machinery — bt.Config, Subtensor.add_args, Wallet.add_args, --subtensor.network, --wallet.name flags parsed inside the SDK — is gone entirely. Scripts own their own argument parsing; the SDK reads nothing from sys.argv.

bt.logging is gone. The SDK logs under the bittensor.* namespace via the standard library and configures no handlers:

import logging
logging.getLogger("bittensor").setLevel(logging.DEBUG)

Reading chain state

General rules: every named read below is a typed method on its namespace (client.staking.stake_for_coldkey(...)) and equally dispatchable by name (client.read("stake_for_coldkey", ...)); both take the same ..._ss58 parameter names the old methods used. Results that used to be raw u16/u64 integers come back normalized (weights and bonds as 0..1 floats, balances as Balance). Anything without a named read is reachable through the generic accessors — client.query(bt.storage.Pallet.Item, [params]), client.query_map(...), client.constant(bt.constants...), client.runtime(bt.runtime_api...) — which cover the entire runtime surface, replacing query_subtensor, query_module, query_map, query_map_subtensor, query_constant, query_runtime_api, and state_call.

Balances and stake

Subnets and hyperparameters

Neurons, registration, delegates

Chain, blocks, and the rest

The metagraph

subtensor.metagraph(netuid) returned an object of parallel NumPy arrays (S, W, B, I, uids, hotkeys, axons, ...) with sync(), save(), load(). The v11 metagraph is a plain typed object with per-neuron records and no matrices:

mg = await client.subnets.metagraph(netuid=1)
for n in mg:                      # MetagraphNeuron, ordered by uid
    n.uid, n.hotkey, n.coldkey
    n.incentive, n.dividends, n.rank, n.trust, n.consensus   # 0..1 floats
    n.emission, n.alpha_stake, n.tao_stake, n.total_stake    # Balance
    n.axon                        # "ip:port" or None
mg.hotkeys, mg.coldkeys, mg.validators
mg.neuron(5), mg.by_hotkey("5F...")

The metagraph record returned by the metagraph read (client.read("metagraph", netuid=...), btcli query metagraph --netuid N --json) carries name and symbol decoded to text; on the wire they are compact-u16 vectors of utf-8 bytes, unlike every other text field on the record. If you need the undecoded wire record, call the runtime API directly:

await client.runtime(bt.runtime_api.SubnetInfoRuntimeApi.get_metagraph, [netuid])

Transactions

Every old transaction method maps to an intent class executed with client.execute(intent, wallet). Trailing kwargs move as follows: wait_for_inclusion / wait_for_finalization / period are kwargs of execute; raise_error=True becomes result.raise_for_failure(); mev_protection becomes mev_shield (on by default for stake-trading intents). The safe_staking / rate_tolerance / allow_partial_stake flags become the explicit *Limit intent variants with a limit_price_rao (see slippage for converting a tolerance to a limit price).

Dynamic dispatch (the old pattern of calling methods by name) becomes bt.intents.build(op, args_dict) or client.execute_tool(op, args_dict, wallet) — see For agents.

New in v11, worth adopting during migration: client.plan(intent, wallet) previews fee, effects, and warnings without submitting, and a bt.Policy(max_spend_tao=..., allowed_netuids=[...]) on the client hard-bounds what any execution may do.

Weights, children, and take

Three call families changed units, not just names:

• Weights are easier: pass floats (any scale — only proportions matter) or a {uid: weight} dict to bt.SetWeights; clipping, normalization, and u16 quantization happen internally (bittensor.intents.normalize is the canonical implementation). bittensor.utils.weight_utils (process_weights_for_netuid, convert_weights_and_uids_for_emit, ...) is gone and unnecessary. set_weights also auto-selects plain vs timelocked commit-reveal submission; drop any manual commit/reveal scheduling unless you used salt-based commits. version_key now defaults to 0 instead of the SDK version number — pass the subnet's required key explicitly if it enforces one.
• Take still accepts the float 0–1 form (take=0.18); a plain integer is the raw u16 proportion (take=11796), following the hyperparameter value rules (a decimal point marks the human form). set_delegate_take's auto-direction behavior is preserved by bt.SetTake; bt.IncreaseTake / bt.DecreaseTake pin the direction.
• Children proportions likewise accept floats 0–1 (children=[[0.5, "5F...child"]]); a plain integer is the raw u64 share of u64::MAX.

Money and Balance

Balance survives but is stricter — the biggest silent-behavior change in v11 (Money):

• Every Balance carries a netuid (0 = TAO). Arithmetic or comparison across units raises bt.UnitMismatchError (was BalanceUnitMismatchError); comparing with a bare float raises TypeError.
• .tao on an alpha balance raises instead of returning a number. Use .amount for the value in its own currency, or the stake-value-for-coldkey read to value alpha in TAO.
• Balance.from_tao(amount) no longer takes a netuid; Balance.from_alpha(amount, netuid=...) is the alpha constructor. Shorthands: bt.tao(1.5), bt.alpha(2.5, 42), bt.rao(1_500_000_000).
• Intent amount fields are unit-named (amount_tao, amount_alpha, limit_price_rao) and accept int | float | str | Decimal | Balance — the strict "must be a Balance object" rule from v10 is relaxed because the field name now carries the unit. Fields that support it accept "all".

Wallets

bittensor_wallet is replaced by bittensor.wallet with the same on-disk format — same paths (~/.bittensor/wallets/<name>/), same keyfile encryption (NaCl / legacy), same SS58 format. Existing wallets just work.

from bittensor.wallet import Wallet
wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")   # same constructor
wallet.coldkey, wallet.hotkey, wallet.coldkeypub          # same properties
wallet.create_new_coldkey(...), wallet.regenerate_coldkey(...)

Differences: bt.Wallet(config=...) and Wallet.add_args are gone (pass name/hotkey/path directly); bt.Keypair / bt.Keyfile are no longer top-level exports (bittensor.keyfiles.Keyfile exists; keypairs come from the wallet). Convenience helpers live in bt.wallets (create, regen_coldkey, list_wallets, sign_message, verify_message, ...). Non-interactive unlock: BT_WALLET_PASSWORD or BT_WALLET_PASSWORD_FILE (wallets).

Axon, Dendrite, and Synapse are gone

v11 contains no miner/validator networking stack: bt.Axon, bt.Dendrite, bt.Synapse, bt.StreamingSynapse, bt.SubnetsAPI, and bt.Tensor do not exist. What the old stack actually provided splits into three layers, and each has a v11 answer:

The chain-side operations remain — publish your endpoint with bt.ServeAxon (see Mining), set weights with bt.SetWeights (see Validating). The identity layer — hotkey-signed HTTP requests, replacing the old bt_header_* scheme with a cleaner cross-language wire format (btauth/1) — ships in the SDK as pure sign/verify functions with no server or client attached. A miner that must keep accepting old-SDK validators during a transition can also verify the legacy v10 header format (recipe in the guide).

Results and errors

Prefer .code over matching .name or message strings. SubtensorModule renamed InsufficientBalance → InsufficientTaoBalance (same error index) and added InsufficientAlphaBalance; both still classify as ErrorCode.INSUFFICIENT_BALANCE. Other pallets (Balances, Crowdloan, Swap) may still emit InsufficientBalance. btcli explain <Name> and result.error.description give the per-name trigger text.

result = await client.execute(intent, wallet)
if not result.success:
    match result.error.code:
        case bt.ErrorCode.RATE_LIMITED: ...        # wait and retry
        case bt.ErrorCode.INSUFFICIENT_BALANCE: ...
        case _: log(result.error.remediation)

Chain and runtime changes

The v11 package ships against a runtime that also changed behavior. These are not rename mappings — scripts that still "work" can fail or mis-account after the upgrade. Full narrative: The V431 Upgrade.

Ownership and emissions

• Subnet ownership. For subnets at least one year old, ownership transfers to the highest-conviction hotkey when total conviction reaches 10% of SubnetAlphaOut. Existing conviction counts toward this threshold. See Conviction.
• Cross-subnet emissions. Allocation uses EMA price adjusted by miner burn; root_proportion is no longer included in the inter-subnet split (it still applies inside each subnet for injection caps and root dividends). Update emission calculations and forecasts. See Emissions.

Proxies and coldkeys

• Deny-by-default allowlists. Proxy types only permit listed call groups. Audit every existing grant. Triumvirate / Senate / Governance / RootWeights proxies deny all calls. A Staking proxy cannot wrap Utility.batch_all — batched staking needs NonTransfer. See Proxies.
• Coldkey-swap and dissolve scope. NonTransfer, NonFungible, and NonCritical proxies can no longer call reset_coldkey_swap, swap_coldkey, or schedule_swap_coldkey. NonCritical can no longer call root_dissolve_network. Owner proxies are limited to owner-settable subnet configuration and identity calls (not owner-key rotation).
• Reject locked alpha. Coldkeys that should accept locked-alpha transfers must opt in with set_reject_locked_alpha (raw call / submit_call — no first-class intent yet). Default is to reject.

Staking and fees

• Default slippage protection. AddStake, RemoveStake, and SwapStake (and the matching CLI commands) apply a 5% price bound by default. Old any-price scripts fail with SlippageTooHigh unless you pass slippage_protection=False / --no-slippage-protection, or set an explicit rate_tolerance / limit price.
• Strict stake moves. move_stake / transfer_stake / swap_stake no longer silently cap the alpha amount to what remains after an alpha-paid fee. Submitting the full stake balance can fail with NotEnoughStakeToWithdraw — leave dust or query the post-fee balance first.
• Limit-stake TAO refund. When a price limit stops a stake-in swap before the full TAO is consumed, the unswapped remainder is refunded to the coldkey (it used to sit on the subnet pallet account). Prefer post-state balances over summing StakeAdded amounts for partial fills — the event can still report the pre-refund TAO, and SubnetVolume may overstate the same way.
• Take changes pay fees. increase_take and decrease_take are Pays::Yes. Preview with client.plan(...) / --dry-run.
• Hotkey-swap alpha fees. swap_hotkey / swap_hotkey_v2 can take the transaction fee in alpha across the hotkey's stake subnets — same "don't submit the entire balance" footgun as stake moves when paying in alpha.
• Stake move/transfer/swap extrinsics also pay the ordinary transaction fee (Pays::Yes). Same-subnet move_stake is not a pool swap, but it is not fee-free.
• Miner collateral. add_collateral takes alpha (amount_alpha / AlphaBalance), not TAO — free stake covers the lock first; only a shortfall is bought with TAO under limit_price. Bonded swap_hotkey / swap_hotkey_v2 with keep_stake=true fails with KeepStakeBlockedByCollateral; use keep_stake=false so the bond migrates (lineage maps track the rename). Coldkey swap migrates MinerCollateral with the stake.
• Key lineage (runtime 437). Hotkey swaps write per-subnet HotkeySuccessor / HotkeyRoot; coldkey swaps write global ColdkeySuccessor / ColdkeyRoot. Prefer hotkey_root / coldkey_root (and same_*_lineage) for bans and owner attribution; *_lineage_tip is best-effort. See The V437 Upgrade.

Registration, hyperparameters, and randomness

• Queued subnet registration. When capacity is full or cleanup is pending, register_network may emit NetworkRegistrationQueued without creating the subnet. client.execute(RegisterSubnet(...)) and btcli subnets create wait for the matching NetworkAdded by default and return the assigned netuid; raw-call clients must do the same before treating the registration as live.
• Tempo and activity cutoff. Owner (and root) set these through AdminUtils::sudo_set_tempo and AdminUtils::sudo_set_activity_cutoff_factor. SubtensorModule call indices 139 (set_tempo) and 140 (set_activity_cutoff_factor) remain as deprecated no-op compatibility entry points: they charge a fee and return success without changing state. Use the AdminUtils calls to update these values. The live inactivity window is activity_cutoff_factor (per-mille of tempo); absolute activity_cutoff is derived / legacy. Set via bt.SetHyperparameter / btcli sudo set --name activity_cutoff_factor|tempo.
• Hyperparams read API. Prefer get_subnet_hyperparams_v3 (name→value); v1/v2 are deprecated. The SDK read already uses v3.
• Drand submissions. After the initial pulse, only last_stored_round + 1 is accepted. Missing rounds must be backfilled sequentially or commit-reveal / timelock consumers stall.

Runtime API, metadata, and catalogs

• get_proxy_filter → get_proxy_filters. Regenerate any client that called the singular API.
• Typed metadata. TAO/Alpha balances, NetUid, and related fields use distinct TypeInfo paths (SCALE bytes unchanged). Regenerate static bindings.
• Error catalog shape. /catalog/errors.json chain_errors values are now {code, description, docs_url} objects, not bare code strings. Update parsers that assumed a string.
• Contract / EVM ABI. Chain-extension output still collapses both Subtensor insufficient-balance variants to the ABI InsufficientBalance code — contracts cannot distinguish TAO vs Alpha from that code alone.

Dissolution (operators / indexers)

• Settlement cursor. Multi-block dissolution stake settlement keeps the cursor on the last completed hotkey and retries an unpaid one on the next pass instead of skipping it. Cleanup progress that assumed "cursor always advances" needs a re-check.

CLI migration

One binary, still called btcli, now installed with bittensor. The structure: every read is btcli query <name>, every transaction is btcli tx <name> (intent op names with dashes), and familiar groups (wallet, stake, subnets, sudo, weights, axon, proxy, ...) wrap the same machinery. The v9 group shorthands (w, st, s, su, c, wt, cr, d) and snake_case command spellings (wallet new_hotkey) still work as hidden aliases. Full details: The CLI.

Global flags

Config file moves from ~/.bittensor/config.yml to ~/.bittensor/btcli.json and keys are renamed: btcli config set network finney, btcli config set wallet my_coldkey (was wallet_name). The old use_cache, rate_tolerance, safe_staking, allow_partial_stake, and dashboard_path keys have no equivalent. Non-interactive behavior changed for the better: without a TTY and without --yes, a mutation is declined with exit code 1 instead of hanging; missing required options exit 2.

Command mapping

Two new commands help automated migration directly: btcli tools dumps the full transaction catalog with JSON schemas, and btcli explain <code> explains any error code.

Migration checklist

1. Replace bittensor + bittensor-cli + bittensor_wallet with a single pinned bittensor>=11 (the CLI is included). In live environments, uninstall the old packages before upgrading (why).
2. Keep bt.Subtensor(...) — the name survives, blocking as before (async when awaited; bt.AsyncSubtensor is gone) — but every method on it changed; move block=-pinned reads onto sub.at(block).
3. Rewrite reads using the tables above; anything unmapped goes through client.query(bt.storage...). Prefer hyperparams v3 for custom RPC clients.
4. Rewrite each transaction as an intent + client.execute; take values and child proportions keep working as 0–1 floats (plain integers mean the raw u16/u64 wire values); replace safe-staking flags with *Limit intents or the default 5% slippage protection (--no-slippage-protection to opt out).
5. Update result handling: .success still works, but branch on result.error.code instead of exception types or message strings. Treat SubtensorModule InsufficientTaoBalance / InsufficientAlphaBalance as the old InsufficientBalance (other pallets may still emit that name).
6. Fix Balance usage: no .tao on alpha, no cross-unit arithmetic, from_alpha for subnet currency.
7. Delete bt.config/argparse plumbing, bt.logging calls (use standard logging), and weight_utils preprocessing.
8. Update env vars (BT_SUBTENSOR_NETWORK → BT_NETWORK, BT_WALLET_NAME → BT_WALLET) and shell scripts per the CLI tables (--wallet.name → -w, --json-output → --json, --no-prompt → --yes).
9. If the script served an axon or queried miners with a dendrite, rebuild that layer on your own HTTP stack with bt.http_auth for the hotkey signing (Signed requests); only its chain calls move to this SDK's client.
10. Apply the chain and runtime changes: audit proxies; retarget owner tempo / activity_cutoff_factor calls to AdminUtils; never submit a full alpha balance when fees are alpha-paid; let the SDK wait for NetworkAdded on queued registrations (or do so in raw-call clients); regenerate metadata bindings and any errors.json / get_proxy_filter consumers.
11. Dry-run everything: client.plan(...) in Python, --dry-run on the CLI, ideally against test or a local node first.