index.mdx

title	Queries
description	Every chain read: one page per query, generated from the SDK.

{/* GENERATED by scripts/generate.py from the SDK registries — do not edit. */}

Reads are free, unsigned, and safe to call at any time. Each CLI command is btcli query <name> (add --json for machine-readable output). In Python every read is a typed method on its category's namespace — sub.subnets.subnet_registration_cost(), sub.delegation.delegates() on sub = bt.Subtensor() (awaited on the async client) — with autocomplete and signature help; sub.read("<name>", ...) dispatches the same read by name. The machine-readable catalog is at /catalog/reads.json or via bt.reads.list_reads().

Accounts & keys

Query	Summary
balance	Free TAO balance of a coldkey address.
balances	Free TAO balance for several coldkey addresses in one batched request.
coldkey-swap-announcement	A coldkey's pending swap announcement (execute block, new-key hash, disputed), or None.
existential-deposit	Minimum balance an account must keep to stay alive.
multisig	A pending multisig operation (opening timepoint, approvals, depositor), or None.
proxies	Proxy delegations of an account: who may sign on its behalf, and the reserved deposit.

Chain

Query	Summary
block-info	A block's hash, timestamp, and extrinsics (as module.function summaries).
block-time	Seconds per block, detected from the chain (12.0 mainnet, 0.25 fast-blocks).
is-fast-blocks	Whether the chain runs fast blocks (0.25s slots, local/e2e testing mode).
mev-shield-next-key	The MEV Shield ML-KEM-768 public key (0x-hex) used to encrypt shielded txs, or None.
timestamp	Current chain time (from the Timestamp pallet) and the block it was read at.
tx-rate-limit	Global transaction rate limit in blocks.

Delegation

Query	Summary
children	Child hotkeys of a parent on a subnet, as (proportion, child_ss58) pairs.
delegate	Delegate info for one hotkey, or None if it is not a delegate.
delegate-take	A hotkey's delegate take (emission fraction it keeps) with the allowed min/max.
delegated	Every nomination a coldkey holds: (delegate, netuid, stake) per position.
delegates	Every delegate hotkey on the network, with take and registrations.
is-delegate	Whether a hotkey is a delegate.
parents	Parent hotkeys of a child on a subnet, as (proportion, parent_ss58) pairs.
pending-children	Proposed child hotkeys of a parent still in cooldown, and when they apply.

Epochs & timing

Query	Summary
blocks-since-last-step	Blocks since the subnet's last epoch step ran.
blocks-since-last-update	Blocks since a neuron last set or committed weights on a subnet
blocks-until-next-epoch	Blocks until the subnet's next epoch fires, or None if tempo is 0.
epoch-status	Where a subnet is in its epoch cycle, in one block-pinned read.
next-epoch-start-block	Block at which the subnet's next epoch is expected to fire, or None if tempo is 0.

Hyperparameters

