Quickstart

Install, connect, read chain state, and submit your first transaction.

View as Markdown

1. Install

Requires Python 3.10–3.13:

uv venv && source .venv/bin/activate
uv pip install bittensor

One install gives you both the bittensor Python library and the btcli command. In anything unattended, pin the exact version and upgrade only to announced releases — see supply-chain risk.

2. Configure once

btcli config set network finney   # or `test` for testnet, `local` for a dev node
btcli config set wallet my_coldkey
btcli config get                  # show the whole config

Precedence, highest first: CLI flag > environment variable > config file > built-in default. So btcli -n test query tx-rate-limit overrides the configured network for that one call. The environment variables are BT_NETWORK, BT_WALLET, BT_WALLET_HOTKEY, BT_WALLET_PATH.

3. Create or import a wallet

btcli wallet create -w my_coldkey                # new coldkey + hotkey
btcli wallet regen-coldkey -w my_coldkey         # import from mnemonic (prompted securely)
btcli wallet list

A wallet has two keys: the coldkey holds funds and signs financial operations; the hotkey identifies you on subnets and signs operational calls (weights, serving). See Wallets and keys.

4. Read chain state

Reads are free and unsigned. On the CLI (add --json for machine output):

btcli wallet balance my_coldkey
btcli subnets list
btcli query metagraph --netuid 1
btcli query --help          # all 70+ reads, grouped by topic

In Python:

import bittensor as bt

sub = bt.Subtensor()                       # defaults to finney; connects lazily
bal = sub.balances.get("5F...coldkey")
subnets = sub.subnets.all()
mg = sub.subnets.metagraph(netuid=1)

No close() needed — the connection is cleaned up automatically. The same class is the async client when awaited:

import asyncio
import bittensor as bt

async def main():
    async with bt.Subtensor() as client:
        bal = await client.balances.get("5F...coldkey")

asyncio.run(main())

5. Submit a transaction

Every mutation supports --dry-run: it shows the fee, the predicted effects, and any policy verdict without submitting anything.

btcli tx transfer --dest 5F...dest --amount-tao 1.5 --dry-run
btcli tx transfer --dest 5F...dest --amount-tao 1.5 -w my_coldkey

In Python the same two-step shape is plan then execute:

import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = bt.Transfer(dest_ss58="5F...", amount_tao=1.5)

sub = bt.Subtensor()
plan = sub.plan(intent, wallet)      # fee, effects, warnings — nothing submitted
result = sub.execute(intent, wallet)
if not result.success:
    print(result.error.code, result.error.remediation)

Next