Bittensor SDK — Complete API Reference

Comprehensive reference for the Bittensor Python SDK. Based on the full autoapi documentation.

Package Structure

bittensor/
├── core/
│   ├── subtensor          — Synchronous blockchain interface (main class)
│   ├── async_subtensor     — Asynchronous blockchain interface
│   ├── metagraph           — Subnet state representation (sync/async/torch/nontorch)
│   ├── axon                — Server-side neuron endpoint (FastAPI)
│   ├── dendrite            — Client-side network request sender
│   ├── synapse             — Communication schema between neurons (Pydantic)
│   ├── stream              — Streaming response model
│   ├── tensor              — Tensor serialization utilities
│   ├── threadpool          — Priority thread pool for Axon
│   ├── config              — Configuration management
│   ├── settings            — Default settings
│   ├── types               — Shared type aliases and mixins
│   ├── errors              — Exception hierarchy
│   ├── chain_data/         — 26 data models for chain state
│   └── extrinsics/         — Sync + async extrinsic operations + pallet definitions
├── extras/
│   ├── subtensor_api/      — High-level SubtensorApi wrapper with 14 sub-APIs
│   ├── dev_framework/      — Test framework with ~184 namedtuple call blueprints
│   └── timelock/           — Drand-based time-lock encryption
└── utils/
    ├── balance             — Balance type (TAO/Rao conversion)
    ├── btlogging/          — Custom logging subsystem (6 modules)
    ├── weight_utils        — Weight normalization/conversion (12 functions)
    ├── registration/       — Registration utilities + torch compat
    ├── liquidity           — Uniswap V3-style liquidity math
    ├── networking          — IP/port utilities
    ├── formatting          — Human-readable number formatting
    ├── subnets             — Community SubnetsAPI base class
    ├── version             — PyPI version checker
    ├── axon_utils          — Nonce window calculations
    └── easy_imports        — Centralized import hub

Quick Start

import bittensor as bt

# Connect to network
subtensor = bt.Subtensor(network="finney")
# or async:
# subtensor = bt.AsyncSubtensor(network="finney")

# Wallet
wallet = bt.Wallet(name="my_wallet", hotkey="my_hotkey")

# Metagraph
metagraph = subtensor.metagraph(netuid=1)

# Stake
from bittensor import Balance
subtensor.add_stake(wallet, netuid=1, hotkey_ss58=wallet.hotkey.ss58_address,
                    amount=Balance.from_tao(10.0))

# Set weights
import numpy as np
subtensor.set_weights(wallet, netuid=1, uids=np.array([0,1,2]),
                      weights=np.array([0.3, 0.4, 0.3]))

Core Modules

bittensor.core.subtensor — Subtensor (Synchronous)

Subtensor(network=None, config=None, log_verbose=False, fallback_endpoints=None,
          retry_forever=False, archive_endpoints=None, mock=False)

Staking & Liquidity:

• add_stake(wallet, netuid, hotkey_ss58, amount, safe_staking=False, allow_partial_stake=False, rate_tolerance=0.005, ...) — Stake TAO
• add_stake_burn(wallet, netuid, hotkey_ss58, amount, limit_price=None, ...) — Subnet buyback
• add_stake_multiple(wallet, netuids, hotkey_ss58s, amounts, ...) — Bulk stake
• add_liquidity(wallet, netuid, liquidity, price_low, price_high, hotkey_ss58=None, ...) — Add liquidity
• remove_liquidity(wallet, netuid, position_id, hotkey_ss58=None, ...) — Remove liquidity
• modify_liquidity(wallet, netuid, position_id, liquidity_delta, hotkey_ss58=None, ...) — Modify position
• move_stake(wallet, origin_netuid, origin_hotkey, dest_netuid, dest_hotkey, amount, ...) — Move stake between subnets
• swap_stake(wallet, origin_netuid, dest_netuid, hotkey_ss58, amount, limit_price=None, ...) — Swap Alpha between subnets
• transfer_stake(wallet, origin_netuid, dest_netuid, dest_coldkey, hotkey_ss58, amount, ...) — Transfer stake to new owner
• unstake(wallet, netuid, hotkey_ss58, amount, ...) — Unstake partial
• unstake_all(wallet, hotkey_ss58, ...) — Unstake all
• unstake_multiple(wallet, netuids, hotkey_ss58s, amounts, ...) — Bulk unstake

