Skip to content
TAO$188.31
BTC0.002929
MCap$2.21B
Vol$86.07M

API reference / EVM

EVM TAO per day: the native TAO held by EVM addresses, per UTC day

GET/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 with days (400 INVALID_RANGE); not a date a 400 INVALID_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 400 INVALID_RANGE.

Format: date, YYYY-MM-DD
daysquery· integer · 1 to 366

The days ending at to_day, 1..366 (default 30). Not with from_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.at is the source's head).

free_tao_raostring · unit rao (÷1e9) · can be null

Sum of the mirrors' data.free at the day end, in rao. Null with unavailable_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 with unavailable_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 with staked_tao_rao_unavailable_reason (or unavailable_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 with unavailable_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 qualifies total_tao_rao, so it is null exactly where the total is: on a row with unavailable_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 the bridge_escrow addresses (TAO locked against tokens on other chains), in rao. Null with bridge_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 the wrapper_reserve addresses (the TAO backing wrapper tokens on this chain), in rao. Null with wrapper_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 with total_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 with day_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
unavailable_reasonstring · can be null

Why the row's figures are null: not_ready (the day's figures are not available yet: the history is still being prepared; its other reasons are not_ready too). Null on an available day. New values may be added; treat unknown values as unavailable.

staked_tao_rao_unavailable_reasonstring · can be null

Why staked_tao_rao is null: unpriced_position or not_ready (the day is not available yet; on the open day, the stake is not loaded yet). Null when it is set. New values may be added; treat unknown values as unavailable.

bridge_escrow_tao_rao_unavailable_reasonstring · can be null

Why bridge_escrow_tao_rao is null on an available day: bridge_feed_not_run (the bridge feed that classifies holdings has not run on the data source) or not_ready. Null when the value is set. New values may be added; treat unknown values as unavailable.

wrapper_reserve_tao_rao_unavailable_reasonstring · can be null

Why wrapper_reserve_tao_rao is null on an available day: bridge_feed_not_run (the bridge feed that classifies holdings has not run on the data source) or not_ready. Null when the value is set. New values may be added; treat unknown values as unavailable.

total_excl_bridge_escrow_tao_rao_unavailable_reasonstring · can be null

Why total_excl_bridge_escrow_tao_rao is null: bridge_feed_not_run or not_ready. Null when it is set. New values may be added; treat unknown values as unavailable.

day_flows_unavailable_reasonstring · can be null

Why the day's flows (tao_in_rao, tao_out_rao, tao_net_rao, tao_internal_rao, first_seen_*) are null: open_day (flows are defined for closed days only) or not_ready. Null when they are set. New values may be added; treat unknown values as unavailable.

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), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, 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). Never immutable. no-store on 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-revalidate and stale-if-error; no-store with X-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, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-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.

From the API's published specification, version 1.165.0.