---
title: "List per-subnet validator and economic metrics"
method: GET
path: "/api/v1/economics"
tags: ["subnets"]
---

# List per-subnet validator and economic metrics

`GET /api/v1/economics`

## Request

- Base URL: `https://api.metagraph.sh`
- URL: `https://api.metagraph.sh/api/v1/economics`
- Auth: none required

List per-subnet validator and economic metrics (counts, stake, registration cost, alpha price, alpha market-cap proxy, alpha FDV proxy, emission share, and registration block height). Default order is the legacy price share descending. Artifact-normalized moving-price share: alpha_price_tao divided by the sum of reported alpha prices, including Root when Root reports a price. Legacy snapshot rows do not retain the historical runtime eligibility inputs needed to certify v440 Stage 1. This is neither a verified runtime Stage-1 share nor final TAO emission. For the separately reconstructed, pinned live pipeline, use /api/v1/chain/emission-pipeline and inspect verification.verified. Filter by netuid/registration_allowed, search by name/slug, and sort with `sort=<field>&order=asc|desc` — the two are separate parameters (e.g. `?sort=alpha_market_cap_tao&order=desc` or `?sort=block&order=asc`), NOT a combined `field:desc` token. Per-subnet recipient-class economics (who the emission actually goes to -- validators, miners, the burn sink, in alpha and derived USD per day) are NOT here: /subnets/{netuid}/emission-split/history measures that split per day; never reconstruct it from an assumed constant. Registry screening signals (repo health via github_commits_weekly/github_last_push_at, testnet lineage via also_on, the declared miner hardware floor via gpu_required/min_vram_gb) are also NOT here: /api/v1/subnets serves them in bulk behind its fields= projection, e.g. ?fields=netuid,github_commits_weekly,also_on,gpu_required.

## Query parameters

- `netuid` integer
- `registration_allowed` 'true' | 'false'
- `q` string
- `fields` string
- `limit` integer
- `cursor` integer
- `page_snapshot` string
- `sort` 'alpha_fdv_tao' | 'alpha_market_cap_tao' | 'alpha_price_change_1d' | 'alpha_price_change_1h' | 'alpha_price_change_1m' | 'alpha_price_change_7d' | 'alpha_price_tao' | 'block' | 'emission_share' | 'max_stake_alpha' | 'max_uids' | 'max_validators' | 'miner_count' | 'miner_readiness' | 'name' | 'netuid' | 'open_slots' | 'registration_cost_tao' | 'subnet_volume_tao' | 'total_stake_alpha' | 'validator_count'
- `order` 'asc' | 'desc'
- `format` 'json' | 'csv'

## Response `200`

Canonical artifact wrapped in the Metagraphed API envelope, or the transformed list as text/csv when CSV is requested.

