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[cli]'

The [cli] extra pulls in the terminal UI for the btcli command; plain uv pip install bittensor installs just the Python library. 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 asyncio
import bittensor as sub

async def main():
    async with sub.Client("finney") as client:
        bal = await client.balances.get("5F...coldkey")
        subnets = await client.subnets.all()
        mg = await client.read("metagraph", netuid=1)

asyncio.run(main())

There is a synchronous facade too:

client = sub.SyncClient("finney")
print(client.balances.get("5F...coldkey"))
client.close()

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:

from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")

async with sub.Client("finney") as client:
    intent = sub.Transfer(dest_ss58="5F...", amount_tao=1.5)
    plan = await client.plan(intent, wallet)     # fee, effects, warnings — nothing submitted
    result = await client.execute(intent, wallet)
    if not result.success:
        print(result.error.code, result.error.remediation)

Next