Registration:

• register(wallet, netuid, ...) — POW registration
• burned_register(wallet, netuid, ...) — Burn registration (recycle TAO)
• register_limit(wallet, netuid, limit_price, ...) — Registration with price cap
• root_register(wallet, ...) — Root network registration

Weights:

• set_weights(wallet, netuid, uids, weights, version_key=..., ...) — Direct weight setting
• commit_weights(wallet, netuid, salt, uids, weights, mechid=0, ...) — Commit-reveal step 1
• reveal_weights(wallet, netuid, uids, weights, salt, ...) — Commit-reveal step 2
• commit_reveal_enabled(netuid, block=None) — Check if commit-reveal is active

Serving:

• serve_axon(wallet, netuid, ip, port, protocol, version, ...) — Register axon endpoint
• serve_axon_tls(wallet, netuid, ip, port, protocol, version, certificate, ...) — Register TLS axon
• serve_prometheus(wallet, netuid, ip, port, version, ...) — Register Prometheus endpoint

Proxy & Delegation:

• add_proxy(wallet, delegate_ss58, proxy_type, delay, ...) — Add proxy relationship
• remove_proxy(wallet, delegate_ss58, proxy_type, delay, ...) — Remove proxy
• remove_proxies(wallet, ...) — Remove all proxies
• announce_proxy(wallet, real_account_ss58, call_hash, ...) — Announce proxy call
• proxy(wallet, real_account_ss58, call, ...) — Execute via proxy

Coldkey Swaps:

• announce_coldkey_swap(wallet, new_coldkey_ss58, ...) — Announce swap intent
• swap_coldkey_announced(wallet, new_coldkey_ss58, ...) — Execute announced swap
• clear_coldkey_swap_announcement(wallet, ...) — Withdraw announcement
• dispute_coldkey_swap(wallet, ...) — Dispute active swap

Root Operations:

• claim_root(wallet, netuids, ...) — Claim root dividends
• set_root_claim_type(wallet, new_root_claim_type, ...) — Set root claim mechanism

Children (Child-Hotkeys):

• set_children(wallet, netuid, hotkey, children, ...) — Set child hotkeys
• get_children(netuid, hotkey_ss58, block=None) — Get children of hotkey

Queries (read-only, no wallet needed):

• metagraph(netuid, block=None) — Get metagraph
• get_subnet_info(netuid, block=None) — Get subnet details
• all_subnets(block=None) — All subnets with parameters
• get_balance(address, block=None) — Get coldkey balance
• get_stake(coldkey_ss58, hotkey_ss58, netuid, block=None) — Get stake amount
• get_total_subnets(block=None) — Total subnet count
• subnet_exists(netuid, block=None) — Check subnet exists
• is_hotkey_registered(netuid, hotkey_ss58, block=None) — Check registration
• get_uid_for_hotkey(netuid, hotkey_ss58, block=None) — Get neuron UID
• bonds(netuid, mechid=0, block=None) — Bond distribution
• weights(netuid, mechid=0, block=None) — Weight matrix
• tempo(netuid, block=None) — Subnet tempo
• difficulty(netuid, block=None) — POW difficulty
• immunity_period(netuid, block=None) — Immunity period
• blocks_since_last_step(netuid, block=None) — Blocks since last epoch
• blocks_until_next_epoch(netuid, block=None) — Blocks until next epoch
• get_subnet_burn_cost(netuid, block=None) — Burn registration cost
• get_subnet_price(netuid, block=None) — Current Alpha/TAO price
• get_subnet_prices(block=None) — All subnet prices
• get_subnet_hyperparameters(netuid, block=None) — Hyperparameters
• get_subnet_reveal_period_epochs(netuid, block=None) — Reveal period
• get_delegate_by_hotkey(hotkey_ss58, block=None) — Delegate info
• get_delegates(block=None) — All delegates
• get_delegated(coldkey_ss58, block=None) — Delegation status
• get_coldkey_swap_announcement(coldkey_ss58) — Swap announcement
• get_mev_shield_current_key() — MEV shield key
• close() — Close connection