Query	Summary
difficulty	Current PoW registration difficulty for a subnet.
immunity-period	Blocks a newly registered neuron is immune from deregistration.
max-weight-limit	Normalized-fraction cap on any single weight: after the chain normalizes the submitted vector, no weight may exceed max_weight_limit/65535 of the total. Not a raw u16 ceiling per weight.
min-allowed-weights	Minimum number of weights a validator must set on a subnet. A pure self-weight (a single entry pointing at the caller's own uid) bypasses the minimum, and the subnet owner bypasses validator-permit rules.
reveal-period	Commit-reveal reveal window, in epochs, for a subnet.
subnet-emission-enabled	Root-controlled pool-side TAO emission flag for a subnet (1 = enabled). When 0, the subnet earns no TAO emission share even while subnet_is_active is true; only root can flip it (see the set_subnet_emission_enabled intent).
weights-rate-limit	Blocks a hotkey must wait between weight sets on a subnet.

Identity & commitments

Query	Summary
commitment	The commitment a hotkey has published on a subnet, or None.
commitments	Every commitment on a subnet, newest first: hotkey, uid, content, block, age, reveal state.
hotkey-identities	On-chain identities for hotkeys (via each hotkey's owner coldkey), keyed by hotkey.
identity	The on-chain identity of a coldkey (name, links, description), or None.
revealed-commitment	The revealed (timelock-decrypted) commitment for a hotkey on a subnet, or None.

Leases & crowdloans

Query	Summary
crowdloan	A crowdloan's state (creator, deposit, raised, cap, end, target/call), or None.
crowdloan-contributors	Contributors and amounts for a crowdloan, with amounts in TAO.
crowdloans	All crowdloans on chain (id and summary fields).
lease	A subnet lease by id (beneficiary, emissions share, end block, netuid, cost), or None.
leases	Every subnet lease on the network.

Locks & conviction

Query	Summary
coldkey-lock	Lock state for a coldkey on a subnet, or None if no lock exists.
hotkey-conviction	Conviction metrics for a hotkey on a subnet.
locks-for-coldkey	Every lock a coldkey holds (one per subnet), rolled forward to now.
most-convicted-hotkey	Hotkey with the highest conviction on a subnet, if any.
subnet-convictions	Every hotkey with locked stake on a subnet, rolled forward to now.

Mining & collateral

Query	Summary
collateral-policy	A subnet's collateral configuration.
miner-collateral	A (hotkey, coldkey) stake position's standing collateral, or None.
subnet-collateral	Every (hotkey, coldkey) position with standing collateral on a subnet.

Neurons & registration

Query	Summary
associated-evm-key	The EVM address associated with a neuron (by netuid + uid) and the block it was set.
hotkey-owner	The coldkey that owns a hotkey, or None if unowned.
netuids-for-hotkey	Every subnet a hotkey is registered on, as a sorted list of netuids.
neurons	Every neuron on a subnet in ONE runtime-API call (the metagraph fast path).
owned-hotkeys	Every hotkey owned by a coldkey (the reverse of hotkey_owner).
uid	UID of a hotkey on a subnet, or None if not registered there.

Prices & swaps

Query	Summary
alpha-price	Current spot alpha price for a subnet, as TAO per alpha.
alpha-prices	Spot alpha price for every subnet, as TAO per alpha keyed by netuid.
quote-stake	Simulate staking amount_tao TAO into a subnet: alpha out, fee, and slippage.
quote-unstake	Simulate unstaking amount_alpha alpha from a subnet: TAO out, fee, and slippage.

Staking

Query	Summary
auto-stake	The hotkey a coldkey auto-stakes its rewards to on a subnet, or None if unset.
auto-stake-all	Every auto-stake destination configured for a coldkey.
root-basket-owed	Total TAO a coldkey would realize by claiming its root dividends now.
root-basket-owed-breakdown	A coldkey's pending root dividends, itemized per validator hotkey.
root-basket-total-nav	Network-wide total basket NAV across all validators, in TAO.
root-baskets	Basket summaries for every validator with an active basket.
root-claim-threshold	The minimum TAO payout for a root dividend claim.
stake	Alpha staked by a coldkey to a hotkey on a subnet (TAO when netuid is 0).
stake-availability	Free vs locked stake for a coldkey on one subnet.
stake-availability-for-coldkey	Free vs locked stake for a coldkey across many subnets (one runtime call).
stake-for-coldkey	Every stake position held by a coldkey, across all hotkeys and subnets.
stake-for-coldkeys	Every stake position for several coldkeys at once, in one runtime call.
stake-value-for-coldkey	A coldkey's stake marked to TAO at spot prices (excludes slippage/fees), block-pinned.
stake-value-for-coldkeys	Spot-price stake valuation for several coldkeys at once, at one block.
staking-hotkeys	Every hotkey associated with a coldkey's staking or root-basket state.
total-alpha-staked	Total alpha currently staked on a subnet, across all hotkeys (TAO when netuid is 0).
validator-basket	A validator's basket holdings: per subnet, the alpha held and its TAO value.
validator-basket-nav	A validator's basket net asset value in TAO (realizable quote).
validator-basket-summary	Everything about one validator's basket, in a single call.
validator-root-weights	A validator's root dividend distribution vector (basket weights).

Subnets

Query	Summary
burn	Current burn (recycle) cost to register on a subnet.
commit-reveal-enabled	Whether commit-reveal weights are enabled on a subnet.
mechanism-count	Current mechanism count configured for a subnet.
mechanism-emission-split	Emission split between mechanisms on a subnet.
metagraph	The full metagraph for a subnet in one call (stakes, ranks, emissions, axons, ...).
subnet	Tempo, burn, and neuron count for one subnet (the three reads run concurrently).
subnet-hyperparameters	All hyperparameters for a subnet, as a flat name -> raw value mapping.
subnet-identity	The identity metadata of a subnet, or None.
subnet-names	Registered name of every subnet that published an identity, keyed by netuid.
subnet-registration-cost	Current cost to register a new subnet.
subnet-start-schedule	When a registered subnet can call start_call.
subnets	Info for every subnet, fetched in four batched map queries rather than
token-symbols	Chain-registered token symbol of every subnet, keyed by netuid.

Weights & bonds

Query	Summary
bonds	Validator bond rows as {validator_uid: {miner_uid: bond}}, scaled to 0..1.
timelocked-weight-commits	Pending (still-encrypted) commit-reveal weight commits, grouped by epoch.
weights	Validator weight rows as {validator_uid: {miner_uid: fraction}}, each row summing to 1.