- object
  - `data` object, required
    - `captured_at` string, nullable, required
    - `chain_state` ChainState: The chain state the decomposition's inputs were pinned to. theta/q/h are read AS STORED at this block -- the runtime gates with the stored bar between its 360-block recomputes, so a live read is the wrong number for 359 blocks out of 360.
      - `block` integer, required
      - `block_hash` string, required: The block hash, so the pinning is exact -- a height alone is ambiguous across a reorg.
      - `emission_bar_quantile` number, nullable, required
      - `emission_gate_bar` number, nullable, required: theta. Null when the bar is unset, which disables the gate outright.
      - `emission_gate_exponent` integer, nullable, required: h. Null means the runtime default 3, NOT zero -- h = 0 makes the Hill gate a constant 0.5 for every subnet.
      - `network_immunity_period` integer, nullable: SubtensorModule.NetworkImmunityPeriod -- how many blocks after registration a subnet cannot be deregistered. Null on a blob captured before this read existed.
      - `total_issuance_tao` number, required
    - `contract_version` string
    - `field_sources` object: Per-field { kind, storage } provenance map: every value is labelled measured (with the pallet-qualified storage item it was read from) or reconstructed (our arithmetic over measurements, storage null). ADR 0023 decision 5.
    - `generated_at` string, required
    - `network` string, nullable, required
    - `notes` union: Public-safe notes; may be a string or a string list depending on the adapter.
      - string
      - string[]
    - `schema_version` 1, required
    - `subnets` SubnetEconomics[], required
      - `alpha_fdv_tao` number, nullable
      - `alpha_fdv_usd` number: alpha_fdv_tao converted at the blob's tao_usd reading.
      - `alpha_in_emission` number, nullable
      - `alpha_in_pool` number, nullable, required
      - `alpha_market_cap_basis` 'total_stake_alpha': What alpha_market_cap_tao multiplies -- published rather than documented, because a market cap without its basis is not a number anyone can reconcile (#10381).
      - `alpha_market_cap_tao` number, nullable
      - `alpha_market_cap_usd` number: alpha_market_cap_tao converted at the blob's tao_usd reading.
      - `alpha_out_emission` number, nullable
      - `alpha_out_pool` number, nullable, required
      - `alpha_price_change_1d` number, nullable: Signed %-change in alpha_price_tao over ~1 day from subnet_snapshots (#7227).
      - `alpha_price_change_1h` number, nullable: Signed %-change in alpha_price_tao over ~1h. Always null from daily snapshots (#7227).
      - `alpha_price_change_1m` number, nullable: Signed %-change in alpha_price_tao over ~30 days from subnet_snapshots (#7227).
      - `alpha_price_change_7d` number, nullable: Signed %-change in alpha_price_tao over ~7 days from subnet_snapshots (#7227).
      - `alpha_price_tao` number, nullable, required: The chain's MOVING price, not spot (#9408): on the live tier this is byte-identical to moving_price_pinned, the same word at the same instant. It is the right number for emission weighting, which is what the chain uses it for — but a lagging average is the wrong mark for valuing a position, and the gap widens exactly when the market moves. Use spot_price_tao for that.
      - `alpha_price_usd` number: alpha_price_tao converted at the blob's tao_usd reading.
      - `block` integer, nullable
      - `emission_enabled` boolean, nullable
      - `emission_share` number, nullable: Artifact-normalized moving-price share: alpha_price_tao divided by the sum of reported alpha prices, including Root when Root reports a price. Legacy snapshot rows do not retain the historical runtime eligibility inputs needed to certify v440 Stage 1. This is neither a verified runtime Stage-1 share nor final TAO emission. For the separately reconstructed, pinned live pipeline, use /api/v1/chain/emission-pipeline and inspect verification.verified.
      - `excess_tao` number, nullable
      - `first_emission_block` integer, nullable
      - `max_stake_alpha` number, nullable, required
      - `max_uids` integer, required
      - `max_validators` integer, required
      - `miner_burned_fraction` number, nullable
      - `miner_count` integer, required
      - `miner_readiness` integer, nullable
      - `moving_price_pinned` number, nullable
      - `name` string
      - `netuid` integer
      - `open_slots` integer, nullable
      - `owner_coldkey` string, nullable, required
      - `owner_hotkey` string, nullable, required
      - `registered_at_block` integer, nullable: SubtensorModule.NetworkRegisteredAt -- the SUBNET's registration height, read in this same pinned sweep. Both the immunity clock's start and the deregistration order's tie-break. Not a neuron's registration block, and not the registry index's field of the same name, which is a publish cycle behind this one.
      - `registration_allowed` boolean, required
      - `registration_allowed_pinned` boolean, nullable
      - `registration_cost_tao` number, nullable, required
      - `slug` string
      - `spot_price_tao` number, nullable: The AMM spot price in TAO per alpha — the pool ratio at rest, derived from tao_in_pool_tao / alpha_in_pool on this row. Root (netuid 0) has no AMM and is 1 by definition. Null when the reserves cannot support a price; an empty pool has no spot, and 0 would read as free. This is the mark to value a position at; alpha_price_tao is the moving average.
      - `subnet_mechanism` integer, nullable: SubtensorModule.SubnetMechanism -- 0 is Stable, 1 is Dynamic. Not cosmetic: get_moving_alpha_price substitutes a flat 1.0 for a Stable subnet instead of reading its moving price, moving it from the top of a pruning-price order to the bottom.
      - `subnet_volume_tao` number, nullable, required
      - `subtoken_enabled` boolean, nullable
      - `tao_in_emission_tao` number, nullable
      - `tao_in_pool_tao` number, nullable, required
      - `total_stake_alpha` number, nullable, required
      - `validator_count` integer, required
    - `summary` object, required
      - `registration_open_count` integer, required
      - `subnet_count` integer, required
      - `total_alpha_value_tao` string, required: Sum of every non-root subnet's alpha_market_cap_tao -- rao-precision decimal string (#6641).
      - `total_miners` integer, required
      - `total_network_value_tao` string, required: total_root_value_tao + total_alpha_value_tao -- Backprop's Total Network Value (#6641).
      - `total_root_value_tao` string, required: Root (netuid 0) TAO-denominated stake -- rao-precision decimal string (#6641).
      - `total_stake_alpha` string, required
      - `total_validators` integer, required
      - `with_economics_count` integer, required
    - `tao_usd` object: The reading every _usd field was converted at. Rides at the blob level because ONE reading priced all of them.
      - `block_number` integer, nullable, required
      - `observed_at` string, nullable, required
      - `price_basis` string, nullable, required
      - `usd_per_tao` number, required
    - `tao_usd_unavailable` 'no_index_reading' | 'index_unpriced' | 'index_stale' | 'no_alpha_price': Why there are no _usd fields. `index_unpriced` is ADR 0025's insufficient_pools -- a stated decline, never a price of zero.
  - `meta` ResponseMeta, required
    - `artifact_path` string
    - `cache` 'short' | 'standard' | 'static'
    - `catalog_paging` object
      - `reason` 'catalog_changed' | 'catalog_budget_exceeded' | 'catalog_unavailable', required
    - `contract_version` string, required
    - `generated_at` string, nullable: Deterministic build content marker (epoch by default); not a wall clock. Use published_at for human-facing freshness.
    - `observed_through` string, date-time, nullable: How far the tier that answered this request has observed at all. A payload reporting no activity at or before this time is a measured absence; one whose subject is newer is outside coverage, not empty. Null when the horizon is unreadable.
    - `pagination` PaginationMeta
      - `collection` string, required
      - `cursor` integer, required
      - `limit` integer, required
      - `next_cursor` integer, nullable, required
      - `order` 'asc' | 'desc'
      - `returned` integer, required
      - `snapshot` string: Present only for page_snapshot paging. Echo as page_snapshot on subsequent pages; a changed collection or query requires a restart.
      - `sort` string, nullable
      - `total` integer, required
    - `published_at` string, date-time, nullable: Real publish time from the KV latest pointer, distinct from generated_at. Null before the first publish or when the control KV is unbound.
    - `source` string
    - `stale_contract` object: Present ONLY when the served artifact was built under an older contract than the live one (serve-time drift, #1001) — the body may predate a schema change. Mirrored on the x-metagraph-stale-contract response header for monitoring.
      - `built_under` string, required: Contract version the served artifact was built under.
      - `live` string, required: Current (live) contract version the Worker is running.
  - `ok` true, required
  - `schema_version` 1, required

## Other responses

- `304`: ETag matched and the cached response is still valid.
- `400`: Query parameters were malformed or unsupported.
- `404`: Artifact or API route was not found.
- `405`: HTTP method is not supported.
- `500`: Unexpected backend error.

---

[API](https://skmtc.dev/metagraph/apis/metagraphed-api.md) · [All operations](https://skmtc.dev/metagraph/apis/metagraphed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metagraph/apis/metagraphed-api/revisions/e29036024bb1?raw)