~130+ total methods on Subtensor class. Many methods accept these common keyword args: mev_protection=DEFAULT_MEV_PROTECTION, period=DEFAULT_PERIOD, raise_error=False, wait_for_inclusion=True, wait_for_finalization=True, wait_for_revealed_execution=True

bittensor.core.async_subtensor — AsyncSubtensor

Identical API to Subtensor but all methods are async. Takes same constructor args:

AsyncSubtensor(network=None, config=None, log_verbose=False, fallback_endpoints=None,
               retry_forever=False, archive_endpoints=None, websocket_shutdown_timer=5.0, mock=False)

All ~130+ methods match Subtensor but are await-able. Use when building async applications (FastAPI miners/validators).

bittensor.core.metagraph — Metagraph

Metagraph(netuid, mechid=0, network=DEFAULT_NETWORK, lite=True, sync=True, subtensor=None)
AsyncMetagraph(netuid, mechid=0, network=DEFAULT_NETWORK, lite=True, sync=True, subtensor=None)
TorchMetagraph(netuid, ...)   # PyTorch tensor attributes
NonTorchMetagraph(netuid, ...)  # NumPy array attributes
MetagraphMixin(netuid, ...)    # Abstract base

Key attributes: n, S (stake), R (rewards), I (incentive), T (trust), C (consensus), hotkeys, coldkeys, uids, axon_infos, neurons, W (weights), bonds, emission, dividends, active, last_update, block

Methods: sync(block=None, lite=None, subtensor=None), save(root_dir=None), load(root_dir=None), state_dict(), metadata()

Factory: async_metagraph(netuid, ...) — Creates pre-synced AsyncMetagraph

bittensor.core.axon — Axon (Server)

Axon(wallet=None, config=None, port=None, ip=None, external_ip=None,
     external_port=None, max_workers=None)

Key methods:

• attach(forward_fn, blacklist_fn=None, priority_fn=None, verify_fn=None) — Register handlers
• serve(netuid, subtensor=None, certificate=None) — Register on-chain
• start() / stop() — Server lifecycle
• info() — Get AxonInfo
• default_verify(synapse) — Signature verification middleware
• verify_body_integrity(request) — Request body integrity check

Also: AxonMiddleware (Starlette middleware for request processing), FastAPIThreadedServer (uvicorn in a thread)

bittensor.core.dendrite — Dendrite (Client)

Dendrite(wallet=None)
DendriteMixin(wallet=None)  # Shared base

Key methods:

• query(target_axon, synapse, timeout=12.0) — Sync query to axon(s)
• aquery(target_axon, synapse, timeout=12.0) — Async query
• preprocess_synapse_for_request(target_axon_info, synapse, timeout=12.0) — Build headers + sign
• process_server_response(server_response, json_response, local_synapse) — Merge server state
• close_session() / aclose_session() — Cleanup

bittensor.core.synapse — Synapse

Synapse()           # Base (Pydantic BaseModel)
TerminalInfo()      # Neuron metadata carrier

Synapse methods: deserialize(), get_total_size(), to_headers(), from_headers(headers), body_hash(), parse_headers_to_inputs(headers), get_required_fields()

TerminalInfo: cast_float(raw), cast_int(raw), get_size(obj)

bittensor.core.stream — BTStreamingResponseModel

Streaming response support for large data transfers between neurons.

bittensor.core.threadpool — PriorityThreadPoolExecutor

Priority-based thread pool used internally by Axon for request handling.

bittensor.core.tensor

Tensor serialization utilities for network communication.

bittensor.core.config — Config

Configuration object parsed from CLI args. Used throughout the framework.

bittensor.core.settings — DEFAULTS

Default settings: axon (ip, port, max_workers), logging (debug, trace, info, logging_dir), priority (max_workers, maxsize), subtensor (chain_endpoint, network), wallet (name, hotkey, path).

bittensor.core.types

Shared types: AxonInfo, PrometheusInfo, SubnetInfo, NeuronInfo, NeuronInfoLite, DelegateInfo, StakeInfo, ProposalVoteData, etc. Also SubtensorMixin base class.

