The taostats API gives you the data behind the explorer, as JSON over plain HTTP: subnets, validators, metagraphs, pools, prices and more. This guide takes you from nothing to a first response, then through the patterns you need for real code.
It is a read-only API. You can look at accounts and balances, blocks and extrinsics, subnet configuration, validators and miners, dTAO pools and prices, but you cannot sign or send a transaction through it. That keeps the mental model simple: every call is a question about the state of the network, and every response is an answer you can cache, store or chart however you like.
What you can build
Because it is the same data that powers the explorer, most projects fall into one of three shapes.
- Dashboards and alerts. Poll the latest endpoints for the figures you care about, such as a subnet's emission or a validator's stake, then chart them or notify yourself when they cross a threshold.
- Research notebooks. Many endpoints come in a latest and a history variant. Pull the history into a notebook or a spreadsheet to study how prices, emissions and registrations have moved over time.
- Bots and integrations. Feed subnet data into a chat bot, a portfolio tracker or a tool of your own. If you automate anything that moves money, be careful: the API describes the state of the chain, but it cannot stop you acting on a stale or misread number.
- Sign up at with Google, GitHub or an email address.
- Create an API key from your dashboard. Treat it like a password.
- Store it in an environment variable, and keep it out of source control.
Every endpoint lives under the base URL https://api.taostats.io/api/ and the paths in the reference are relative to it. A good first call is the latest subnet snapshot, which returns each subnet's configuration, emission metrics and participant counts. Ask for five subnets to keep the response small.
bash
curl -H "Authorization: $TAOSTATS_API_KEY" \
"https://api.taostats.io/api/subnet/latest/v1?limit=5"subnets.mjs
const response = await fetch(
'https://api.taostats.io/api/subnet/latest/v1?limit=5',
{ headers: { Authorization: process.env.TAOSTATS_API_KEY } }
);
if (!response.ok) {
throw new Error('Request failed with status ' + response.status);
}
const { pagination, data } = await response.json();
console.log('Page ' + pagination.current_page + ' of ' + pagination.total_pages);
for (const subnet of data) {
console.log(subnet.netuid, subnet.active_validators, subnet.active_miners);
}subnets.py
import os
import requests
response = requests.get(
"https://api.taostats.io/api/subnet/latest/v1",
params={"limit": 5},
headers={"Authorization": os.environ["TAOSTATS_API_KEY"]},
timeout=30,
)
response.raise_for_status()
for subnet in response.json()["data"]:
print(subnet["netuid"], subnet["active_validators"], subnet["active_miners"])Every list endpoint returns the same envelope: a data array and a pagination block.
response-shape.json
{
"pagination": {
"current_page": 1,
"per_page": 5,
"total_items": 5,
"total_pages": 1,
"next_page": null,
"prev_page": null
},
"data": []
}Once you have seen the envelope on one endpoint you have seen it on all of them, which makes it easy to write a single helper that fetches a page, checks the status and hands back the data. Three habits will save you time when you do.
- Paginate. Use
pageandlimitto walk through results; the maximum page size is 200. Follownext_pageuntil it is null. - Parse numbers carefully. Many values, such as prices and emissions, arrive as strings so that no precision is lost. Use a decimal-aware type when you do arithmetic on them.
- Convert units. Token amounts are in RAO, the smallest unit. One TAO is 1,000,000,000 RAO, so divide before you display anything.
Most endpoints accept filters, and using them is the difference between a script that takes a second and one that downloads the whole network. The subnet snapshot, for instance, takes a netuid to fetch one subnet and an order to sort the results, with options such as emission_desc for the subnets that emit the most. The pool endpoint can be sorted by liquidity, price or rank in the same way, and the metagraph endpoint can be filtered by hotkey, coldkey, validator permit and more.
A call for the ten subnets with the largest emission is then a single line:
bash
curl -H "Authorization: $TAOSTATS_API_KEY" \
"https://api.taostats.io/api/subnet/latest/v1?order=emission_desc&limit=10"Each endpoint page in the reference lists the parameters it accepts, and the Try it panel on every GET page lets you run a request from your browser with your own key before you write any code.
| You want to know | Call |
|---|---|
| The current TAO price | GET /api/price/latest/v1?asset=tao |
| How subnets are configured and how much they emit | GET /api/subnet/latest/v1 |
| A subnet's pool price, reserves and fee | GET /api/dtao/pool/latest/v1?netuid= |
| Who is on a subnet, and how they are performing | GET /api/metagraph/latest/v1?netuid= |
The pool endpoint pairs well with our , and the metagraph endpoint with .
The endpoints combine well. A common first project is to take the subnet snapshot for a list of subnets, fetch the pool for each one, and join them on the subnet number to see emission next to price and depth. Because both responses are paginated in the same way, the join is a few lines of code in any language.
- Respect rate limits. Limits depend on your plan. When you exceed yours the API returns
429 Too Many Requests; wait for the time given in theRetry-Afterheader before you retry. - Cache what you can. The latest endpoints describe the chain tip. Reuse a response for a few seconds instead of polling in a tight loop.
- Keep the key on the server. Never ship it in browser code or a mobile app, where anyone can read it.
Wrap your calls in one small helper rather than repeating the same checks everywhere. It should confirm the status code, parse the body, and decide what to do about a failure. A rate-limit response is worth retrying after the delay the server asks for, with a cap on the number of attempts so a bad day does not turn into an infinite loop. A server error deserves a retry with a short, growing pause. Anything else, such as a bad parameter or a rejected key, will not fix itself and should surface as an error straight away. When you log a failure, record the status and the path, and never the key.
Start with curl or the Try it panel while you are exploring, because you see exactly what comes back. Move to plain HTTP calls in the language you already use when you know what you need. Reach for the TypeScript SDK if you want typed responses and do not want to hand-write the request code, and for the MCP server if the thing asking the questions is an AI assistant rather than your own program. They all talk to the same data, so you can mix them freely as a project grows.
A 401 or 403 almost always means the Authorization header is wrong. A 429 means you are over your limit. A 404 usually means the path is missing the /api/ prefix or the /v1 version suffix. Everything else is covered in the quickstart.
