Bittensor Chain Tools

Subnaut can read the Bittensor chain directly. Four tools cover the questions people ask most often: which subnets exist and what they earn, how one subnet is configured, who is in a subnet's metagraph, and what an address holds.

Tool	Answers
bittensor_subnets	Every subnet with its economics: alpha price, market cap, reserves, emission, registration cost, neuron count.
bittensor_subnet	One subnet in depth: identity, owner, epoch timing, reserves, validator counts, registration status, and all hyperparameters.
bittensor_metagraph	One row per neuron in a subnet: keys, stake, incentive, dividends, trust, consensus, emission, validator permit, axon.
bittensor_account	An SS58 address: free balance, stakes held as a coldkey, and registrations held as a hotkey.

The tools belong to the bittensor toolset. They are part of the core tools, so they are on by default in the CLI, the TUI, the desktop app, Telegram, Discord, Slack, cron jobs, the API server and ACP editors. The webhook toolset leaves them out.

Read-only by design

• The tools only read public chain data. They never sign or submit extrinsics, and they never open a wallet or touch key files.
• The model can choose only a named network (finney, test or archive). A custom subtensor endpoint can be set only in config.yaml, so a prompt cannot point Subnaut at an arbitrary socket.
• Subnet names, descriptions and identities are free text that subnet owners write on chain. Subnaut wraps the output of bittensor_subnets, bittensor_subnet and bittensor_metagraph in untrusted-data markers, the same way it wraps web pages, and tells the model to treat that text as data rather than instructions.
• Anything that signs goes through btcli, which Subnaut gates separately: signing always asks you, and key-material commands never run. See Bittensor wallets and btcli.

Example prompts

• "Which subnets pay the most emission right now?" (bittensor_subnets sorted by emission)
• "Show me the validators on subnet 5." (bittensor_metagraph with netuid: 5 and validators_only: true)
• "What is my coldkey 5F… staked in, and what is it worth in TAO?" (bittensor_account)
• "How much does it cost to register a miner on subnet 1, and when is the next epoch?" (bittensor_subnet)
• "Which subnets have the highest market cap on testnet?" (bittensor_subnets with network: test and sort_by: market_cap)

What the tools return

Every successful result is JSON with "success": true and the network it queried. A failure returns {"error": "..."}, plus the network when the query got that far.

bittensor_subnets

Parameter	Default	Notes
netuids	all	Only these subnets.
sort_by	netuid	netuid, price, market_cap, emission, registration_cost or volume. Every order except netuid is descending.
limit	50	Rows to return, at most 256.
network	config	finney, test or archive.

The result carries block, subnet_count (subnets matched before limit), subnet_creation_cost_tao, sort_by, truncated (true when more subnets matched than limit) and subnets. Each subnet row has netuid, name, symbol, owner_coldkey, owner_hotkey, price_tao, market_cap_tao, tao_in, alpha_in, alpha_out, emission_tao_per_block, volume_alpha, tempo, blocks_since_last_step, registration_cost_tao, neurons, max_neurons and registered_at_block.

market_cap_tao is price_tao × (alpha_in + alpha_out).

bittensor_subnet

Takes a required netuid (0 to 65535) and an optional network. The result carries block, a subnet object and a hyperparameters object.

subnet has netuid, name, symbol, identity, owner_coldkey, owner_hotkey, registered_at_block, tempo, blocks_since_last_step, blocks_until_next_epoch, price_tao, moving_price_tao, tao_in, alpha_in, alpha_out, emission_tao_per_block, neurons, max_neurons, active_neurons, validator_permits, max_validators, registration_allowed, registration_cost_tao, immunity_period_blocks and commit_reveal_weights_enabled.

hyperparameters is the subnet's hyperparameter set as the SDK reports it, in chain units.

bittensor_metagraph

Parameter	Default	Notes
netuid	required	Subnet id.
sort_by	incentive	uid, stake, incentive, dividends, emission, trust or consensus. Every order except uid is descending. stake sorts by total_stake_alpha.
validators_only	false	Only neurons that hold a validator permit.
hotkeys	all	Only these hotkey addresses.
limit	50	Rows to return, at most 256.
network	config	finney, test or archive.