bittensor.core.errors

Exception hierarchy: ChainConnectionError, ChainTransactionError, IdentityError, StakeError, MetadataError, PriorityException, AxonException, DendriteException, SynapseException, StreamException, ConfigException, etc.

Chain Data Models (26 modules)

All under bittensor.core.chain_data:

Model	Description
AxonInfo	Neuron axon endpoint: ip, port, ip_type, protocol, version, placeholder1/2
ChainIdentity	On-chain identity: name, url, description, discord, github_repo, additional
ColdkeySwap	Coldkey swap execution data
CrowdloanInfo	Crowdloan details: id, cap, raised, end, min_contribution, target
DelegateInfo	Delegate: hotkey_ss58, total_stake, take, nominators, owner_ss58
DelegateInfoLite	Lightweight delegate info
DynamicInfo	Subnet dynamic parameters
InfoBase	Base dataclass for all info types
IPInfo	IP: ip, ip_type, port, protocol
MetagraphInfo	Metagraph metadata
NeuronInfo	Full neuron: hotkey, coldkey, uid, netuid, stake, rank, trust, incentive, emission, axon_info, prometheus_info, etc.
NeuronInfoLite	Lightweight neuron info
PrometheusInfo	Prometheus endpoint: ip, port, version
ProposalVoteData	Governance proposal vote data
Proxy	Proxy relationship: delegate, proxy_type, delay
RootClaim	Root claim data
ScheduledColdkeySwapInfo	Scheduled swap details
SimSwap	Simulated swap result
StakeInfo	Stake: hotkey_ss58, coldkey_ss58, stake
SubnetHyperparameters	Full hyperparameter set for a subnet
SubnetIdentity	Subnet identity: subnet_name, subnet_url, subnet_contact, logo_url, description, discord, github_repo, additional
SubnetInfo	Subnet: netuid, owner, tempo, emission, dynamic_info
SubnetState	Subnet state data
WeightCommitInfo	Weight commit-reveal info
utils	Chain data utility functions

Extrinsics — Pallet Operations

Sync Extrinsics (bittensor.core.extrinsics)

Each module provides functions that compose and submit extrinsics:

• staking — add_stake, add_stake_burn, add_stake_multiple, move_stake, swap_stake, transfer_stake, unstake, unstake_all, unstake_multiple
• unstaking — remove_stake, remove_stake_limit, remove_stake_full_limit, unstake_all_alpha
• registration — burned_register, register, register_limit, root_register
• weights — set_weights, commit_weights, reveal_weights, batch_set_weights, batch_commit_weights, batch_reveal_weights
• serving — serve_axon, serve_axon_tls, serve_prometheus
• root — claim_root, root_register, root_dissolve_network, set_root_claim_type
• proxy — add_proxy, remove_proxy, remove_proxies, announce_proxy, proxy, proxy_announced
• transfer — transfer, transfer_stake
• coldkey_swap — announce_coldkey_swap, swap_coldkey, swap_coldkey_announced, clear_coldkey_swap_announcement, dispute_coldkey_swap
• crowdloan — create, contribute, dissolve, finalize, refund, update_cap, update_end, update_min_contribution, withdraw
• liquidity — add_liquidity, remove_liquidity, modify_liquidity, toggle_user_liquidity, swap_stake
• mev_shield — mev_submit_encrypted
• take — increase_take, decrease_take
• children — set_children, swap_hotkey
• sudo — Admin/root operations
• start_call — Start call
• move_stake — move_stake, swap_stake, transfer_stake
• utils — Helper utilities

Async Extrinsics (bittensor.core.extrinsics.asyncex)

Identical module structure but async versions. All functions are async def.

Pallet Definitions (bittensor.core.extrinsics.pallets)

Constants for pallet names used in extrinsics:

• admin_utils — Admin utility pallet constants
• balances — Balance transfer constants (Transfer, TransferKeepAlive, TransferAllowDeath, etc.)
• base — Base pallet shared types
• commitments — Commitment pallet
• crowdloan — Crowdloan pallet
• mev_shield — MEV shield pallet
• proxy — Proxy pallet types
• subtensor_module — Main SubtensorModule pallet
• sudo — Sudo pallet
• swap — Swap pallet

