Skip to content
TAO$188.58
BTC0.002932
MCap$2.21B
Vol$86.73M

Get started

Common tasks

Requests you can copy. Each shows the call in curl and Python, a real response cut down to the fields discussed, and what to check before you use the numbers. Replace YOUR_API_KEY and ADDRESS with your own.

Rank subnets by market cap

/subnets lists every live subnet with its price, market cap and volume. Sort it with sort and order, and read further pages with the cursor from meta.page.next_cursor.

curl "https://api.bittensor.ai/api/v2/subnets?sort=market_cap_spot_tao_rao&order=desc&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
{
  "data": [
    { "netuid": 0,  "name": null,      "price_tao": "1.000000000", "market_cap_spot_tao_rao": "5487351025072242" },
    { "netuid": 51, "name": "lium.io", "price_tao": "0.122424476", "market_cap_spot_tao_rao": "586547451772131" },
    { "netuid": 64, "name": "Chutes",  "price_tao": "0.068309284", "market_cap_spot_tao_rao": "252492149512379" }
  ],
  "meta": {
    "at": { "height": 9480674, "finalized": true, ... },
    "page": { "next_cursor": "eyJvIjoyLCJo…", "limit": 3 }
  }
}

Root (netuid 0) is in the list: its token is TAO itself, so its price is always 1. Leave it out if you only want subnets, and keep the dividing by 10⁹ for display; the 1e9 float above is fine for printing, not for sums.

Read a wallet: balance and stake

/accounts/{address} gives a coldkey's balance and the total of its stake. /accounts/{address}/positions lists each stake position: the hotkey, the subnet, the alpha held and what it is worth now.

curl "https://api.bittensor.ai/api/v2/accounts/ADDRESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.bittensor.ai/api/v2/accounts/ADDRESS/positions?limit=2" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
// GET /accounts/ADDRESS
{
  "data": {
    "free_rao": "1563090854",
    "transferable_rao": "1563090854",
    "stake_spot_tao_rao": "12421265819",
    "total_spot_tao_rao": "13984356673",
    "total_is_lower_bound": false,
    "position_count": 13,
    ...
  }
}

// GET /accounts/ADDRESS/positions
{
  "data": [
    {
      "hotkey": "5G...",
      "netuid": 51,
      "alpha_rao": "1",
      "price_tao": "0.122424993959",
      "value_spot_tao_rao": "0",
      ...
    }
  ],
  "meta": { "page": { "next_cursor": "OTQ4MDcyMTo2…", "limit": 2, "total": 3 }, ... }
}

“Spot” values price alpha at the pool's current price. Selling a large position would get less, because of the swap (see Quote a stake). If total_is_lower_bound is true, some part of the total could not be valued and the figure is a minimum.

Find validators

/validators is the validator directory: stake, take, nominators and the yield stakers got over the last 7 days. It sorts by many columns. This list pages with offset and returns a total, unlike most lists.

curl "https://api.bittensor.ai/api/v2/validators?sort=stake&order=desc&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
{
  "data": [
    {
      "hotkey": { "ss58": "5E...", "hex": "0x..." },
      "take_ratio": "0.000000",
      "stake_spot_tao_rao": "1407424824202218",
      "nominator_apy_7d_ratio": "0.55883413",
      ...
    },
    ...
  ],
  "meta": { "page": { "limit": 3, "offset": 0, "total": 1033 }, ... }
}

Ratios are fractions: a take_ratio of 0.179995 is a take of about 18%. Past yield is not a promise of future yield. Hotkey endpoints go deeper on one validator: its stakers, take changes and performance per subnet.

Quote a stake before you sign

Staking swaps TAO into a subnet's alpha through its pool, so the price you get depends on the amount. /subnets/{netuid}/quote tells you what an amount would get you now. This asks what 10 τ (10,000,000,000 rao) buys on subnet 64:

curl "https://api.bittensor.ai/api/v2/subnets/64/quote?side=stake&amount_rao=10000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
{
  "data": {
    "netuid": 64,
    "side": "stake",
    "amount_in_tao_rao": "10000000000",
    "amount_out_alpha_rao": "146311827756",
    "fee_tao_rao": "5035477",
    "spot_price_tao": "0.068309386785",
    "effective_price_tao": "0.068347174342",
    "price_impact_ratio": "0.000049353809",
    ...
  },
  "meta": { "at": { "height": 9480719, ... }, ... }
}

10 τ buys about 146.31 alpha here, at an effective price a little above the spot price. A quote is for the block in meta.at; the pool moves with every trade, so quote again just before you sign. Use side=unstake with an alpha amount for the other way.

Follow an account’s transfers

/transfers lists transfers of TAO, and of alpha between coldkeys, newest first. Filter by account (either side), from, to, asset, a block or time range, or a minimum amount.

curl "https://api.bittensor.ai/api/v2/transfers?account=ADDRESS&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
{
  "data": [
    {
      "height": 9480718, "time": "2026-11-11T04:46:00.000Z",
      "asset": "alpha", "netuid": 75,
      "amount_rao": null, "alpha_rao": "88242000000", "tao_equivalent_rao": "1504248232",
      "from": "5...", "to": "5...", ...
    },
    {
      "height": 9480427, "time": "2026-11-11T03:47:48.000Z",
      "asset": "tao", "netuid": null,
      "amount_rao": "4523617412", "alpha_rao": null, "tao_equivalent_rao": null,
      ...
    }
  ],
  "meta": { "page": { "next_cursor": "OTQ4MDY3OC0x…", "limit": 25 }, ... }
}

Check asset before you read an amount: a TAO transfer fills amount_rao, an alpha transfer fills alpha_rao and the subnet. The fields that don't apply are null.

Fetch price history

/subnets/{netuid}/candles gives open, high, low and close prices of a subnet's alpha, with volume, from one minute to one week per candle. /prices/tao/candles does the same for TAO in US dollars or another currency.

curl "https://api.bittensor.ai/api/v2/subnets/64/candles?interval=1d&limit=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response (trimmed)
{
  "data": [
    {
      "open_at": "2026-11-10T00:00:00.000Z",
      "open": "0.067880295", "high": "0.068715726",
      "low": "0.067864753", "close": "0.068174971",
      "close_price_usd": "14.873213",
      "volume_tao_rao": "4212910082953",
      "trades": 697,
      ...
    },
    ...
  ],
  ...
}

Prices in open…close are TAO per alpha; the _price_usd fields are dollars. A subnet slot can be reused by a new subnet, so candles cover the current subnet unless you pass generation (see Subnets and alpha).

For anything not covered here, every endpoint is in the reference. Requests and responses covers errors, paging and rate limits.