Bittensor SDK

Complete Bittensor SDK reference — Subtensor, AsyncSubtensor, Metagraph, Axon, Dendrite, Synapse, chain_data models, extrinsics (sync + async), extras (subtensor_api, dev_framework, timelock), and utils (balance, btlogging, weight_utils, registration, liquidity, networking, version). Use for any bittensor operation: wallet management, staking, subnet ops, neuron registration, metagraph queries, emissions tracking, liquidity management, MEV protection, proxy delegation, coldkey swaps, crowdloans, weight setting, and more.

Taoli@taoleeh

Install

openclaw skills install @taoleeh/bittensor-sdk

Bittensor SDK — Complete API Reference

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

Package Structure

text

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

python

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)

python

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:

python

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

python

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)

python

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)

python

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

python

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:

python

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:

python

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

python

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:

python

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:

python

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

python

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

python

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)

python

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

RAOPERTAO = 1_000_000_000.0 (1 TAO = 1e9 Rao)
U16_MAX = 65535, U32_MAX = 4294967295, U64_MAX = 18446744073709551615
GLOBAL_MAX_SUBNET_COUNT = 4096

Examples

Complete Miner

python

import bittensor as bt

subtensor = bt.Subtensor(network="finney")
wallet = bt.Wallet(name="miner", hotkey="hk1")

# Register
subtensor.burned_register(wallet, netuid=1, wait_for_inclusion=True)

# Check position
mg = subtensor.metagraph(netuid=1)
uid = mg.hotkeys.index(wallet.hotkey.ss58_address)
print(f"UID: {uid}, Stake: {mg.S[uid]}, Emission: {mg.emission[uid]}")

Complete Validator

python

import bittensor as bt
import numpy as np

subtensor = bt.Subtensor(network="finney")
wallet = bt.Wallet(name="validator", hotkey="vk1")

mg = subtensor.metagraph(netuid=1)
weights = np.random.rand(mg.n)
weights = weights / weights.sum()

subtensor.set_weights(wallet, netuid=1, uids=np.arange(mg.n),
                      weights=weights,
                      wait_for_inclusion=True, wait_for_finalization=True)

Axon Server

python

import bittensor as bt

def forward(synapse): ...
def blacklist(synapse): ...
def priority(synapse): ...

wallet = bt.Wallet(name="miner", hotkey="hk1")
axon = bt.Axon(wallet=wallet, port=8091)
axon.attach(forward_fn=forward, blacklist_fn=blacklist, priority_fn=priority)
axon.serve(netuid=1)
axon.start()

Dendrite Client

python

import bittensor as bt

dendrite = bt.Dendrite(wallet=bt.Wallet(name="validator", hotkey="vk1"))
metagraph = bt.Subtensor(network="finney").metagraph(netuid=1)
responses = dendrite.query(metagraph.axons, bt.Synapse(), timeout=12)

Liquidity Management

python

subtensor.add_liquidity(wallet, netuid=1,
                        liquidity=bt.Balance.from_tao(100),
                        price_low=bt.Balance.from_tao(50),
                        price_high=bt.Balance.from_tao(200),
                        wait_for_inclusion=True)

Time-Lock Encryption

python

from bittensor.extras.timelock import encrypt, decrypt, wait_reveal_and_decrypt

encrypted, reveal_round = encrypt(b"secret data", n_blocks=100)
# Later, after enough blocks...
data = wait_reveal_and_decrypt(encrypted)

Troubleshooting

Connection issues: Use fallback endpoints and retry_forever=True

python

subtensor = bt.Subtensor(network="finney",
    fallback_endpoints=["wss://entrypoint-finney.opentensor.ai:443"],
    retry_forever=True)

Registration fails: Check balance, try alternative method. Use register_limit() for price protection.

Weight setting fails: Verify commit-reveal cycle. Check commit_reveal_enabled(netuid) first.

Rate limiting: Space out extrinsics. Use period= parameter to control inclusion window.

Wallet not found: Use bt.Wallet(name="...").create_if_non_existing() or bt.Wallet(name="...", hotkey="...").regenerate_coldkey(...).

References

Bittensor Docs
Bittensor SDK Reference
Learn Bittensor
Taostats API
Bittensor GitHub
Full autoapi: references/autoapi/index.md (133 files, complete SDK API docs)

Bittensor SDK

Install

Bittensor SDK — Complete API Reference

Package Structure

Quick Start

Core Modules

bittensor.core.subtensor — Subtensor (Synchronous)

bittensor.core.async_subtensor — AsyncSubtensor

bittensor.core.metagraph — Metagraph

bittensor.core.axon — Axon (Server)

bittensor.core.dendrite — Dendrite (Client)

bittensor.core.synapse — Synapse

bittensor.core.stream — BTStreamingResponseModel

bittensor.core.threadpool — PriorityThreadPoolExecutor

bittensor.core.tensor

bittensor.core.config — Config

bittensor.core.settings — DEFAULTS

bittensor.core.types

bittensor.core.errors

Chain Data Models (26 modules)

Extrinsics — Pallet Operations

Sync Extrinsics (bittensor.core.extrinsics)

Async Extrinsics (bittensor.core.extrinsics.asyncex)

Pallet Definitions (bittensor.core.extrinsics.pallets)

Extras

bittensor.extras.subtensor_api — SubtensorApi

bittensor.extras.dev_framework — Test Framework

bittensor.extras.timelock — Time-Lock Encryption

Utils

bittensor.utils.balance — Balance

bittensor.utils.btlogging — Logging

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

bittensor.utils.liquidity — Liquidity Math

bittensor.utils.networking

bittensor.utils.registration.torch_utils

bittensor.utils.axon_utils

Other Utils

Common Patterns

MEV Protection

Safe Staking

Async Pattern

Using SubtensorApi (Recommended for new code)

Network Types

Key Constants

Examples

Complete Miner

Complete Validator

Axon Server

Dendrite Client

Liquidity Management

Time-Lock Encryption

Troubleshooting

References

Related skills

Sync Extrinsics (`bittensor.core.extrinsics`)

Async Extrinsics (`bittensor.core.extrinsics.asyncex`)

Pallet Definitions (`bittensor.core.extrinsics.pallets`)