Extras

bittensor.extras.subtensor_api — SubtensorApi

High-level wrapper providing a unified interface over both Subtensor and AsyncSubtensor:

SubtensorApi(network=None, config=None, async_subtensor=False, legacy_methods=False,
             fallback_endpoints=None, retry_forever=False, log_verbose=False,
             mock=False, archive_endpoints=None, websocket_shutdown_timer=5.0)

Properties (each returns a sub-API instance):

• .chain — Chain: get_current_block, get_block_hash, get_timestamp, state_call, tx_rate_limit, is_fast_blocks, last_drand_round, get_existential_deposit, get_minimum_required_stake, etc. (15 methods)
• .commitments — Commitments: get_commitment, get_all_commitments, set_commitment, commit_reveal_enabled, etc. (12 methods)
• .crowdloans — Crowdloans: create_crowdloan, contribute_crowdloan, dissolve_crowdloan, finalize_crowdloan, get_crowdloans, etc. (14 methods)
• .delegates — Delegates: get_delegates, get_delegate_by_hotkey, get_delegate_take, set_delegate_take, get_delegated, etc. (7 methods)
• .extrinsics — Extrinsics: add_stake, set_weights, burned_register, serve_axon, etc. (45 methods)
• .metagraphs — Metagraphs: metagraph, get_metagraph_info, get_all_metagraphs_info
• .mev_shield — MevShield: get_mev_shield_current_key, get_mev_shield_next_key, mev_submit_encrypted
• .neurons — Neurons: neurons, neurons_lite, neuron_for_uid, query_identity, get_neuron_certificate
• .proxies — Proxy: add_proxy, remove_proxy, get_proxies, etc. (16 methods)
• .queries — Queries: query_subtensor, query_map, query_constant, query_module, query_runtime_api
• .staking — Staking: add_stake, unstake, move_stake, swap_stake, claim_root, get_stake, etc. (30 methods)
• .subnets — Subnets: all_subnets, get_subnet_info, get_subnet_hyperparameters, register, etc. (45 methods)
• .utils — Utility functions
• .wallets — Wallets: get_balance, get_balances, transfer, get_stake, is_hotkey_registered, etc. (35 methods)

Each sub-API class takes subtensor: Union[Subtensor, AsyncSubtensor] and supports both sync and async.

bittensor.extras.dev_framework — Test Framework

calls module: ~184 namedtuple call blueprints for constructing extrinsics. Divided into:

• non_sudo_calls (~100 namedtuples): ADD_STAKE, SET_WEIGHTS, REGISTER, BURNED_REGISTER, COMMIT_WEIGHTS, REVEAL_WEIGHTS, TRANSFER, etc.
• sudo_calls (~84 namedtuples): SUDO_SET_TEMPO, SUDO_SET_DIFFICULTY, SUDO_SET_MAX_ALLOWED_UIDS, etc.
• pallets (string constants): AdminUtils, Balances, Commitments, Crowdloan, MevShield, Proxy, SubtensorModule, Sudo, Swap, etc.

subnet module: TestSubnet class for test subnet lifecycle management.

utils module: ActivateSubnet, RegisterNeuron, RegisterSubnet helpers.

bittensor.extras.timelock — Time-Lock Encryption

Drand QuickNet-based TLE:

encrypt(data, n_blocks, block_time=12.0) -> tuple  # (encrypted_data, reveal_round)
decrypt(encrypted_data, no_errors=True, return_str=False)
wait_reveal_and_decrypt(encrypted_data, reveal_round=None, no_errors=True, return_str=False) -> bytes

Use block_time=0.25 for fast-blocks nodes.

Utils

bittensor.utils.balance — Balance

Balance(balance: int | float)  # int=rao, float=tao

Static methods: from_tao(amount), from_rao(amount), from_float(amount), get_unit(netuid) Properties: tao (float), rao (int), unit (str), rao_unit (str) Helpers: tao(amount, netuid=0) -> Balance, rao(amount, netuid=0) -> Balance

bittensor.utils.btlogging — Logging

Custom logging subsystem with state machine:

LoggingMachine(config, name="bittensor")  # StateMachine + logging.Logger