The result carries block, netuid, name, neurons (the subnet's neuron count), matched (rows left after filtering), sort_by, truncated and rows. Each row has uid, hotkey, coldkey, active, validator_permit, alpha_stake, root_stake_weight, total_stake_alpha, emission_alpha, incentive, dividends, trust, consensus, pruning_score, registered_at_block, last_update_block, blocks_since_update and axon.

emission_alpha is per epoch. axon is the served host:port, or null when the neuron serves no axon. root_stake_weight is the neuron's root TAO stake already multiplied by the chain's root weight (0.18), which is how root stake counts on the subnet.

bittensor_account

Takes a required SS58 address and an optional network. One address can be a coldkey, a hotkey, or both, so the result answers both ways:

• free_balance_tao: the address's free TAO balance.
• as_coldkey.stakes: one entry per hotkey and subnet the address stakes to, with hotkey, netuid, stake_alpha, value_tao, locked_alpha, emission_alpha and hotkey_registered. as_coldkey.total_stake_value_tao sums value_tao.
• as_hotkey.registered_netuids: the subnets where the address is registered as a hotkey. as_hotkey.registrations gives the uid and stake_alpha for each, up to 32 subnets (registrations_truncated says when there are more). as_hotkey.delegate_take is the hotkey's delegate take, or null when it is registered nowhere.

value_tao is stake_alpha multiplied by the subnet's current price. It is a spot value: unstaking a large position would return less because of slippage.

Units

Field	Unit
*_tao, tao_in	TAO
*_alpha, alpha_in, alpha_out, alpha_stake	Alpha of that subnet
price_tao, moving_price_tao	TAO per alpha
incentive, dividends, trust, consensus, pruning_score	Normalized scores from 0 to 1
block, registered_at_block, last_update_block	Block number
blocks_since_last_step, blocks_until_next_epoch, blocks_since_update, immunity_period_blocks, tempo	Blocks
emission_tao_per_block	TAO per block

Amounts are plain floats rounded to 9 decimal places, which is rao precision. Scores are rounded to 6 decimal places.

Networks and configuration

# ~/.subnaut/config.yaml
bittensor:
  # finney (mainnet) | test | archive | a ws:// or wss:// subtensor endpoint
  network: finney
  # Deadline for one query, in seconds (minimum 5)
  timeout_seconds: 45

• network is used when the model does not pass a network argument. Use finney for mainnet, test for testnet, or archive for a mainnet archive node. To query your own node, set a ws:// or wss:// endpoint here, for example ws://127.0.0.1:9944. Any other value makes the tools return an error.
• timeout_seconds limits each query. When a query runs past it, the tool returns an error and drops that network's connection, and the next call reconnects.

Subnaut keeps one connection per network open for the life of the process, so only the first query on a network pays the connection handshake.

Change a setting with subnaut config set, for example subnaut config set bittensor.network test.

First use: installing the SDK

The tools use the official bittensor Python SDK, which is not part of the base install. The first Bittensor call installs it into Subnaut's own environment from PyPI, using exact pinned versions (bittensor==10.5.0, plus aiohttp, starlette and numpy). This is the same allowlisted lazy install that other optional backends use. That first call takes longer than later ones while the install runs.

To block runtime installs, set:

security:
  allow_lazy_installs: false

With installs blocked and the SDK not installed, Subnaut hides the Bittensor tools from the model. To use them in that setup, install the pinned packages into Subnaut's environment yourself. The bittensor extra in pyproject.toml lists the same pins.

Turning the tools off

The toolset appears as τ Bittensor in subnaut tools, where you can switch it off for any platform. To remove it everywhere at once, add it to agent.disabled_toolsets:

agent:
  disabled_toolsets:
    - bittensor

If you saved a tool selection in subnaut tools before this toolset existed, Subnaut turns it on once when you upgrade. If you then switch it off, it stays off.