1 Contents
API2 tao.xyz REST API v1
DOCS01BASEBase URL
Every endpoint is a GET under /v1 on the API host. The same handlers answer under the site origin at /api/v1, which is handy from a browser on tao.xyz.
- https://api.tao.xyz/v1/<path>
- API host
- Answers only API paths; anything else is a JSON 404.
- https://tao.xyz/api/v1/<path>
- Site origin
- The same handlers under the website's origin.
- https://api.tao.xyz/status
- Health
- Alias of /v1/status (also served at the bare host).
- https://api.tao.xyz/ready
- Readiness
- Database round trip; 503 while it fails.
- https://api.tao.xyz/openapi.json
- Description
- OpenAPI 3.1, generated from the live route definitions.
02AUTHAuthentication
Keys are optional. Send one in the Authorization header, raw, without a scheme: Authorization: txyz-…. A Bearer prefix is tolerated. The query form ?authorization= is ignored by default because URLs end up in proxy and browser logs. Keys are created on Keys (at most 5 active per account); only a SHA-256 hash is stored, so a lost key cannot be shown again: revoke it and create another.
curl -s 'https://api.tao.xyz/v1/blocks?limit=2' \ -H "Authorization: $TAOXYZ_API_KEY"
status, ready and openapi.json ignore keys: health checks never count against a quota.
03CACHECaching and keys
Anonymous responses are cached at the edge for a few seconds, matched to how often the data changes (12 s per block, 5 s for price ticks, one tempo for snapshots, minutes for closed history). Keyed responses are never cached: a key buys per-key limits and usage accounting, not different data. Anonymous and keyed answers are identical.
- No credential
- public, s-maxage=N, stale-while-revalidate=M
- Served from the edge cache; no database write. N follows the dataset's cadence.
- Authorization: <key>
- private, no-store
- Never cached. One usage count per request; X-RateLimit-* headers.
- Unknown or revoked key
- no-store
- 401 with WWW-Authenticate. Fix the key or drop the header.
- Over the key's limit
- no-store
- 429 with Retry-After: seconds left in the current minute.
- ?authorization=<key>
- no-store
- Ignored (treated as anonymous) unless the deployment enables query keys.
- Any error
- no-store
- Errors are never cached.
04PAGEPagination and envelopes
Lists answer {data: [...], pagination: {current_page, next_page, prev_page, per_page, total_items, total_pages}}; single objects answer {data: {...}}. page starts at 1, limit defaults to 50 and stops at 200 (a few endpoints document a higher maximum). next_page and prev_page are null at the ends.
The offset window is one million rows: (page - 1) × limit must stay below 1,000,000. For deep history, page by block or time range instead. Sort with order_by (one of the endpoint's fields) and order_dir (asc/desc, default desc).
05RANGERanges and filters
- block_start, block_end
- Inclusive block range; start after end is a 400.
- block_number
- Exact block.
- timestamp_start, timestamp_end
- Unix seconds, inclusive, converted to blocks at the chain's 12 s cadence (price/ohlc keeps taostats' exclusive end).
- netuid
- One subnet or up to 20, comma-separated or repeated (?netuid=1&netuid=2).
- address, coldkey, hotkey
- SS58 with any network prefix (checksum verified) or a 64-hex public key; answers use prefix-42 SS58.
- empty / unknown
- ?x= counts as absent; unknown parameters are ignored.
History endpoints read a bounded block window (each states its own default and maximum); a wider range is a 400 rather than a slow query.
06UNITSUnits and formats
- TAO and alpha
- RAO as decimal strings (1 TAO = 10^9 RAO), so no client loses precision past 2^53.
- Prices
- Subnet prices are decimal strings in TAO per alpha; USD values are JSON numbers.
- Timestamps
- ISO 8601 UTC with milliseconds and Z; parameters take unix seconds.
- Binary
- 0x-prefixed lowercase hex (hashes, keys).
- Names
- snake_case fields; non-finite numbers are null.
// JavaScript: keep RAO exact const rao = BigInt(row.amount); // "1234500000" const tao = Number(rao) / 1e9; // display only
07ERRErrors
Errors answer {status_code, message} with Cache-Control: no-store. Messages are for people; branch on the status.
- 400
- Bad request
- Invalid parameter, a range beyond an endpoint's window, or a page past the offset window.
- 401
- Unauthorized
- The Authorization header holds an unknown or revoked key.
- 403
- Forbidden
- Reserved for plan-gated data; not used yet.
- 404
- Not found
- Unknown entity, or an unknown path on the API host.
- 429
- Too many requests
- Per-key minute limit (Retry-After), or the anonymous edge limit.
- 500
- Server error
- A bug. The body never contains SQL, stack traces or hosts.
- 501
- Not implemented
- The endpoint is documented but its data is not indexed yet.
- 503
- Unavailable
- A database is down or the query deadline was hit (Retry-After: 5). Narrow the range and retry.
08LIMITRate limits and tiers
Limits are per key per UTC minute. Keyed responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds); over the limit the answer is 429 with Retry-After. Anonymous traffic is limited per IP at the edge.
09EXTResponse extensions
Fields tao.xyz adds to the taostats envelopes. Clients that ignore unknown fields need no change; clients that chart history should read gaps.
- gaps
- history, OHLC and range lists
- Block ranges with no data, oldest first, each whole (not clipped): {block_start, block_end, timestamp_start, timestamp_end, reason, status}. Draw them as NO DATA; never interpolate across.
- gaps[].reason = backfill_pending
- gaps
- History from genesis is still being indexed: [first_block, verified_from - 1] of the dataset. Status open; the band shrinks as the backfill advances.
- gaps[].status = unrecoverable
- gaps
- Will never be filled: an exclusion (reason unsupported_era or not_on_chain) or a range the chain no longer serves. Other statuses: open, repairing.
- gaps_degraded
- history responses
- true when the gap registry did not answer: gaps lists only the backfill band and exclusions, so the data may have holes it does not name.
- total_items_capped
- filtered lists
- true when total_items is a lower bound (the count stopped at its cap). The last page is then unknown; follow next_page.
- window_exhausted
- lists without a range
- The search walked its widest block window and the page is still short; older rows may exist. oldest_block_searched / newest_block_searched say where it looked: pass block_start/block_end to go further.
- alpha_estimated
- subnets/stake-events
- The event carried no alpha amount; alpha is tao divided by the pool price at the previous block (or null).
- estimated, staked_estimated
- accounts/{address}/history, alpha/history
- The day's balance (or one of its positions) is reconstructed from events between daily sweeps, not read from chain state.
- cadence_blocks
- subnets/epochs, status
- Spacing of the rows in the returned range: 1 is every block (live), 300 in backfilled history.
- partially_decoded
- blocks, extrinsics, calls, events
- The indexer recorded a decode failure for this item (for a block: for any item in it). Some arguments could not be decoded with the runtime's metadata and may be missing; the row itself is real.
- *_since_ingest, null_reason
- network/stats, subnets/burns
- Lifetime counters are null until the backfill covers all history; the *_since_ingest siblings carry the sum over indexed history meanwhile.
"gaps": [
{ "block_start": 0, "block_end": 4499999, "timestamp_start": null,
"timestamp_end": null,
"reason": "backfill_pending", "status": "open" }
]10COMPATtaostats compatibility
Paths, parameters, envelopes and error bodies follow the taostats v1 conventions, so a client written for taostats can switch its base URL to https://api.tao.xyz and keep working for every served path. The differences in behaviour are listed first, then what is not served.
Deviations
- Anonymous access
- every request needs a key
- allowed, edge-cached and rate-limited per IP; keys add per-key limits and are never cached
- ?authorization=
- accepted
- off by default (URLs end up in logs); the header is the supported form
- Bearer prefix
- not accepted
- tolerated and stripped
- Rate-limit headers
- none documented
- Retry-After on 429; X-RateLimit-Limit/-Remaining/-Reset on keyed responses
- gaps and coverage
- absent
- gaps, gaps_degraded and the other response extensions
- frequency=every_block
- not offered
- extension on subnets/pools/history: every stored block of one subnet, at most 7,200 blocks per request (limit up to 7,200)
- by_block
- every stored snapshot
- same semantics: one row per 300-block bucket, not every block (use every_block)
- /v1/status
- {ok, version, timestamp}
- adds build, head, datasets (freshness per dataset), gaps, repair_queue, clickhouse, backfill
- /ready
- {reason, status}
- {status} on 200, {status, reason} on 503
- Address parameters
- SS58 or 0x hex
- SS58 (any prefix, checksum verified) or a 64-hex public key; 40-hex EVM addresses only on EVM endpoints
- network parameter
- finney, nakamoto, kusanagi
- finney only; the parameter is ignored
- Deep pages
- offset paging over full history
- (page - 1) x limit must stay below 1,000,000; filtered history searches newest-first block windows (window_exhausted); offsets past 10,000 rows need a range
- Capped totals
- exact
- filtered history counts may be bounded (total_items_capped)
- Weight history
- daily vectors
- frequency=update (default) lists every set, commit and reveal; frequency=daily keeps one state per validator per UTC day; netuid is required
- Metagraph cadence
- every 300 blocks
- one snapshot per subnet epoch (tempo + 1 blocks); subnets/metagraph/history accepts hotkey without netuid
- Epoch rows
- per block
- per block live, every 300 blocks in backfilled history (cadence_blocks)
- Lifetime counters
- always set
- null until the backfill reaches genesis; *_since_ingest meanwhile (also created_on_date)
- Bounded history windows
- unbounded
- each history endpoint reads at most a documented block window; a wider range is a 400
- subnets/burns filters
- hotkey, extrinsic_id
- rejected with 400 (burns store neither)
- POST /v1/validators/yield
- documented
- served, but not in the OpenAPI document (GET operations only)
- price/ohlc
- timestamp_end exclusive
- the same (the only exclusive bound in the API)
- CORS
- not documented
- Access-Control-Allow-Origin: * ; preflight answered on the API host
Not implemented
3 Quick reference
REF- Base
- api.tao.xyz/v1
- Auth header
- Authorization
- Key format
- txyz-<32>
- Keys / account
- 5
- Anon limit
- 120/min/IP
- Free key
- 30/min
- Page size
- 50, max 200
- Offset window
- 1,000,000
- Amounts
- RAO strings
- Times
- ISO 8601 UTC