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.