Loading...
Loading
Loading
A REST API for Bittensor chain data, subnets, validators and portfolios, with a public OpenAPI specification. This page covers how to get access, how to authenticate, how rate limits behave and how changes are announced.
The API is served at https://bittensor.ai/api/v1 and returns JSON. It covers chain data (blocks, extrinsics, events, accounts), subnets, validators and staking, and portfolio data for watched wallets.
There is one version, /api/v1. Changes are additive: new fields and endpoints are added, old ones are deprecated with notice before they are removed (see Versioning).
API keys are issued on request. Email [email protected] with a short description of what you are building and the data you need, and we will get back to you with a key.
For higher limits than your key allows, contact us at the same address. Use of the API is covered by the Terms of Service.
Send your key in the X-API-Key header on every request:
curl https://bittensor.ai/api/v1/system/status \
-H "X-API-Key: YOUR_API_KEY"Requests without a key are challenged at the edge and will not reach the API from a script or server. The only exception is the OpenAPI spec itself.
OAuth 2.0 (authorization-code flow) bearer tokens are accepted on the data-read endpoints and on endpoints for the signed-in user, but only alongside an API key when calling from a script or server. Client-credentials tokens are not accepted.
Keep your key secret. Don't put it in client-side code or public repositories.
The full public specification is at https://bittensor.ai/api/v1/openapi.json. It can be fetched without a key and lists every public endpoint, parameter and response schema, grouped by tag (chain data, subnets, system and portfolio).
curl -o openapi.json https://bittensor.ai/api/v1/openapi.jsonEndpoints that are not in this spec are not part of the public API, even if you can find them.
Numeric fields carry their unit in the spec. x-unit names the unit (for example rao, TAO, alpha, basis points, a ratio or a percent), and x-convert gives the conversion to a display value.
null value means the figure is unknown, never zero. Treat it as missing.Each key has request limits per minute, hour and day. Successful responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the window with the least room left. When a limit is hit, the API answers 429 with one of these error codes:
| Code | Meaning | What to do |
|---|---|---|
| RATE_LIMITED | The key used up a window. X-RateLimit-Reset and Retry-After say when it reopens. | What to do: Wait until Retry-After. Don't retry in a loop. |
| CONCURRENCY_LIMIT | Too many requests in flight at once for this key (X-Concurrency-Limit). | What to do: Retry after Retry-After (1 second), and lower your parallelism. |
There is also a per-IP limit that applies before the key is checked. It answers 429 RATE_LIMITED with Retry-After: 60 and no X-RateLimit headers.
Limits can change. If you need more, email [email protected].
Paths, operation IDs and schema names stay stable within /api/v1. When something is retired, it is deprecated first and removed only after the notice period: at least 90 days for a field or parameter, and at least 6 months for an endpoint.
Deprecated endpoints announce it in their responses:
Deprecation (RFC 9745) with the date it was deprecatedSunset (RFC 8594) with the removal date, once one is setLink with rel="deprecation" and rel="successor-version" pointing at the replacementIn the spec, deprecated items are marked deprecated: true, with x-sunset and x-replacement where a date and replacement are set.
WebSocket and server-sent event feeds for live chain activity are coming soon. The API is REST only for now.
AI clients can connect to the Bittensor.ai MCP server and sign in with their bittensor.ai account. Connect an MCP client