# Docs for AI agents

How to point Claude, ChatGPT, Cursor or your own agent at the Taostats docs, the MCP server and the API.

_Source: https://beta.taostats.io/docs/ai-agents_

_Last reviewed: 2026-09-17_

These docs are written for people and for agents. Everything a reader sees on a
page is also available as plain markdown, and the whole corpus is indexed in a
single file. Nothing here needs an API key or a browser.

## Read a page as markdown

Append `.md` to any docs URL:

```shell
curl https://taostats.io/docs/start-here/faq.md
```

The response is `text/markdown`. It starts with the page title, its one-line
description, a `_Source:_` line pointing back at the HTML page, and the date a
human last checked the page for accuracy. Links and images are absolute, so the
markdown stands on its own once it is out of context.

Every page has one. On the page itself, **Copy page** in the toolbar puts the
same markdown on your clipboard, and **View as Markdown** opens it.

### Or ask for markdown with `Accept`

If your client sends an `Accept` header, you do not need the `.md` suffix. A
request for a docs page that prefers `text/markdown` gets the markdown twin
from the page URL itself:

```shell
curl -H "Accept: text/markdown" https://taostats.io/docs/concepts/staking/slippage
```

`text/markdown` has to be preferred at least as much as `text/html`, so a
browser, or `curl` with its default `Accept: */*`, still gets HTML. Negotiated
responses are sent with `Cache-Control: private, no-store` and `Vary: Accept`;
fetch the `.md` URL when you want a response you can cache.

Every HTML page also advertises its twin in the response headers, so a crawler
that fetched the HTML can find the markdown without guessing:

```text
Link: </docs/concepts/staking/slippage.md>; rel="alternate"; type="text/markdown"
```

## Index the whole corpus

Two generated files cover the full set:

