A basket fund's NAV at every UTC hour or day end
https://api.bittensor.ai/api/v2/baskets/{hotkey}/nav- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
A validator's basket fund over the days before the series' head.
Full description
A validator's basket fund over the days before the series' head (meta.at), ascending: at every UTC hour end (interval=hour, the default: the runtime's basket valuation at the hour's last block) or day end (interval=day): units outstanding, realizable and spot NAV, the realizable NAV per unit and, on day rows only, the day-end pricing (display_price, stake_price, staker_twr, as GET /baskets/{hotkey}'s pricing); an hour series serves those three null and names them in meta.daily_only. A window older than the series' coverage has fewer rows (never padded). Moves with every closed hour or day: cached as slow. Every row says day_status (closed | open) and as_of_height. With interval=day, to_day either ends the day rows at a closed day's close, final only (a day not available yet is a 503 NOT_READY, one after meta.final_through_day a 503 NOT_FINAL, never an earlier day; still slow: the window's start follows the head) or, as today's date, adds today's open row after them (the fund's newest NAV reading since the close; an opt-in: never in a default answer; cached as tip). Day window: from_day (or cursor, or to_day with interval=hour) asks for calendar days instead: day rows from_day..to_day (pages of 366 days) or every hour of those days (pages of 31; to_day default today, its hours so far), no days ceiling, meta.page.next_cursor continuing with cursor, meta.range the whole request and meta.from_day / meta.to_day the page's days; a past to_day final or refused as above. While paged day windows are not available yet, those parameters are a 503 SOURCE_NOT_READY. Errors are application/problem+json: INVALID_ADDRESS, INVALID_INTERVAL, INVALID_DAYS (1..30 for hours, 1..365 for days without the day-window parameters), INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, NOT_FOUND (404: no fund on the hotkey), UNKNOWN_PARAMETER, NOT_READY (503), NOT_FINAL (503), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503). meta.final_through_day is the key to cache closed days by: the rows through it never change again (but by an announced rerun); later rows may (null on an older data version's answer).
Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).
Path parameters
- hotkeypath, required· string
The validator's hotkey: SS58, or 0x + 64 hex.
Query parameters
- intervalquery· enum · one of hour, day · default hour
hour(the default: every UTC hour end) orday(every UTC day end, with the day-end pricing). Anything else is a 400INVALID_INTERVAL.- daysquery· integer · at least 1
The window in days: 1..30 for
interval=hour(default 7, at most 720 hour ends), 1..365 forinterval=day(default 90). Withfrom_day/cursor(or an hour series'to_day): the calendar days ending atto_day, no page ceiling (at most 1,000,000), never withfrom_day(both: a 400INVALID_RANGE). Anything else is a 400INVALID_DAYS.- to_dayquery· string (date)
A UTC day,
YYYY-MM-DD.interval=day: before today, the day rows end at that day's close (withoutfrom_daythe window still startsdaysbeforemeta.at); a day not available yet is a 503NOT_READY, one available but aftermeta.final_through_daya 503NOT_FINAL(retry; never an earlier day). Today: the closed days plus today's open row (the opt-in).interval=hour: the last calendar day whose hours are served (today: its hours so far). After today: a 400INVALID_RANGE; anything else a 400INVALID_DAY. Omitted: closed rows only, to the series' head.- Format: date, YYYY-MM-DD
- from_dayquery· string (date)
The first UTC day,
YYYY-MM-DD, inclusive (raised to the first available day:meta.range.from_day_raised). Not withdays(both: a 400INVALID_RANGE); afterto_day: a 400INVALID_RANGE; not a date: a 400INVALID_DAY.- Format: date, YYYY-MM-DD
- cursorquery· string · up to 200 characters
meta.page.next_cursorof the previous page: the next days of a range longer than one page, sent back unchanged with the same other parameters (a changed or altered one is a 400INVALID_CURSOR). While paged day windows are not available yet: 503SOURCE_NOT_READY.
Response
data is a list of objects with these fields. Amounts are integer strings in their base unit, and null means unknown, never zero (see Units and formats). meta.at names the block the answer was read at.
Ascending, one row per UTC hour end (interval=hour) or day end (interval=day) inside the days before meta.at (at most 24 x days hours / days days, plus one where the window's edges cut two buckets); fewer where the series' coverage starts later (never padded).
- timestring (date-time)
The timestamp of the bucket's last block (an hour end: the hour's last block; a day end: the day's), RFC 3339 UTC. One row per UTC hour or day, ascending (checked).
- Format: date and time, ISO 8601 in UTC
- heightinteger · unit block
That block: every figure of the row is read there.
- units_outstandingstring · unit count
BasketShares: the fund's units outstanding (units, not TAO).
- Format: whole number, as a string
- display_pricestring · unit coefficient · 12 decimals · can be null
(spot NAV / units) / BetaBaseline.price_divisor: the fund's price spliced onto the bag index (a level), 12 decimals;
pricing.display_priceofGET /baskets/{hotkey}. Null while provisional. Day rows only: null on every hour row (meta.daily_onlynames it).- Format: decimal number, as a string · can be negative
- stake_pricestring · unit coefficient · 12 decimals · can be null
tr_splice x BasketTwr: the staker's price line (a level), 12 decimals. Null while provisional or without a BasketTwr (with
staker_twr, checked). Day rows only: null on every hour row (meta.daily_onlynames it).- Format: decimal number, as a string · can be negative
- staker_twrstring · unit coefficient · 12 decimals · can be null
BasketTwr: the staker total-return level since the life's start (not annualised), 12 decimals. Null with
stake_price. Day rows only: null on every hour row (meta.daily_onlynames it).- Format: decimal number, as a string · can be negative
- stake_index_levelstring · unit coefficient · 12 decimals · can be null
The stake index level at the day end (BetaIndexSnapshot), 12 decimals: the benchmark line beside
stake_price. Null without a pricing row that day, and on an answer read before the source served it. Day rows only: null on every hour row (meta.daily_onlynames it).- Format: decimal number, as a string · can be negative
- bag_index_levelstring · unit coefficient · 12 decimals · can be null
The bag index level at the day end (BetaIndexSnapshot), 12 decimals: the benchmark line beside
display_price. Null asstake_index_level. Day rows only: null on every hour row (meta.daily_onlynames it).- Format: decimal number, as a string · can be negative
- day_statusstring
closed: a finished UTC hour or day end.open(interval=dayonly): today so far, served only withto_day= today (the opt-in; never by default), as the last row: the fund's newest NAV reading since the last close (a non-close valuation or the latest UTC hour end), its block possibly abovemeta.at; the day-end-only members (display_price,stake_price,staker_twr, the index levels) null. A closed day is final at or beforemeta.final_through_day; a closed day after it is still being finalised (the nightly close, typically minutes after 00:00 UTC, or an announced repair). The open row is today so far (it moves with every reading). On an answer read before the source served this member every row isclosed. New values may be added; show an unknown value as is (or generically).- as_of_heightinteger · unit block · can be null
The block the row reads: its
height(checked). Null on an answer read before the source served it.
Response headers
10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- ETag
Strong validator of this answer. Send it back as
If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.- Cache-Control
One of three classes: settled
public, max-age=3600, stale-while-revalidate=86400(pinned to a block that cannot move), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, max-age=6, stale-while-revalidate=12(follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Neverimmutable.no-storeon an earlier answer served because the data source failed (X-BTAI-Stale).- CDN-Cache-Control
The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with
stale-while-revalidateandstale-if-error;no-storewithX-BTAI-Stale.- X-BTAI-Stale
Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then
if-error, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.- X-BTAI-Stale-As-Of
With
X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).- RateLimit-Policy
The tier's request quota of the current window (IETF draft), e.g.
"tier";q=600.- RateLimit
Requests left in the current window and the seconds until it resets (IETF draft), e.g.
"tier";r=597;t=42.- X-RateLimit-Limit
The tier's request quota of the current window.
- X-RateLimit-Remaining
Requests left in the current window.
- X-RateLimit-Reset
When the current window resets, Unix seconds.
Status codes
200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503
304 Not Modified: the If-None-Match validator still matches; no body.
Error codes
The codes this endpoint can return. Each links to what it means and what to do.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_CURSOR
- INVALID_DAY
- INVALID_DAYS
- INVALID_INTERVAL
- INVALID_RANGE
- NOT_FINAL
- NOT_FOUND
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.