EVM TAO per day: the native TAO held by EVM addresses, per UTC day
https://api.bittensor.ai/api/v2/evm/tao/daily- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Beta. An EVM address's native TAO sits in its Substrate mirror account (blake2_256("evm:" ++ h160)): every H160 seen in an EVM transaction has one.
Full description
Beta. An EVM address's native TAO sits in its Substrate mirror account (blake2_256("evm:" ++ h160)): every H160 seen in an EVM transaction has one. One row per UTC day, oldest first: the mirrors' free, reserved and staked TAO at the day end and their total (an unavailable stake leg counts 0: total_is_lower_bound), the TAO in bridge escrow and wrapper reserves and the total without the bridge escrow, the day's TAO in, out and net between mirror and other accounts, the holder count, and reconciliation figures (mirror_count, tao_internal_rao, first_seen_count, first_seen_opening_tao_rao). Every null figure carries its reason (*_unavailable_reason). The open day (today, is_open_day) comes last when the window reaches it; its flows are null (day_flows_unavailable_reason open_day). Days whose history is still being prepared are rows with unavailable_reason not_ready and every figure null. Window: from_day..to_day (inclusive UTC days) or the days ending at to_day (default 30); to_day defaults to today. At most 366 days. Cached as the head. Errors are application/problem+json: INVALID_DAY, INVALID_DAYS, INVALID_RANGE (from_day with days, from_day after to_day, to_day after today, over 366 days), UNKNOWN_PARAMETER; SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503: this deployment's data source is not configured, or does not serve the EVM TAO views yet), SERVICE_UNAVAILABLE (503).
Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).
Query parameters
- from_dayquery· string (date)
The first UTC day,
YYYY-MM-DD, inclusive. Not withdays(400INVALID_RANGE); not a date a 400INVALID_DAY.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
The last UTC day,
YYYY-MM-DD, inclusive (default: today, the open day). After today a 400INVALID_RANGE.- Format: date, YYYY-MM-DD
- daysquery· integer · 1 to 366
The days ending at
to_day, 1..366 (default 30). Not withfrom_day.
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.
One row per day the source has, oldest first; the open day (today) last when the window reaches it. A day before the EVM history has no row.
- daystring (date)
The UTC day.
- Format: date, YYYY-MM-DD
- day_end_heightinteger · unit block · can be null
The day's last block; null on the open day and on a day not available yet.
- is_open_dayboolean
Today (UTC), still moving: its figures change until the day closes.
- as_of_heightinteger · unit block · can be null
The block the row's figures are as of:
day_end_height, or on the open day the holder dataset's head; null when the source states none (meta.atis the source's head).- free_tao_raostring · unit rao (÷1e9) · can be null
Sum of the mirrors'
data.freeat the day end, in rao. Null withunavailable_reason.- Format: whole number, as a string · on chain: u64
- reserved_tao_raostring · unit rao (÷1e9) · can be null
Sum of the mirrors'
data.reserved, in rao. Null withunavailable_reason.- Format: whole number, as a string · on chain: u64
- staked_tao_raostring · unit rao (÷1e9) · can be null
The mirrors' stake at spot value on
staked_as_of_day, in rao. Null withstaked_tao_rao_unavailable_reason(orunavailable_reason).- Format: whole number, as a string · on chain: u64
- total_tao_raostring · unit rao (÷1e9) · can be null
free + reserved + staked, in rao; an unavailable stake leg counts 0 (
total_is_lower_bound). Null withunavailable_reason.- Format: whole number, as a string · on chain: u64
- total_is_lower_boundboolean · can be null
True when the stake leg is unavailable and counted as 0: the real total is at least
total_tao_rao. It qualifiestotal_tao_rao, so it is null exactly where the total is: on a row withunavailable_reason(not_ready); never null on a available day.- bridge_escrow_tao_raostring · unit rao (÷1e9) · can be null
Of
total_tao_rao: all legs (free + reserved + staked) of thebridge_escrowaddresses (TAO locked against tokens on other chains), in rao. Null withbridge_escrow_tao_rao_unavailable_reason.- Format: whole number, as a string · on chain: u64
- wrapper_reserve_tao_raostring · unit rao (÷1e9) · can be null
Of
total_tao_rao: all legs of thewrapper_reserveaddresses (the TAO backing wrapper tokens on this chain), in rao. Null withwrapper_reserve_tao_rao_unavailable_reason.- Format: whole number, as a string · on chain: u64
- total_excl_bridge_escrow_tao_raostring · unit rao (÷1e9) · can be null
total_tao_rao-bridge_escrow_tao_rao, in rao: the TAO on the EVM side without what backs tokens on other chains. The wrapper reserve stays in it. Null withtotal_excl_bridge_escrow_tao_rao_unavailable_reason.- Format: whole number, as a string · on chain: u64
- tao_in_raostring · unit rao (÷1e9) · can be null
TAO into mirror accounts from non-mirror accounts during the day, in rao. Null with
day_flows_unavailable_reason.- Format: whole number, as a string · on chain: u64
- tao_out_raostring · unit rao (÷1e9) · can be null
TAO out of mirror accounts to non-mirror accounts during the day, in rao. Null with
day_flows_unavailable_reason.- Format: whole number, as a string · on chain: u64
- tao_net_raostring · unit rao (÷1e9) · can be null
tao_in_rao-tao_out_rao, in rao (signed). Null withday_flows_unavailable_reason.- Format: whole number, as a string · can be negative
- holder_countinteger · unit count · can be null
Mirror accounts holding free + reserved + staked > 0 at the day end. Null with
unavailable_reason.- staked_as_of_daystring (date) · can be null
The UTC day the stake is valued on (the stake history's newest closed day). Null until loaded.
- Format: date, YYYY-MM-DD
- mirror_countinteger · unit count · can be null
Reconciliation: the mirror accounts counted that day. An EVM address counts from the first block its mirror account held TAO, or from its first EVM activity if that is earlier. The zero address and protocol precompiles (0x0…0x0fff) are excluded. Past days can be revised upward when an address's first EVM activity appears later; the revision covers every earlier day its mirror held TAO. Null with
unavailable_reason.- tao_internal_raostring · unit rao (÷1e9) · can be null
Reconciliation: TAO moved mirror to mirror during the day (netted out of in and out), in rao. Null with
day_flows_unavailable_reason.- Format: whole number, as a string · on chain: u64
- first_seen_countinteger · unit count · can be null
Reconciliation: mirror accounts first counted that day. Null with
day_flows_unavailable_reason.- first_seen_opening_tao_raostring · unit rao (÷1e9) · can be null
Reconciliation: free, reserved and staked TAO of newly counted mirrors at the previous day end, entering the totals without a flow, in rao; usually 0, since funding arrives as an incoming transfer. Null with
day_flows_unavailable_reason.- Format: whole number, as a string · on chain: u64
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_DAY
- INVALID_DAYS
- INVALID_RANGE
- 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.