| File | Contents |
| --- | --- |
| [`/llms.txt`](https://taostats.io/llms.txt) | One line per page — title, `.md` URL and description — under `## Section` and `### Group` headings, in the order the sidebar shows. Plus the API, MCP and SDK entry points, and the OpenAPI spec the API reference is generated from. |
| [`/llms-full.txt`](https://taostats.io/llms-full.txt) | Every guide page's markdown, concatenated. The API reference is a separate file, [`/llms-full/api-reference.txt`](https://taostats.io/llms-full/api-reference.txt). |

Both follow the [llmstxt.org](https://llmstxt.org) convention. Start with
`llms.txt` to decide what you need, then fetch the individual `.md` files —
`llms-full.txt` is there for the cases where one request is easier than many.

## Search the docs without an LLM

The search box on these pages runs over a static JSON index you can fetch
yourself:

```shell
curl https://taostats.io/docs-search.json
```

It lists every visible page (`path`, `title`, `navTitle`, `description`,
`keywords`, section and group) and every `##` and `###` heading (`path`,
`anchor`, `text`). An API reference endpoint page is a single entry — its method
and path are in `keywords` — so its headings are not listed. Build
`https://taostats.io/docs/{path}#{anchor}` from an entry to link straight to an
answer. The index changes only when the docs are deployed, so it is safe to
cache for a few minutes.

Every page lives here now, the API reference included, so nothing in these docs
links to `docs.taostats.io`.

## Heading anchors are stable

Every `##` and `###` has an id generated from its text, so you can cite a
specific answer rather than a whole page:

```text
https://taostats.io/docs/start-here/faq#what-is-dtao
https://taostats.io/docs/start-here/glossary#emission
```

The same anchors appear in the `.md` twin, which makes
`{page path}#{anchor}` a usable chunk identifier for retrieval.

## Live data: the MCP server

Docs explain how Bittensor works. They cannot tell you a wallet's balance, this
epoch's emission or which subnets are registering — those change by the block.
For that, connect to the Taostats MCP server:

```text
https://mcp.taostats.io/
```

It exposes the Taostats API as Model Context Protocol tools, so an agent can
look up accounts, subnets, extrinsics, prices and staking state without you
writing a client. You need a Taostats API key; see
[Model Context Protocol (MCP)](https://beta.taostats.io/docs/start-here/model-context-protocol-mcp) for the
setup, and [Getting started with the Taostats API](https://beta.taostats.io/docs/start-here/getting-started-with-taostats-api)
to create the key.

> [!TIP]
> **Docs for structure, MCP for values**
>
> Use the docs to learn what a field means and which endpoint to call. Use MCP to
> read the current value. An agent that guesses a number from documentation prose
> will be wrong within a block.

## Building a client instead

If you are writing code rather than driving a chat model, the
[TypeScript SDK](https://beta.taostats.io/docs/start-here/typescript-sdk) wraps the same API with types, and
adds direct RPC access to the chain for transactions. The REST API base URL is
`https://api.taostats.io/api`; every endpoint is documented in the
[API reference](https://beta.taostats.io/docs/api-reference).

## API key hygiene

A Taostats API key identifies your account and counts against your plan's limits.
Treat it the way you would treat any other credential:

- Keep it in an environment variable (`TAOSTATS_API_KEY`), never in a committed
  file, a prompt, or a rule file that ships with a repository.
- Do not paste it into a chat window. An agent that needs it should read it from
  the environment or from your MCP client's own secret store.
- Give an agent its own key, so you can rotate or revoke that key without
  breaking everything else.
- Rotate keys from [Taostats Pro](https://taostats.io/pro) if one is exposed.

> [!WARNING]
> **Seed phrases are not API keys**
>
> The SDK can sign chain transactions, which means it can take a seed phrase or a
> private key. Never give either to an agent, and never put one in a rule file or a
> prompt. Anything that can sign can move funds.

## Rule-file snippets

Dropping a few lines into your repository's agent instructions saves an agent
from crawling HTML. The wording is the same in each case — only the file name
changes.

**`CLAUDE.md` or `AGENTS.md`** (Claude Code, Codex, and most agent CLIs):

```markdown
## Bittensor and Taostats data

- Taostats docs: append `.md` to any page URL for plain markdown
  (`https://taostats.io/docs/start-here/faq.md`).
- Index of every page: `https://taostats.io/llms.txt`.
  Whole corpus in one file: `https://taostats.io/llms-full.txt`.
- Glossary first: `https://taostats.io/docs/start-here/glossary.md` defines
  alpha, emission, hotkey/coldkey, netuid, tempo and the rest.
- For live values (balances, emissions, prices, metagraph) call the Taostats MCP
  server at `https://mcp.taostats.io/` — never infer a number from the docs.
- The API key lives in `TAOSTATS_API_KEY`. Do not print it or commit it.
```

**`.cursor/rules/taostats.mdc`** — the same content with Cursor's frontmatter:

```markdown
---
description: How to look up Bittensor and Taostats facts
alwaysApply: true
---

- Taostats docs: append `.md` to any page URL for plain markdown.
- Index: https://taostats.io/llms.txt — full corpus: https://taostats.io/llms-full.txt
- Live data: the Taostats MCP server at https://mcp.taostats.io/
- Read the API key from TAOSTATS_API_KEY; never print or commit it.
```

**`.github/copilot-instructions.md`** — Copilot has no import mechanism, so paste
the `AGENTS.md` block above into it verbatim.

## Prompt snippet

For a one-off conversation, this is enough to orient a model:

```text
Taostats documents Bittensor and the Taostats API at https://taostats.io/docs.
Fetch https://taostats.io/llms.txt for the page index, then fetch the .md URL of
the pages you need (any docs page URL + ".md"). Use the glossary for terminology.
Do not state a balance, price or emission figure from the docs — those are live
values; say you need the Taostats MCP server or API for them.
```

## What not to do

- **Do not scrape the HTML.** The `.md` twin is the same content without the
  navigation, and it will not break when the layout changes.
- **Do not cache a page forever.** Each page carries the date it was last
  reviewed; dTao, hyperparameters and API surfaces all move.
- **Do not treat an example value as current.** Sample balances and block numbers
  in these docs are illustrations, dated where it matters.