Using the API
Requests and responses
The rules every endpoint follows: how to authenticate, what an answer looks like, how errors, paging and units work, how rate limits behave and how changes are announced. New to the API? Start with the quickstart.
Overview
The API is served at https://api.bittensor.ai/api/v2 and returns JSON. It covers blocks, extrinsics, calls and events; accounts, balances, stake and identities; subnets, validators and staking; portfolio history; markets and trades; and the Bittensor EVM.
Every successful JSON answer is an object with data and meta, except the integration feeds, which use the third party's format. On chain data, meta.at is the block the answer is for: its height, hash and time, and whether it is finalized. Anything retired is deprecated with notice first (see Versioning).
Getting access
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 [email protected]. Use of the API is covered by the Terms of Service.
Authentication
Send your key on every request, either as a bearer token in the Authorization header or in the X-API-Key header. Both carry the same key with the same access and limits:
curl "https://api.bittensor.ai/api/v2/subnets?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.bittensor.ai/api/v2/subnets?limit=10" \
-H "X-API-Key: YOUR_API_KEY"Send one key, in one header, and never in a URL. Two different keys in the two headers are refused with 401 AMBIGUOUS_CREDENTIALS. A request without a valid API key or OAuth access token gets 401 UNAUTHORIZED. Only the API documents need no credential: /api/v2/openapi.json, /api/v2/openapi/{version}.json and /api/v2/stream/asyncapi.json.
OAuth 2.0 access tokens from the authorization-code flow are accepted in Authorization: Bearer on the data-read endpoints and on endpoints for the signed-in user. Client-credentials tokens are not accepted. To send an API key together with an access token, put the key in X-API-Key.
Keep your key secret. Don't put it in client-side code or public repositories.
OpenAPI spec
The full public specification is at https://api.bittensor.ai/api/v2/openapi.json. It can be fetched without a key and lists every public endpoint, parameter and response schema, grouped by tag (accounts, subnets, blocks and extrinsics, EVM and more).
curl -o openapi.json https://api.bittensor.ai/api/v2/openapi.jsonEndpoints that are not in this spec are not part of the public API, even if you can find them. info.x-content-hash changes whenever the document does, so a generated client can tell when it is out of date.
Errors
Every error is an RFC 9457 problem document, served as application/problem+json:
type,title,statusanddetail, as RFC 9457 defines themcode: an upper-case code such asINVALID_LIMITorRATE_LIMITED. Branch on this, not ondetailrequest_id: the same id as theX-Request-Idheader. Include it when you contact userrors: one entry per bad parameter (param,code,detail), empty when there is none
Invalid parameters are a 400, and so is an unknown query parameter (UNKNOWN_PARAMETER): a misspelt filter is refused rather than ignored. Each operation lists the codes it can return in x-error-codes in the spec, and x-error-catalogue, at the top level of the spec, lists every code with its status, what it means and what to do. The same list is on API errors, with a page for each code (for example /docs/errors/invalid-cursor).
A key without the data:read scope gets 403 INSUFFICIENT_PERMISSIONS. A 503 means the data is briefly unavailable (for example SOURCE_TIMEOUT, or RECALCULATING on the cost-basis routes): retry after Retry-After seconds when the answer sends it. A few 503 codes describe a state that lasts, such as SOURCE_NOT_READY: retrying does not help there, and each code's page says whether it does.
Pagination
Most lists are paged with a cursor. Set the page size with limit (each operation gives its range and default in the spec); the answer's meta.page.next_cursor fetches the next page, and is null on the last one. Three lists page by offset with a total instead (/validators, /leaderboard and /hotkeys/{hotkey}/stakers), and /subnets and /accounts/{address}/positions return every row when limit is left out.
curl "https://api.bittensor.ai/api/v2/blocks?limit=100&cursor=NEXT_CURSOR" \
-H "Authorization: Bearer YOUR_API_KEY"Pass the cursor back unchanged, with the same other parameters. It is tied to them: a cursor that was altered or is sent with different parameters is a 400 INVALID_CURSOR. Cursors are at most 200 characters on most routes (up to 4,000 on some); a longer one is also a 400 INVALID_CURSOR.
Units and formats
Numeric fields carry their unit in the spec. x-unit names the unit (for example rao, alpha_rao, usd, ratio or block), and x-convert gives the conversion to a display value (÷1e9 for rao).
Field names carry their unit as a suffix:
_tao_rao: TAO amounts as integer strings in rao (1 τ = 10⁹ rao), so they never lose precision. Convert them with a decimal or big-integer type, not a float._alpha_rao: a subnet's alpha in the same base unit (10⁹ per alpha), also as integer strings.- Other
_raofields: integer strings in the same base unit, but not always of TAO. Theirx-unitsays which. _wei: EVM amounts in wei (÷1e18), as integer strings._usd: US dollar values as decimal strings._ratio: a fraction, not a percentage.0.05means 5%._bps: basis points (÷10000).
A few _tao_rao and _alpha_rao fields are objects instead: the cost-basis sums ({amount, complete, excluded_positions}, where amount is the integer string) and the by_type maps (an integer string per key). So are a few _usd and _ratio fields that carry the period or basis they were measured over, such as twr_usd and take_ratio. Their schema says so.
- A
nullvalue means the figure is unknown, never zero. Treat it as missing. - Timestamps are UTC.
Rate limits
A key has limits per minute, hour and/or day (a window can be left without a limit), and on requests in flight at once. Answers to an authenticated request carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the window with the least room left, along with the RateLimit-Policy and RateLimit headers (an IETF draft), when at least one window is limited. When a limit is hit, the API answers 429 with one of these error codes, and names the limit it reached in limit_name:
| Code | Meaning | What to do |
|---|---|---|
| RATE_LIMITED | The key used up a window. Retry-After says when it reopens (and X-RateLimit-Reset, except on the per-IP limit). | 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 (currently 1 second), and lower your parallelism. |
Requests without a valid API key (OAuth access tokens included), with a key that has no per-minute limit, or with a free key also count against 200 requests per minute per IP address. Free keys from one IP also share a small per-IP budget. This limit answers 429 RATE_LIMITED with Retry-After: 60 and none of the X-RateLimit, RateLimit-Policy or RateLimit headers.
Limits can change. If you need more, email [email protected].
Versioning and deprecation
Within /api/v2, a breaking change is never made without notice. 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. Additions (new endpoints, optional parameters, new fields) need no notice.
Beta routes are marked x-stability: beta in the spec (stable routes carry x-stability: stable), and their descriptions end with a Beta note. A beta route can change incompatibly with one release's notice in the API changelog, instead of the deprecation period above. Most routes are beta for now, so check the marker before you build on one. A response field marked x-stability: beta follows the same rule.
Deprecated endpoints announce it in their responses. No /api/v2 endpoint is deprecated today.
Deprecation(RFC 9745) with the date it was deprecatedSunset(RFC 8594) with the removal dateLinkwithrel="deprecation"and, when the replacement is a route,rel="successor-version"pointing at it
In the spec, deprecated items are marked deprecated: true, with x-deprecated-since, x-sunset and x-replacement where a date and replacement are set. Deprecated fields are marked only there: their responses carry no deprecation headers.
Realtime
The REST API described on this page is the supported interface.
AI clients
AI clients can connect to the Bittensor.ai MCP server and sign in with their bittensor.ai account. MCP access is granted per account. Connect an MCP client
Contact
- API access and higher limits: [email protected]
- Security reports: [email protected] (see security.txt)
- Legal: [email protected]
- Privacy: [email protected]