States: Default, Debug, Trace, Info, Warning, Disabled Methods: debug(), info(), warning(), error(), success(), trace(), critical(), exception() Toggle: set_debug(on), set_trace(on), set_info(on), on(), off() Console: BittensorConsole with info(), success(), warning(), error(), critical(), debug() Formatters: BtFileFormatter, BtStreamFormatter (colors, emojis, millisecond timestamps) Config: LoggingConfig namedtuple — debug, info, trace, record_log, logging_dir, enable_third_party_loggers

Global toggles: btlogging.debug(on), btlogging.trace(on), btlogging.info(on), btlogging.warning(on)

bittensor.utils.weight_utils — Weight Processing (12 functions)

• normalize_max_weight(x, limit=0.1) — Normalize with max cap
• process_weights(uids, weights, num_neurons, min_allowed_weights, max_weight_limit, exclude_quantile=0) — Full weight processing
• process_weights_for_netuid(uids, weights, netuid, subtensor, metagraph=None, exclude_quantile=0) — Subnet-aware processing
• convert_weights_and_uids_for_emit(uids, weights) — To chain format
• convert_weight_uids_and_vals_to_tensor(n, uids, weights) — From chain format
• convert_root_weight_uids_and_vals_to_tensor(n, uids, weights, subnets) — Root weights
• generate_weight_hash(address, netuid, uids, values, version_key, salt) — Commit hash

bittensor.utils.liquidity — Liquidity Math

Uniswap V3-style: price_to_tick(price), tick_to_price(tick), calculate_fees(...), get_fees(...)

LiquidityPosition dataclass: id, netuid, liquidity, price_low, price_high, fees_tao, fees_alpha Method: to_token_amounts(current_subnet_price) -> (alpha_amount, tao_amount)

bittensor.utils.networking

get_external_ip(), get_formatted_ws_endpoint_url(url), int_to_ip(int), ip_to_int(str), ip_version(str)

bittensor.utils.registration.torch_utils

LazyLoadedTorch — lazy torch import proxy legacy_torch_api_compat(func) — Decorator for torch↔numpy compatibility use_torch() — Check/enable torch mode

bittensor.utils.axon_utils

allowed_nonce_window_ns(current_time_ns, synapse_timeout) — Nonce window calculate_diff_seconds(current_time, synapse_timeout, synapse_nonce) — Time diff

Other Utils

• bittensor.utils.version: check_version(timeout), get_and_save_latest_version(timeout)
• bittensor.utils.formatting: get_human_readable(num), millify(n)
• bittensor.utils.subnets: SubnetsAPI(wallet) — Community ABC for subnet querying
• bittensor.utils: unlock_key(wallet), is_valid_ss58_address(addr), decode_hex_identity_dict(d), format_error_message(err), strtobool(val), float_to_u64(val), u16_normalized_float(x), determine_chain_endpoint_and_network(network)

Common Patterns

MEV Protection

Most extrinsic methods accept these keyword args:

mev_protection=DEFAULT_MEV_PROTECTION  # Enable MEV shielding
period=DEFAULT_PERIOD                   # Blocks to wait for inclusion
raise_error=False                       # Raise on failure instead of returning error
wait_for_inclusion=True                 # Wait for block inclusion
wait_for_finalization=True              # Wait for block finalization
wait_for_revealed_execution=True        # Wait for MEV reveal period

Safe Staking

subtensor.add_stake(wallet, netuid=1, hotkey_ss58=addr, amount=amount,
                    safe_staking=True,       # Price protection
                    allow_partial_stake=True, # Accept partial fill
                    rate_tolerance=0.005)     # 0.5% slippage

Async Pattern

async with bt.AsyncSubtensor(network="finney") as subtensor:
    metagraph = await subtensor.metagraph(netuid=1)
    result = await subtensor.add_stake(wallet, netuid=1, ...)

Using SubtensorApi (Recommended for new code)

api = bt.SubtensorApi(network="finney")
block = api.block
info = api.subnets.get_subnet_info(netuid=1)
stake = api.staking.add_stake(wallet, netuid=1, ...)

Network Types

• finney — Mainnet
• test — Testnet
• local — Local dev chain

Key Constants