Skip to content
TAO$188.40
BTC0.00293
MCap$2.21B
Vol$86.07M

API reference / EVM

One EVM token

GET/api/v2/evm/tokens/{address}
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

One token (the /evm/tokens row) with transfers_24h: its transfers in the last 7,200 blocks (~24 h), counted when read (up to 1,000; transfers_24h_exact). meta.standards lists the contract's standards (two for a contract emitting both kinds; pick one with standard). The contract's own page (code, verification) is /evm/contracts/{address}. Amounts are raw integer strings (*_raw, unit token_raw): divide by 10^decimals of their token. Balances, holders, supply, NFT owners and approvals are as of meta.computed_through_height (the token ledger's top); meta.at is the source's head, meta.coverage the dataset's range. Cached as the head (the token ledger advances with every block). Errors are application/problem+json: INVALID_ADDRESS, INVALID_KIND, NOT_FOUND (404: no token at this address, or not that standard), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503: this deployment's data source is not configured, or does not have the EVM token views yet).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Path parameters

addresspath, required· string

The token contract, 0x + 40 hex (any case).

Query parameters

standardquery· enum · one of erc20, erc721, erc1155

Which standard's row of a contract that emits two (erc20, erc721 or erc1155). Default: the contract's only row, else the one its metadata describes. Anything else is a 400 INVALID_KIND; a standard the contract does not have is a 404 NOT_FOUND.

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 token (the standard asked for, or the contract's default).

addressstring

The token contract, 0x H160.

Format: EVM address: 0x and 40 hex digits
standardenum

The token standard of this row: erc20, erc721 or erc1155. A contract that emits two kinds of Transfer has a row per standard (meta.standards on its detail).

One of: erc20, erc721, erc1155
namestring · can be null

The token's name() as the contract returns it (attacker-controlled text: render it as text, never as markup). Null when it has none.

symbolstring · can be null

The token's symbol() as the contract returns it (attacker-controlled text). Null when it has none.

decimalsinteger · unit count · can be null

The token's decimals() (the metadata feed): divide its *_raw amounts by 10^decimals. Null: unknown.

is_unnamedboolean

No metadata, or neither a name nor a symbol: show it as an unnamed token, never a guess.

is_verifiedboolean

The contract's source is verified on Sourcify.

is_wrapperboolean

WETH9-style Deposit / Withdrawal events are counted as mints / burns (a TAO wrapper).

is_backedboolean · can be null

A wrapper's native balance covers what its holders are owed, within 500 rao (the existential deposit): the hourly check's authoritative verdict (the figures are in peg). Null: not checked (every non-wrapper, alpha-backed wrappers for now: backing unknown; also when the check's balance read failed or the token's balances are suspect). Only TAO-backed wrappers (WETH9-style: Deposit / Withdrawal against the contract's native TAO) are checked, hourly; alpha-backed wrappers are not checked yet (backing unknown: peg null).

total_supply_rawstring · unit token_raw (÷10^decimals) · can be null

totalSupply() at metadata_height, raw units. Null when the contract has none (most erc721).

Format: whole number, as a string
computed_supply_rawstring · unit token_raw (÷10^decimals) · optional

minted_raw - burned_raw: the supply the token's events add up to, at meta.computed_through_height.

Format: whole number, as a string · can be negative
folded_supply_rawstring · unit token_raw (÷10^decimals) · deprecated

minted_raw - burned_raw: the supply the token's events add up to, at meta.computed_through_height. Deprecated: use computed_supply_raw; sunset 2027-02-15.

Format: whole number, as a string · can be negative
Deprecated since 2026-10-17, removed after 2027-02-15. Use computed_supply_raw instead.
minted_rawstring · unit token_raw (÷10^decimals)

Transfers from 0x0 plus wrapper Deposits, raw units. The null address appears only here and in burned_raw, never as a holder.

Format: whole number, as a string
burned_rawstring · unit token_raw (÷10^decimals)

Transfers to 0x0 plus wrapper Withdrawals, raw units.

Format: whole number, as a string
holder_countinteger · unit count

Addresses with a positive balance, 0x0 excluded (erc721: holding at least one id).

negative_holder_countinteger · unit count

Addresses with a negative balance computed from the events (a non-standard token or missed movements; 0 expected; flagged negative_balance).

transfer_countinteger · unit count

Transfer logs of this standard (an erc1155 batch counts items).

first_heightinteger · unit block · can be null

The first counted movement's block.

last_heightinteger · unit block · can be null

The newest counted movement's block.

supply_checkstring · can be null

The supply computed from the events against total_supply_raw at supply_height: equal, differs (flag supply_without_events), pending (the token ledger is below the metadata's block), no_meta, no_supply or other_standard (the metadata describes the contract's other row). Null: not compared yet. New values may be added; show an unknown value as is (or generically).

supply_diff_rawstring · unit token_raw (÷10^decimals) · can be null

computed_supply_raw minus total_supply_raw at supply_height, raw units; null unless compared.

Format: whole number, as a string · can be negative
supply_heightinteger · unit block · can be null

The block the supply was compared at (the metadata's).

flagsarray of string

Checks that failed or need care: negative_balance, supply_without_events, both_standards, non_standard_balance (a balanceOf check), unnamed. [] when none. An open set.

price_taostring · unit tao_per_token · can be null

TAO per whole token. Only the peg: 1 for a verified (Sourcify), backed TAO wrapper (price_source peg); null for every other token, with price_unavailable_reason. Never a made-up price, never 0.

Format: decimal number, as a string
price_sourcestring · can be null

peg when price_tao is set (a verified, backed wrapper at 1:1); null otherwise. New values may be added; show an unknown value as is (or generically).

price_unavailable_reasonstring · can be null

Why price_tao is null: peg_not_backed (a wrapper that is not both verified and backed) or no_price_map (no price source for the token yet). Null when price_tao is set.

price_null_reasonstring · can be null · deprecated

Why price_tao is null: peg_not_backed (a wrapper that is not both verified and backed) or no_price_map (no price source for the token yet). Null when price_tao is set. Deprecated: use price_unavailable_reason; sunset 2027-02-15.

Deprecated since 2026-10-16, removed after 2027-02-15. Use price_unavailable_reason instead.
metadata_heightinteger · unit block · can be null

The block the metadata calls were made at.

metadata_fetched_atstring (date-time) · can be null

When the metadata was fetched, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
metadata_errorstring · can be null

The metadata fetch's last error (calls reverted, a non-standard return); null when none.

pegobject · can be null

The TAO backing check, as of peg.checked_at_height (checked hourly). Only TAO-backed wrappers (WETH9-style: Deposit / Withdrawal against the contract's native TAO) are checked, hourly; alpha-backed wrappers are not checked yet (backing unknown: peg null). Null for a token not checked (is_backed null: every non-wrapper), and while this deployment's data source does not serve the check yet.

9 fields in peg
is_backedboolean

The authoritative verdict of the hourly check: backed when shortfall_raw is at most 500 rao (500 x 10^9 wei, the existential deposit). Read this flag, not the figures: dust of up to 500 rao is the existential deposit left in the contract, not a leak. The same value as the token's is_backed.

native_balance_weistring · unit wei (÷1e18)

The contract's native TAO balance at checked_at_height, in EVM wei (1e18 per TAO).

Format: whole number, as a string
owed_rawstring · unit token_raw (÷10^decimals) · can be null

What the holders are owed: their positive balances summed, 0x0 excluded, raw units, as of meta.computed_through_height (the token ledger's block, which can differ from checked_at_height). Null on a non-erc20 row.

Format: whole number, as a string
owed_at_check_rawstring · unit token_raw (÷10^decimals) · can be null

The same sum at checked_at_height (the owed the feed's shortfall_raw and backing_ratio use), raw units. Null on a non-erc20 row, and while this deployment's data source does not serve it yet.

Format: whole number, as a string
shortfall_rawstring · unit token_raw (÷10^decimals)

max(owed at checked_at_height - native_balance_wei, 0), raw units: the feed's figure, written only when the wrapper was quiet since meta.computed_through_height (at most 600 blocks after it). Up to 500 rao (500 x 10^9) is the existential deposit, still backed (is_backed). Without owed_at_check_raw, owed_raw is as of meta.computed_through_height, so when checked_at_height and meta.computed_through_height differ the two can disagree.

Format: whole number, as a string
backing_ratiostring · unit ratio · 12 decimals · can be null

TAO held per TAO owed: (native_balance_wei / 1e18) / (owed / 10^decimals), owed being owed_at_check_raw (same block) when served, else owed_raw (as of meta.computed_through_height: then the two can be from different blocks); truncated toward zero to 12 decimals (1 = fully backed; below 1 = short; above 1 = over-backed). A ratio a hair below 1 within the 500-rao tolerance is still backed: read is_backed. Null with backing_ratio_unavailable_reason.

Format: decimal number, as a string
backing_ratio_unavailable_reasonstring · can be null

Why backing_ratio is null: cross_chain (the backing sits on another chain: this chain's native balance does not measure it), no_owed (owed is null or 0) or no_decimals (the token's decimals are unknown). Null when the ratio is set. New values may be added; treat unknown values as unavailable.

backing_scopeenum · can be null

Where the backing sits: local (this chain's native TAO in the contract) or cross_chain (another chain). Null: not known (the data source does not state it yet).

One of: local, cross_chain
checked_at_heightinteger · unit block

The block the feed read the native balance and the verdict at (checked hourly); the figures are as of this block.

transfers_24hinteger · unit count · can be null

Transfers of this standard in the last 7,200 blocks (~24 h) up to meta.at, counted when read (counted up to 1,000: see transfers_24h_exact). Null when this deployment does not know the head.

transfers_24h_exactboolean · can be null

False when transfers_24h stopped at 1,000 (show "1,000+"). Null with transfers_24h.

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.