Get started
Key concepts
Bittensor is a network of subnets, each producing a different kind of AI work, paid for in TAO. These are the ideas you will meet in the API's field names. For the longer story, see What is Bittensor?
TAO and rao
TAO (τ) is the network's currency. Its smallest unit is the rao: 1 τ is 1,000,000,000 rao. The API sends every amount as a string of whole rao, so nothing is lost to floating point. Read them with a decimal or big-integer type and divide by 10⁹ only when you display them.
The field name tells you the unit. stake_spot_tao_rao is TAO in rao; price_usd is US dollars; take_ratio is a fraction (0.18 is 18%).
Subnets and alpha
A subnet is a market for one kind of work: inference, training, storage, data and more. There are 128 today, plus the root network. Each sits in a numbered slot, its netuid; root is 0.
Every subnet has its own token, called alpha, and a pool that holds TAO and alpha. The ratio of the two sets the alpha price: price_tao is what one alpha costs in TAO. Alpha amounts use the same base unit as TAO (_alpha_rao, 10⁹ per alpha), but they are a different asset on each subnet, so never add alpha from two subnets together.
Slots are reused. When a subnet is deregistered, a new one can take its netuid. The generation field tells the lives of a slot apart, and history endpoints say which life a figure belongs to.
Coldkeys and hotkeys
Bittensor accounts come in two roles:
- A coldkey is a wallet. It holds TAO and owns stake. When you look up “an account”, you usually mean a coldkey.
- A hotkey is the working key of a miner or validator, registered on one or more subnets. Coldkeys stake on hotkeys. A hotkey has an owner coldkey.
Both are SS58 addresses starting with 5 (prefix 42). Some fields return an address as {ss58, hex}, the same key in both encodings. Bittensor also runs an EVM, whose addresses are 0x hex and whose amounts are in wei (_wei, 10¹⁸ per TAO).
Staking and validators
Staking puts TAO behind a validator's hotkey on a subnet. On a subnet, the TAO is swapped through the pool into that subnet's alpha, so a stake position is an amount of alpha held by a coldkey, on a hotkey, on one subnet. On root, stake stays in TAO.
A position's value in TAO moves with the alpha price, and swapping in or out costs something, more for larger amounts. The quote endpoints tell you what a stake or unstake would get you now. Validators keep a share of their stakers' rewards, their take (take_ratio).
Emissions and epochs
New TAO and alpha are issued every block. Each subnet gets a share of the network's emission (emission_share_1d_ratio), and pays its own out to miners, validators and the subnet owner at the end of each epoch. An epoch lasts tempo blocks: 360 on most subnets, about 72 minutes.
Blocks and finality
A block is produced about every 12 seconds. Each holds extrinsics (the transactions, signed or not), the calls they dispatched, and the events the chain emitted as a result. Blocks are numbered by height.
Answers about chain state say which block they reflect, in meta.at, and whether that block is finalized (it can no longer change). Many endpoints take at to read the past: a block height, a block hash or a time.
Unknown is not zero
When the API does not know a value, it sends null. That means “not known”, never 0. Show it as missing, and leave it out of sums rather than counting it as nothing. A total built from some known parts and some unknown ones is a lower bound, and several responses say so with a flag such as total_is_lower_bound.
Next: make a first request in the quickstart, or copy one from Common tasks.