Skip to content
TAO$188.36
BTC0.002929
MCap$2.22B
Vol$86.25M

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.json

Endpoints 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, status and detail, as RFC 9457 defines them
  • code: an upper-case code such as INVALID_LIMIT or RATE_LIMITED. Branch on this, not on detail
  • request_id: the same id as the X-Request-Id header. Include it when you contact us
  • errors: 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 _rao fields: integer strings in the same base unit, but not always of TAO. Their x-unit says which.
  • _wei: EVM amounts in wei (÷1e18), as integer strings.
  • _usd: US dollar values as decimal strings.
  • _ratio: a fraction, not a percentage. 0.05 means 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 null value 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:

RATE_LIMITEDThe 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_LIMITToo 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 deprecated
  • Sunset (RFC 8594) with the removal date
  • Link with rel="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