A basket fund's daily series, returns, benchmarks and validator take
https://api.bittensor.ai/api/v2/baskets/{hotkey}/performance- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
A validator's basket fund at its newest priced UTC day end.
Full description
A validator's basket fund at its newest priced UTC day end (meta.as_of_day): its daily series over days (units, realizable and spot NAV, NAV per unit, the runtime's cumulative deposits and redemptions); its returns as RatioFigures (staker TWR over 7 and 30 days and since the current life's first stamped day, the NAV per unit over 7 and 30 days, and the lifetime return (realizable NAV + redeemed) / deposited - 1, no_deposits for a fund nothing was deposited into); its benchmarks over 7 and 30 days (the stake index against its stake price, the bag index and the subnets, equal and TAO weighted, against its display price: the benchmark's return, the excess, tracking error, beta and information ratio, null unless every day pair of the window has both sides); and the take on its root dividends over 30 days (amounts and ratio). A figure is served only over its whole window, never a shorter one. Moves when the next day is priced: cached as slow. Every series row says day_status (closed | open) and as_of_height; with to_day = today the series also ends with today's open row (the fund's newest NAV reading since the close; an opt-in: never in a default answer; cached as tip), while every windowed figure stays at meta.as_of_day's close. Day window: from_day, a past to_day or cursor computes the answer per request: the series is the priced days from_day..to_day (pages of 366 by cursor, meta.range, the page's meta.from_day / meta.to_day) and every windowed figure is anchored at to_day (meta.as_of_day; final or refused: a day not available or priced yet is a 503 NOT_READY, one after meta.final_through_day a 503 NOT_FINAL, never an earlier day); while paged day windows are not available yet those are a 503 SOURCE_NOT_READY. Errors are application/problem+json: INVALID_ADDRESS, INVALID_DAYS (7..365 without the day-window parameters), INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, NOT_FOUND (404: no priced 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
- daysquery· integer · default 90 · at least 1
The series window in days, 7..365 (default 90); the returns and benchmarks keep their own windows. With a past
to_dayorcursor: the days ending atto_day, 1..1,000,000 (no page ceiling); never withfrom_day(both: a 400INVALID_RANGE). Anything else is a 400INVALID_DAYS.- to_dayquery· string (date)
A UTC day,
YYYY-MM-DD. Today: adds today's open row (day_statusopen) after the closed days (an opt-in; without it the answer is closed days only). A closed day: the window ends there, final or refused, never an earlier day (a day not available yet is a 503NOT_READY, one aftermeta.final_through_daya 503NOT_FINAL; while paged day windows are not available yet, a 503SOURCE_NOT_READY). After today: a 400INVALID_RANGE; anything else a 400INVALID_DAY.- 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 an object 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.
The series and the figures.
- seriesarray of objects
One row per closed UTC day in the
daystometa.as_of_day, ascending (fewer where the fund's history starts later).11 fields in series (each item)
- daystring (date)
The UTC day.
- Format: date, YYYY-MM-DD
- heightinteger · unit block
The day's last block (the fund's close): every figure is read there.
- units_outstandingstring · unit count
BasketShares: the fund's units outstanding (units, not TAO).
- Format: whole number, as a string
- deposited_cum_tao_raostring · unit rao (÷1e9)
The runtime's cumulative deposits into the fund (BasketSummary) over the row's fund life (
life_start_height), rao of TAO; never falls within one life (checked), and can restart where the life changes.- Format: whole number, as a string · on chain: u64
- redeemed_cum_tao_raostring · unit rao (÷1e9)
The runtime's cumulative redemptions (claims) out of the fund over the row's fund life, rao of TAO; never falls within one life (checked), and can restart where the life changes.
- Format: whole number, as a string · on chain: u64
- life_start_heightinteger · unit block · can be null
The fund life the row belongs to: that life's first block (a fund dissolved and re-created starts a new life).
deposited_cum_tao_rao/redeemed_cum_tao_raoare that life's counters, so they can fall only where this changes. Null when not known, and on an answer read before the source served it.- day_statusstring
closed: a finished UTC day (its close).open: today so far, served only withto_day= today (the opt-in; never by default), appended as the last row: the fund's newest NAV reading since the close (a non-close valuation or the latest UTC hour end), its block abovemeta.at, in the last closed row's fund life. The returns, benchmarks and take stay close-based (they never read the open row). 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.
- returnsobject
The returns (RatioFigures).
8 fields in returns
- staker_twr_7dobject
The staker TWR (BasketTwr) over the 7 days to the day.
7 fields in staker_twr_7d
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- staker_twr_30dobject
The same over 30 days.
7 fields in staker_twr_30d
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- staker_twr_since_inceptionobject
BasketTwr at
meta.as_of_day/ at the current life's first stamped day (from_day=meta.twr_from_day, checked) - 1;days_expectedis the days between them.7 fields in staker_twr_since_inception
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- holder_return_7dobject · can be null
Option B's holders' return over 7 days: the very figure of
GET /hotkeys/{hotkey}'sstaking_options.fund.holder_return_7d(one definition; its window closes at that block'sas_of_day, which can differ frommeta.as_of_day; the B block's rules, checked). Null when the source has none, and on an answer read before the source served it.7 fields in holder_return_7d
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- holder_return_30dobject · can be null
The same over 30 days (
staking_options.fund.holder_return_30d).7 fields in holder_return_30d
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- lifetime_returnobject
(realizable NAV + redeemed) / deposited - 1 at
meta.as_of_day, over the runtime's cumulative deposits and redemptions;no_depositswhen nothing was deposited (a migration-seeded fund).7 fields in lifetime_return
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- benchmarksobject
Against the stake index, the bag index and the subnets (equal and TAO weighted), over 7 and 30 days.
2 fields in benchmarks
- 7dobject
Over the 7 days to the day.
4 fields in 7d
- stake_indexobject
BetaIndexSnapshot's stake level against the fund's stake price (tr_splice x BasketTwr).
- bag_indexobject
The bag level against the fund's display price (spot NAV per unit / price_divisor).
- subnets_equal_weightobject
The mean of the subnets' day-end spot returns (a subnet re-registered between two days left out of that pair) against the display price.
- subnets_tao_weightobject
The same weighted by each subnet's TAO reserve at the window's opening day end.
- 30dobject
Over the 30 days to the day.
4 fields in 30d
- stake_indexobject
BetaIndexSnapshot's stake level against the fund's stake price (tr_splice x BasketTwr).
- bag_indexobject
The bag level against the fund's display price (spot NAV per unit / price_divisor).
- subnets_equal_weightobject
The mean of the subnets' day-end spot returns (a subnet re-registered between two days left out of that pair) against the display price.
- subnets_tao_weightobject
The same weighted by each subnet's TAO reserve at the window's opening day end.
- validator_take_30dobject
The take on the hotkey's root dividends over the 30 days to the day.
9 fields in validator_take_30d
- take_tao_raostring · unit rao (÷1e9) · can be null
The validator's take on its root dividends (the daily
root_takeemission), each day valued at its subnet's day-end spot, floored, rao of TAO. Null while a day is unpriced (with the gross, checked).- Format: whole number, as a string · on chain: u64
- gross_root_dividend_tao_raostring · unit rao (÷1e9) · can be null
The gross root dividend: the take + the stakers' queued root claimable, valued the same way (at least the take, checked).
- Format: whole number, as a string · on chain: u64
- take_ratioobject
take_tao_rao/gross_root_dividend_tao_rao, 8 decimals (checked within the amounts' flooring), a 30-dayperiodfigure:price_unknownwhile a day is unpriced,insufficient_historybefore 30 days with dividends.7 fields in take_ratio
- valuestring · unit ratio · can be null
The figure, a signed ratio (1 = 100 %). Null exactly when
unavailable_reasonis set, and served only whendays_ok=days_expected(checked).- Format: decimal number, as a string · can be negative
- kindstring
apy: a compounded annual rate;apr: a simple annual rate;period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).- from_daystring (date) · can be null
The window opens at this UTC day's end (
to_day-days_expected). Null only withnot_readyornot_applicable.- Format: date, YYYY-MM-DD
- to_daystring (date) · can be null
The window closes at this UTC day's end: the block's
as_of_day, at or beforemeta.at's day. Null withfrom_day.- Format: date, YYYY-MM-DD
- days_okinteger · unit count · can be null
Whole UTC days of the window whose inputs are valid, 0..
days_expected: how far a figure short of its window (insufficient_history) has got. Null withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- take_ratio_minstring · unit ratio · 8 decimals · can be null
The lowest daily take / gross root dividend in the window (each day at its spot), 8 decimals, 0..1;
take_ratiolies between it andtake_ratio_max(checked). Null withtake_ratio_max: while a day is unpriced, without a day with dividends, and on an answer read before the source served it.- Format: decimal number, as a string
- take_ratio_maxstring · unit ratio · 8 decimals · can be null
The highest daily take / gross root dividend in the window, 8 decimals, 0..1. Null with
take_ratio_min.- Format: decimal number, as a string
- avg_root_stake_tao_raostring · unit rao (÷1e9) · can be null
The hotkey's mean root stake over the window (root accrual's daily stake), floored, rao of TAO: for the take as a share of stake. Null without a day of root stake, and on an answer read before the source served it.
- Format: whole number, as a string · on chain: u64
- firingsinteger · unit count · can be null
The root-dividend distributions to this hotkey in the window: one firing = one (subnet, block) that credited it. An integer >= 0; null on an older data version's answer.
- unpriced_firingsinteger · unit count · can be null
The firings on a subnet-day with no day-end price, at most
firings. While any is unpriced the TAO amounts (take_tao_rao,gross_root_dividend_tao_rao) andtake_ratioare null (price_unknown), as before (checked). Null on an older data version's answer.- take_unknown_firingsinteger · unit count · can be null
The firings whose take is unknown: always 0, since the take is the chain's own
root_takecredit, never inferred from a rate. Null on an older data version's answer.
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_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.