# TaoSwap glossary — metric definitions & API reference

> TaoSwap is a Bittensor (TAO / dTAO) explorer and DEX. This file documents every metric the app displays: its plain-language meaning, its exact formula, and the exact public API request that returns it, so an agent can fetch the same values directly. Human version: https://taoswap.org/glossary

API base URL: https://api.taoswap.org

## Using the API

- All endpoints are public, unauthenticated HTTP GET requests. No key, no rate-limit headers documented here.
- Most subnet metrics come from one call: `GET https://api.taoswap.org/v2/subnets/` returns `results[]` (one object per subnet); a metric’s "Response field" is the path within a row.
- Validator metrics: `GET /validators/` (`results[]`). Account metrics: `GET /accounts/` (`results[]`, paginated).
- Portfolio / per-account metrics require a `?account=<coldkey>` query param. Replace `<coldkey>`, `<netuid>`, `<hotkey>` placeholders with real values.
- Source `api` = the value is returned as-is in the response field shown. Source `in-app` = computed client-side from the listed source(s); the request then shows where the inputs come from.

## Price & valuation

### Price (τ)
- Source: api
- Definition: What one alpha token is worth in TAO right now, quoted by the subnet's own liquidity pool.
- Formula: `root_in_pool / alpha_in_pool (chain spot price)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].price`
- Note: The pool is technically a weighted (Balancer) AMM, so the exact chain formula is (w_base / w_quote) × root_in_pool / alpha_in_pool, but every live subnet sits at 0.5 / 0.5 to within a rounding error, which makes the plain ratio of the two reserves exact for any practical purpose. This is the spot price, not the EMA moving price used for market cap and FDV, so explorers that display the EMA read differently.

### Price ($)
- Source: in-app
- Definition: The same spot price, converted to dollars.
- Formula: `price × the live TAO/USD rate`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].price`
- Request note: USD = price × the live TAO/USD rate.

### Market Cap
- Source: api
- Definition: Value of the alpha actually in circulation: what sits in the pool plus what is staked, minus what has been burned, priced at the smoothed (EMA) price.
- Formula: `(alpha_in_pool + max(alpha_stake − alpha_burned_counter/1e9, 0)) × (moving_price || price)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].market_cap`
- Note: Three things make it differ from other explorers: the price is the EMA moving price (spot only as a fallback); the base is circulating alpha, not the 21M cap (that is FDV); and burned alpha is subtracted. On-chain, burning destroys the tokens but leaves them inside the staked reserve, so without that subtraction the destroyed alpha would still be valued. Recycled alpha is not subtracted again, because the chain already removed it from the reserve, and the subtraction is clamped at zero (a missing burn counter subtracts nothing), so it can never over-correct. Supply, below, deliberately keeps burns, so on burn-heavy subnets supply × price sits above market cap. Root (SN0) falls back to spot because its moving price is 0.

### FDV
- Source: api
- Definition: Fully Diluted Valuation: what the subnet would be worth if every alpha token that can ever exist had already been emitted.
- Formula: `21,000,000 × (moving_price || price)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].fdv (fdv_usd for the USD value)`
- Note: Every subnet has the same 21M alpha hard cap as TAO itself, so FDV is always ≥ market cap. Same EMA-vs-spot gap as market cap. Root falls back to spot.

### Moving Price
- Source: api
- Definition: A slow-moving average of the price, used as the basis for market cap and FDV so a single trade cannot move a valuation.
- Formula: `chain-native EMA of min(spot, 1 τ), spot as fallback`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].moving_price`
- Note: Computed on-chain, not by TaoSwap: the smoothing factor is 0.000003 per block, which takes about 30 days to close half the gap to spot and ~3.5 months to close 90%, and a young subnet ramps in gradually from its first emission block. The chain feeds the EMA min(spot, 1 τ), so the moving price can never exceed 1 τ even if spot does. It should match any explorer reading the same chain value; small gaps come from the ~2-min snapshot block.

### 1H / 24H / 7D / 30D / 90D %
- Source: api
- Definition: How much the price has moved over the trailing window: current spot against the closing price at the start of the window.
- Formula: `((spot − close) / close) × 100, close = the last candle close before the window opens`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].price_evolution_{h_1,h_24,d_7,d_30,d_90}`
- Note: Anchored by clock time, not by block, and the two families anchor differently: 1H and 24H take the last minute-candle close inside a one-hour-wide window ending an hour (or a day) ago, while 7D / 30D / 90D take the last candle of the calendar day N days ago in UTC, so 7D is not a rolling 7 × 24 h. It compares a noisy live spot against a candle close, which is why it can differ from explorers doing spot-to-spot. A missing or zero baseline shows 0%.

### 7D Trend (sparkline)
- Source: api
- Definition: The inline 7-day price line drawn in the table.
- Formula: `the last close of each 4-hour bucket over 7 days (~42 points, oldest → newest, 6 significant digits)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].sparkline_7d`
- Note: null when the subnet has fewer than two points in the window, which is the exact "too little history to draw a line" condition.

### Volume 24H
- Source: api
- Definition: TAO traded through the subnet's pool over the last 24 hours.
- Formula: `Σ of the TAO leg of every stake and unstake on the subnet in the trailing 24 h (τ); volume_24h_usd is server-converted`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].volume_24h (volume_24h_usd for the USD value)`
- Note: Counted on one side only, in TAO, so it is roughly half of what an exchange would print for the same activity, since exchanges count both legs. Protocol chain buys are excluded: the coinbase moves the reserves directly without ever emitting a trade. Swaps and cross-subnet moves contribute each of their legs to the pool it touches, while same-subnet hotkey or validator rebalances are excluded, because they never touch the pool. The window rolls from now, but it is recomputed at most once an hour, so it steps rather than glides. null for root (no pool); a 0 is a real zero.

## Emission

### Emission %
- Source: api
- Definition: The share of the network's per-block TAO emission that goes to this subnet. Across emission-enabled subnets it adds up to ~100%.
- Formula: `emission_value / Σ emission_value (non-root) × 100, emission_value = tao_in_emission + excess_tao_emission (τ/block)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].emission_percent`
- Note: It is a share, not an absolute amount, so the halving cancels out of it entirely. `emission_ema_percent` is the same number under an older name (see EMA %). A subnet reads 0 when emission is switched off for it (its share is redistributed on-chain), and a freshly registered subnet starts switched off until it is enabled. A subnet is also skipped entirely while registration is closed on it or its subtoken is disabled. Root (SN0) is null. Since the chain records what was actually injected, rare partial-injection blocks read slightly low.

### EMA %
- Source: api
- Definition: The subnet's share of realized per-block emission. It is the same number as Emission %: the name is legacy, and no EMA is involved any more.
- Formula: `emission_value / Σ emission_value (non-root, emission_value > 0) × 100`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].emission_ema_percent`
- Note: Two names for one metric: they are the same number, to within rounding. The "EMA" is pure back-compat: there is no 30-day half-life and no net stake/unstake flow involved since emission switched from flow-based to price-based in June 2026. What it tracks now is the chain emission share, which the chain builds from moving_price × (1 − miner burn), renormalised over the emission-enabled non-root subnets. Until runtime spec 425 that weighting also carried a root_proportion factor; spec 425 removed it. Root (SN0) is null. The old flow EMA now only survives in the Inflow / Outflow fields.

### Chain Buys (Excess TAO emission)
- Source: api
- Definition: TAO the protocol spends buying alpha on the open pool, rather than injecting it as fresh liquidity. It is real buy pressure paid by the network.
- Formula: `SubnetExcessTao (RAO/1e9, halving-adjusted); τ/block, shown ×7200 for τ/day. Invariant: emission_value = tao_in_emission + excess_tao_emission.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].excess_tao_emission`
- Note: Each block the chain wants to inject the subnet's TAO emission as matching TAO + alpha liquidity, but the alpha side is capped at root_proportion × the block's alpha emission. As a subnet ages its alpha issuance grows, that cap falls, and the TAO that can no longer be paired is spent buying alpha in the pool instead. That is the whole mechanism, and it is why older subnets drift from liquidity injection towards chain buys. Replaces the old emission_chain_buys estimate (a τ/day price proxy), so historical values diverge sharply. null for root; ≤ 0 means no chain buy this block. The field records what actually executed, so on a rare partial-injection block the two legs sum below the allocated emission.

### Chain Buys %
- Source: api
- Definition: This subnet's share of all the chain buying happening across the network.
- Formula: `subnet excess / Σ excess over non-root subnets with excess > 0 × 100`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].excess_tao_emission_percent`
- Note: A normalised share, so it sums to 100 across non-root subnets. There is no smoothing whatsoever: the chain clears the underlying counter every block, so the value is whatever the latest block happened to do, which makes it very spiky. Use the history series for a stable view.

### Root Proportion
- Source: api
- Definition: The share of this subnet's validator emission that flows to root (SN0) stakers instead of to its own alpha stakers.
- Formula: `γ·R / (γ·R + alpha issuance), fraction in [0, 1), multiply by 100 for display. alpha issuance = alpha_in_pool + alpha_stake + the protocol alpha reserve. R = TAO staked on root, γ = the chain tao weight (~0.18, read live).`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_proportion`
- Note: The denominator is the subnet's whole alpha issuance, the pool side included; netting it against the staked side alone overstates the proportion by several points. The third term is protocol liquidity the AMM could not inject without pushing the pool weights out of range: it is zero on every subnet today and drains as soon as an injection fits, so in practice the value is set by the two alpha stocks. The proportion falls as a subnet ages and its own alpha issuance grows, which is also what shifts the subnet from liquidity injection to chain buys (see Chain Buys). It is a fraction, not a percentage. null for root or when there is no data. Do not confuse γ with `conviction.owner_emission_share`, which also sits near 0.18 but is the unrelated owner cut.

### Burn
- Source: api
- Definition: The share of the miner reward pool that never reaches independent miners, because it was directed at the owner's own neurons and then destroyed.
- Formula: `Σ (owner neurons' incentive) / Σ (all incentive) × 100 (weighted by mechanism split on multi-mechanism subnets)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].emission_miner_burn`
- Note: The owner does not pocket this emission. The chain withholds any incentive aimed at an owner or "immune" hotkey and then either burns or recycles it, depending on the subnet's setting, and the value is deliberately identical either way. That withheld share matters because the chain scales the subnet's whole emission allocation by (1 − burn), so a high burn actively costs the subnet. An "owner neuron" is any neuron whose coldkey is the subnet owner, plus the subnet owner hotkey. Below 100% means at least one independent miner is earning. The figure is recomputed from the live metagraph rather than read from the chain's own per-tempo ratio; the two agree within a hundredth of a point on every subnet, the only exception being subnets with emission switched off, where the chain value is a stale default and nothing is being distributed anyway.

### EMA Inflow / Outflow
- Source: api
- Definition: The two halves of one signed average of net TAO flow (stake minus unstake) into the pool. A subnet shows one or the other, never both.
- Formula: `inflow = max(EMA_net_tao_flow, 0); outflow = |min(EMA_net_tao_flow, 0)| (chain EMA in TAO, ~30-day half-life)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].inflow / results[].outflow`
- Note: Only direct user stake/unstake counted; emission-driven swaps were excluded. IMPORTANT: these values are FROZEN. Since emission switched to price-based weighting in June 2026 the chain code that advanced this EMA is no longer called at all, so the storage is still readable but never updated. Any explorer showing a live 24h/7d net flow is computing something else.

## Liquidity & depth

### In Pool (τ) / (α)
- Source: api
- Definition: The two sides of the subnet pool: how much TAO and how much alpha it currently holds.
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_in_pool / results[].alpha_in_pool`

### Depth ±2% / ±5%
- Source: api
- Definition: How much TAO it takes to push the price up (+, buying) or down (−, selling) by 2% or 5%. Bigger numbers mean a deeper, harder-to-move pool.
- Formula: `up = root_in_pool × (√(1+δ) − 1) / (1 − fee); down = root_in_pool × (1 − √(1−δ)); δ = 0.02 or 0.05, fee ≈ 0.0005`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].depth_{up,down}_{2,5}pct (+ *_usd)`
- Note: The down side reads slightly larger than the up side, and that is arithmetic rather than a bug: since √ is concave, the same percentage move needs marginally more TAO on the way down. The up leg is a gross input with the pool fee added on top, while the down leg is the net TAO leaving the pool, so the fee actually narrows the gap instead of widening it: as served, the down side is 0.95% larger at ±2% and 2.5% larger at ±5%. It is computed on the plain constant-product curve, which matches the chain because live pools are balanced 0.5 / 0.5. There is no concentrated liquidity, because user-provided liquidity is permanently disabled on-chain. Root (SN0) is null, having no pool.

### ADR (Alpha Distribution Ratio)
- Source: api
- Definition: How much alpha holders own compared with how much the pool holds. Above 1, holders own more than the pool can absorb, so a rush for the exit sells at a steep discount. Below 1, the pool cushions exits.
- Formula: `(alpha_stake − alpha_burned_counter/1e9) / alpha_in_pool (unitless, pivot at 1.0)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].adr`
- Note: Burned alpha stays inside the staked reserve on-chain, so it is subtracted here through the same helper that backs market cap, and the two therefore net burns identically; they can only disagree for a single sync cycle, if a burn-counter read fails. The numerator still includes the owner's own locked and self-staked alpha. History rows before 2026-05-28 keep the raw un-netted ratio, because the chain had no burn counter before then. null for root or an empty pool.

## Supply

### Supply
- Source: api
- Definition: All the alpha in circulation for this subnet: what sits in the pool plus what is staked.
- Formula: `alpha_in_pool + alpha_stake`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].total_supply`
- Note: Burned alpha is deliberately NOT removed here: on-chain a burn destroys the tokens but leaves the reserve untouched, and it is tracked separately (see Burned). Market cap, by contrast, does remove it, which is why supply × price sits above market cap on burn-heavy subnets. Recycled alpha IS already excluded, because the chain reduces the reserve when it recycles. Supply and market cap also stop at those two stocks, leaving out the protocol alpha reserve that the chain folds into its own issuance figure (see Root Proportion): that reserve is liquidity waiting to be injected, owned by nobody, and it is zero on every subnet today. Explorers that also net burns, or that show the 21M cap (which is the FDV base), will differ.

### Burned
- Source: in-app
- Definition: The best-known amount of alpha destroyed for good, valued in TAO. Most subnets never burn anything.
- Formula: `max(alpha_burned_counter, total_alpha_burned) / 1e9 × (moving_price || price)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].alpha_burned_counter, results[].total_alpha_burned`
- Request note: Valued in TAO as max(counter, total) / 1e9 × (moving_price || price).
- Note: Two overlapping sources, neither complete on its own: the on-chain counter covers every burn path (the burn extrinsic, the incentive burn during emission, the swap-fee burn) but only exists since 2026-05-28, while the extrinsic-only total reaches back to genesis but is blind to the other paths. Taking the larger of the two is the tightest lower bound on the real total. Burning is not recycling: a burn destroys the tokens while leaving the reserve and the issuance counter untouched, whereas recycling reduces both, and recycled alpha is not counted here.

## Concentration

### HHI (concentration)
- Source: api
- Definition: How concentrated the holders are, on a 0–100% scale. 0% means the stake is spread perfectly evenly, 100% means one holder owns everything. Lower is healthier.
- Formula: `(HHI − 1/N) / (1 − 1/N), clamped 0..1, ×100 for display. HHI = Σ(share²) over positive holders`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].hhi_normalized`
- Note: N counts the positive holders left after the owner's own position is removed. The exclusion is per position, not per wallet: a position drops out only when the holder, the validator it is staked to and the subnet owner are the same coldkey, so the owner's delegations to outside validators are still counted. Most explorers publish the raw HHI rather than this min-normalised form, so the numbers are not comparable. Returns 0 below 2 holders.

### Nakamoto coefficient
- Source: api
- Definition: The smallest number of top holders who together own more than half of the stake. Lower means more concentrated.
- Formula: `smallest k whose cumulative share of the stake exceeds 0.5 (integer)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].nakamoto_coefficient`
- Note: Same owner exclusion as HHI. Returns 0 (not 1) for an empty or single-holder subnet.

### Top 10 %
- Source: api
- Definition: How much of the stake the ten largest holders own between them.
- Formula: `Σ(shares of the 10 largest) / Σ(all kept holders), 0..1, ×100 for display`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].top10_share`
- Note: It is a fraction in 0..1, not a percentage. The denominator excludes the owner self-stake, so it measures the tradable distribution; the owner can still show up through its external delegations.

### Conviction
- Source: api
- Definition: How much of the subnet the current leader of the ownership race has locked up, as a share of supply. Locking alpha is how a key stakes its claim to owning the subnet.
- Formula: `(king_conviction / 1e9) / total_supply × 100`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.owner_conviction_pct_supply`
- Note: Despite the field name this is the LEADER's position, and the leader ("king") is not always the owner, so check `king_is_owner`, and never infer it by comparing `king` (a hotkey) to `owner` (a coldkey). The companion fields are king_conviction (raw score, never display it), owner_conviction_pct (share of the conviction battle, 100% = unchallenged) and total_conviction. Conviction decays over time and the chain serves it already decayed, so the value you read is current; perpetually locked alpha never loses mass and its conviction converges upward to that mass instead. Two half-lives drive it, today about 90 days for the unlock schedule and about 30 for maturation, but both are governance parameters and one has already been moved off its default, so read unlock_half_life_days / maturity_half_life_days rather than trusting those numbers.

### Takeover gate (Threshold met)
- Source: api
- Definition: Two conditions must both hold before the chain will hand a subnet to the conviction leader: the subnet must be over a year old, and the TOTAL conviction locked on it (every holder combined, owner included) must reach 10% of its staked alpha. Threshold met is how full that second condition is.
- Formula: `Eligible when age ≥ 2,629,800 blocks (7200 × 365 + 1800 ≈ 365.25 d) AND total_conviction ≥ SubnetAlphaOut / 10. Threshold met = total_conviction / threshold × 100.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.threshold_used_pct`
- Note: Both gates must hold in the same block. The age gate is a plain countdown and is usually already cleared. The bar can read above 100% for a while when a decaying lock is near its peak, without the gate being durably reachable; see the ceiling described under Time to takeover. Whether the chain actually executes the flip is a runtime question, so read `takeover_enforced`, which tracks the live runtime version rather than a hardcoded flag: while it is false the gates are computed but nothing happens, which makes this an armed race rather than an executed takeover. Mainnet passed the enabling runtime version, so it reads true today.

### Time to takeover (ETA)
- Source: api
- Definition: How long the current locks would need to fill the 10% conviction gate, projected day by day. Deliberately NOT proportional to the Threshold-met bar: a subnet that looks fuller today can still show a longer ETA.
- Formula: `Smallest Δ, scanned in 1-day steps out to 3 years, where the projected total conviction ≥ threshold, reported as max(conviction ETA, age ETA). The projection replays the chain maturation/decay math: existing conviction fades by exp(−Δ/MaturityRate), perpetual mass matures into conviction by (1 − exp(−Δ/MaturityRate)), decaying mass follows the chain's γ term, and owner masses are pinned to their locked mass.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.gate_eta_days`
- Note: Conviction converges towards the perpetually locked mass, because the decaying part matures and then melts away. That gives the gauge a ceiling (gate_ceiling_pct = perpetual locked / threshold × 100): below 100% the gate is never durably reachable and the status reads Stalled, even if a transient bump crosses it. The approach is concave, so the closer the ceiling sits to the threshold the slower the final stretch, and a subnet with high conviction today but a ceiling barely above the gate reads slower than a less-filled one with room to grow. The 3-year horizon is about 36 maturity half-lives, far enough out that the projection has settled, so "no crossing" really does mean "never, with the locks as they stand". Assumes locks stay frozen and the threshold does not move; every sync recomputes it and the value drifts.

### Stake (α)
- Source: api
- Definition: All the alpha staked on the subnet, i.e. everything held outside the pool.
- Formula: `the chain alpha-out reserve (α)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].alpha_stake`
- Note: This is the raw reserve: it INCLUDES the owner's locked and self-staked alpha, and it still includes burned alpha (a burn does not shrink the reserve). The owner-excluded distribution behind HHI / Nakamoto / Top 10% is a separate calculation.

### Locked (conviction)
- Source: api
- Definition: The alpha locked across every participant in the ownership race, shown both at face value and at what it would actually fetch if sold.
- Formula: `total_locked = perpetual + decaying (α). Face value = α × price; realizable = the same α sold through the pool, after fee and slippage.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.total_locked, .total_locked_value`
- Note: Perpetual locks never release their alpha; decaying locks give it back gradually. Realizable values are single AMM exits, so per-holder figures do NOT add up to the subnet total, so use the subnet-level value for "everything sold at once".

### Challenger stake
- Source: api
- Definition: What the leading challenger has actually put at risk: the realizable TAO value of the alpha they have locked. Bigger means a more committed challenger.
- Formula: `the king's locked α, valued through the pool after fee and slippage (tao_slippage), not at flat spot`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.owner_locked_value.tao_slippage`
- Note: Shown at realizable value on purpose, because face value overstates the commitment on a thin pool. Only meaningful when the leader is an outsider (`king_is_owner` false).

### Takeover status
- Source: api
- Definition: A one-word verdict on the ownership race: whether the gate can ever be reached with the locks as they stand, whether both gates are already satisfied, and whether the chain would act on it.
- Formula: `Eligible = takeover_age_ok AND takeover_threshold_ok. Stalled = gate_reachable false (the current locks plateau below the gate). Enforcement = takeover_enforced.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].conviction.gate_reachable, .takeover_eligible, .takeover_enforced`
- Note: Stalled is not the same as "far away": it means the perpetual mass alone cannot reach the threshold, so no amount of waiting helps, only a new lock does. Even when eligible, nothing happens while enforcement is off.

## Lifecycle & risk

### Deregistration risk
- Source: api
- Definition: How exposed a subnet is to being removed from the network. A subnet is only ever removed when someone registers a new one while the network is at its cap, and the victim is the surviving subnet with the lowest price EMA.
- Formula: `prune_rank orders the non-immune subnets by price EMA, lowest first and oldest first on a tie; rank 1 is the one the next registration would remove. risk_level = immune, then critical (price EMA of 0, or rank ≤ 5), high (≤ 15), medium (≤ 40), low beyond that.`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].dereg.risk_level, .prune_rank; envelope dereg_context`
- Note: Immune subnets cannot be removed at all and carry no rank. A subnet whose owner never called start_call has a price EMA frozen at 0, which puts it at the very front of the queue the moment its immunity ends. The bands are a presentation choice, not a chain concept: on-chain, only rank 1 means anything, and since registrations have historically arrived about weekly the rank reads roughly as weeks of headroom. The envelope `dereg_context` tells you whether the network is actually at capacity, and none of this matters while it is not.

### Immunity
- Source: api
- Definition: A grace period after registration during which a subnet cannot be deregistered, whatever its price.
- Formula: `is_immune = current_block < immunity_end_block; immunity_ends_at is the ISO timestamp of that block`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].dereg.is_immune, .immunity_end_block, .immunity_ends_at`
- Note: The comparison is strict, so the subnet becomes prunable exactly on its end block. The fields are only set while the subnet is actually immune. The window length is a chain parameter, served alongside as `immunity_period_blocks`.

### Price EMA (deregistration)
- Source: api
- Definition: The value the chain compares when it has to pick which subnet to remove: the same smoothed moving price shown elsewhere, not the spot price.
- Formula: `the chain moving price (see Moving Price); lowest non-immune subnet is the one removed, older subnets losing ties`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].moving_price`
- Note: Using the EMA rather than spot is deliberate: it makes the choice unforgeable by a single trade. A subnet that never started emission sits at 0 and is therefore always the first candidate.

## Network activity

### Miners
- Source: api
- Definition: How many independent miners are currently earning something, excluding the owner's own neurons.
- Formula: `count(neurons where incentive > 0 and not an owner neuron)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].active_miners`
- Note: "Active" here means incentive strictly above 0, with no validator-permit, vtrust or stake threshold applied, so explorers using a permit or axon heuristic will report different numbers. A Burn below 100% implies at least one of these miners is earning.

### Mechs
- Source: api
- Definition: How many mechanisms (sub-mechanisms) the subnet runs.
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].mechanism_count`

### Holders
- Source: api
- Definition: How many distinct wallets (coldkeys) hold any alpha of this subnet.
- Formula: `count(distinct nominator coldkeys with stake > 0)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].holders_count`
- Note: There is no minimum or dust floor (any non-zero position counts), and unlike the concentration metrics this one does NOT exclude the owner. The asymmetry is deliberate: this answers "how many wallets hold this alpha", while HHI, Nakamoto and Top 10% answer "how is the tradable float distributed". An explorer with a min-stake floor, or one counting per (coldkey, hotkey) pair instead of per coldkey, will differ.

## Validators

### Total Stake (validator)
- Source: api
- Definition: Everything a validator has behind it, root stake plus alpha across every subnet, expressed in TAO.
- Formula: `Σ over subnets of each position valued in TAO (root 1:1; alpha through the pool, with slippage)`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].total_stake`
- Note: Alpha is valued at what it would really fetch on exit, position by position, not at flat spot and not at the moving price. So it reads lower than a naive Σ(alpha × price) for large positions, and lower still than EMA-based explorers. The Accounts table values alpha exactly the same way, so the two are directly comparable. It is a snapshot from the last sync.

### Root stake / Alpha stake (validator)
- Source: api
- Definition: The two halves of a validator's total stake: TAO staked on root, and alpha staked across subnets (valued in TAO).
- Formula: `total_stake_root + total_stake_alpha = total_stake`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].total_stake_root / results[].total_stake_alpha`
- Note: The alpha half carries the same slippage-aware valuation as Total Stake, so it moves with pool depth as well as with price.

### Stake share (validator)
- Source: in-app
- Definition: The split of a validator's own stake between root and alpha, drawn as a bar. It says nothing about the validator's size relative to others, which is Dominance.
- Formula: `root % = total_stake_root / total_stake × 100; alpha % = the remainder`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].total_stake_root, results[].total_stake`
- Request note: The bar splits the same total into its root and alpha halves.

### Root weight (validator)
- Source: api
- Definition: The validator's root stake counted the way the chain counts it for emission, where TAO on root does not weigh 1:1 against alpha.
- Formula: `total_stake_root × γ, γ being the chain tao weight (~0.18, read live)`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].root_weight`
- Note: A scaled TAO amount, not a ratio and not a second stake bucket, so never add it to the stake columns. Same γ as the subnet Root Proportion.

### Dominance
- Source: api
- Definition: What proportion of all validator stake on the network this one validator controls.
- Formula: `total_stake / Σ total_stake (chain-wide) × 100`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].dominance`
- Note: Same slippage-aware valuation as Total Stake. The list only sums validators with at least 1000 τ, so the visible set adds to ~100%. A validator's own page can read slightly lower than the list, because the two do not always count the same set. Validators under 1000 τ have no page of their own.

### Fees (take)
- Source: api
- Definition: The commission the validator keeps out of its delegators' rewards.
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].take`

### APY / APR 7D (validator)
- Source: api
- Definition: What delegating to this validator has returned over the last 7 days, annualised: APR without compounding, APY with.
- Formula: `rate per epoch = Σ dividends paid to delegators / Σ stake that earned them, over the last 7 complete UTC days. epochs per year = 7200 × 365 / the subnet tempo. APR = rate × epochs per year × 100; APY = ((1 + rate)^(epochs per year) − 1) × 100. Both ×100 and clamped to [0, 10000].`
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].apy_7d / results[].apr_7d`
- Note: The series is what the chain actually paid delegators, already net of the validator take and of childkey redistribution, measured against the exact stake the chain used as the denominator. The only difference between the two figures is the compounding assumption: APR is the number most explorers publish, often labelled APY, while APY is the more honest one for a passive alpha staker, since dividends restake into the pool. Annualisation uses each subnet's own tempo rather than a flat epoch count. Exactly 10000 means the real figure was clamped, not that it is precisely 10000%. A hotkey with no dividends in the window reads 0, and stale values are never carried forward. The list figure is the stake-weighted average of the validator's per-subnet rows.

### Delegator / Validator Earnings per Day
- Source: api
- Definition: What the validator paid out over the last full day, in TAO: the first figure is what its delegators shared, the second what it kept as commission.
- Formula: `Σ TAO paid over the last complete UTC day, split at the take: the delegators' side is net of it, the validator's side is the take itself.`
- Request: `GET https://api.taoswap.org/validators/<hotkey>/`
- Response field: `delegator_daily_earning / validator_daily_earning`
- Note: A single day, not a rate, so it moves with the stake behind the hotkey and with what its subnets emitted that day: a large validator out-earns a small one at the same APY. The childkey-take slice is counted inside these figures, not on top of them. A validator running a 0% take reads 0 on its own line while still paying its delegators in full. Only the validator's own page carries them, so a list of validators compares yields instead.

### Nominators / Validator / Childkey 7D (τ)
- Source: api
- Definition: The TAO a validator earned on one subnet over the last 7 days, split three ways: what went to its nominators, what it kept as commission, and the part that came from childkey take.
- Formula: `Σ TAO earned on that subnet over the last 7 complete UTC days. Nominators is net of the take, validator is the take itself, childkey is the childkey-take slice of the two.`
- Request: `GET https://api.taoswap.org/validators/<hotkey>/`
- Response field: `monitoring[].nominator_return_7d_tao / validator_return_7d_tao / childkey_return_7d_tao`
- Note: Amounts, not rates: they scale with the stake behind the hotkey, which is why the APY sitting beside them can be high on a small line and modest on a large one. Blank until the subnet has synced, which is not the same as zero. The childkey figure is a slice of the other two, so adding all three double-counts it.

### Delegators
- Source: api
- Definition: How many delegators are staking to the validator.
- Request: `GET https://api.taoswap.org/validators/`
- Response field: `results[].count_delegators`

## Accounts & wealth

### Free
- Source: api
- Definition: TAO sitting in the wallet, not staked anywhere.
- Request: `GET https://api.taoswap.org/accounts/`
- Response field: `results[].free`

### Stake (root) / Stake (alpha)
- Source: api
- Definition: TAO staked on root, and all alpha across subnets valued in TAO.
- Formula: `staked_tao (root stake, 1:1) / staked_alpha_in_tao (alpha through the pool, with slippage)`
- Request: `GET https://api.taoswap.org/accounts/`
- Response field: `results[].staked_tao / results[].staked_alpha_in_tao`
- Note: staked_tao is root stake only and excludes free TAO (the Total column adds it back). Alpha is valued at what it would actually fetch on exit, so it reads lower than flat-price or EMA-based figures.

### Total (account)
- Source: api
- Definition: Everything the wallet is worth in TAO: free plus root stake plus alpha stake.
- Formula: `free + staked_tao + staked_alpha_in_tao`
- Request: `GET https://api.taoswap.org/accounts/`
- Response field: `results[].total_tao`

### Share (Free / Root / Alpha)
- Source: in-app
- Definition: How a wallet splits its own holdings between free TAO, root stake and alpha: the three-segment bar in the Accounts table. It is the composition of that wallet, NOT its share of the network.
- Formula: `free % = free / total_tao × 100, root % = staked_tao / total_tao × 100, alpha % = staked_alpha_in_tao / total_tao × 100 (the three sum to 100)`
- Request: `GET https://api.taoswap.org/accounts/`
- Response field: `results[].free, results[].staked_tao, results[].staked_alpha_in_tao`
- Request note: The three percentages come from the row itself.
- Note: Easy to misread: a wallet showing "80% Alpha" holds 80% of ITS OWN balance in alpha. For the wallet's standing across the network, read the rank instead.

### Global rank
- Source: api
- Definition: Where the wallet sits in the network-wide wealth ranking, 1 being the largest.
- Formula: `position by total_tao (free + root stake + alpha stake) descending, ties broken by address order. rank_alpha ranks on alpha stake alone.`
- Request: `GET https://api.taoswap.org/accounts/`
- Response field: `results[].rank (results[].rank_alpha for the alpha-only ranking)`
- Note: It ranks every coldkey in the latest complete daily balance snapshot, so it is a ranking of the indexed set rather than of the whole chain, and it is anchored to the last fully computed snapshot so a partial sync cannot silently drop the top of the table. Alpha carries the same exit-value pricing as everywhere else, which can reorder large alpha-heavy wallets compared with a flat-price ranking.

## Portfolio & PnL

### Value (τ) / Share
- Source: in-app
- Definition: What a position is worth in TAO, and how much of the portfolio it represents.
- Formula: `value = balance × price (or the realizable amount in Realizable mode); share = position value / portfolio total`
- Request: `GET https://api.taoswap.org/portfolio-balance/?account=<coldkey>`
- Request note: Live positions are read from the chain, the balance chart is the historical record.
- Note: Live balances and pool reserves come straight from the chain, so the portfolio never lags behind your wallet. Switching to Realizable changes the value, and therefore every share, at once.

### Spot vs Realizable
- Source: in-app
- Definition: Spot prices your tokens at the pool price, as if size did not matter. Realizable estimates what you would actually receive selling them through the pool, fee and slippage included.
- Formula: `spot = balance × pool price; realizable = the same amount pushed through the weighted pool curve, after the subnet fee`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_in_pool, results[].alpha_in_pool`
- Request note: Realizable is simulated against the pool reserves, read live from the chain.
- Note: The gap between the two is the honest cost of your own size: it widens with the position and with how thin the pool is. Positions are simulated per subnet, and because the curve is non-linear per-position figures do not add up to the portfolio figure. For reference the chain refuses any single swap larger than 1000× the input-side reserve, but that guard is far beyond any real position and the simulation here does not model it.

### APY (α / τ / $)
- Source: api
- Definition: Your annualised return over a trailing window. α counts only the alpha you earned, τ adds what the alpha did against TAO, $ adds what TAO did against the dollar.
- Formula: `A gain annualises linearly: ((end − start) / start) × 365 / days × 100. A loss compounds: ((end / start)^(365/days) − 1) × 100, floored at −100%. Deposits and withdrawals are removed by rebuilding the end value as if they had never happened, both legs priced at the end of the window.`
- Request: `GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>`
- Response field: `apy.alpha, apy.tao, apy.usd, apy.days_observed (each keyed 7d / 30d / all)`
- Request note: The confidence rules on top of it are ours.
- Note: The asymmetry is deliberate: a linear gain stays readable on a young position, while a compounded loss cannot print below −100%, which is the real floor. The starting point is the first day in the window on which the wallet actually held something, so a dust prefix is skipped and "days observed" can be shorter than the window you picked. The three dimensions answer three different questions and diverge on purpose: a positive α with a negative τ means you earned tokens while their price fell. All three come back empty when the alpha return exceeds 1000%, which is how emission-funded and faucet wallets are kept from printing nonsense, and the absolute change is shown instead; on top of that the app flags a short sample below 14 observed days on the 30-day window and shows nothing at all below 4 days on the 7-day window.

### PnL (Realized / Unrealized)
- Source: api
- Definition: Realized is the profit or loss you have actually booked by closing positions. Unrealized is what you are up or down on what you still hold.
- Formula: `realized = proceeds − cost basis on disposals; unrealized = current value − cost basis on open positions, marked at the latest hourly close of each subnet (root 1:1)`
- Request: `GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>`
- Response field: `pnl.realized, pnl.unrealized (each: tao.wac, tao.fifo, usd_throughout, usd_then)`
- Request note: Computed over your whole trade history.
- Note: Unrealized marks your alpha at the hourly closing price, with no fee and no slippage, so it reads higher than the exit-value pricing used for validator and account totals: it answers "what is it worth", not "what would I get". Sending stake to another wallet books a real disposal at the market price inside Realized, and receiving it opens a fresh position at the price on arrival rather than inheriting the sender's basis. Both figures come in a WAC and a FIFO flavour (see Cost basis) and in two USD flavours. The 24h variants are the change since the previous daily snapshot rather than a rolling 24 hours, so they step once a day when the nightly sync runs; the baseline is anchored to the snapshot date, so a late sync shifts the window instead of breaking it.

### Cost basis (WAC / FIFO) & USD method
- Source: api
- Definition: Two ways of deciding what a token cost you. WAC averages every purchase into one blended price. FIFO matches each sale against your oldest purchases. Then two ways of putting that in dollars: "throughout" records the dollar value at every trade, "then" computes the result in TAO and converts it at today's rate.
- Formula: `WAC = Σ(amount × price) / Σ amount; FIFO = chronological matching, oldest lot first`
- Request: `GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>`
- Response field: `pnl.*.tao.{wac,fifo}, pnl.*.{usd_throughout,usd_then}`
- Note: WAC is smoother and easier to read; FIFO is what most tax regimes expect. Likewise "throughout" is the rigorous accounting answer and the only one that adds up over time, while "then" reprices your whole history at today's rate. Never read a difference between two dates in "then" mode: a week in which you did not trade at all can show a dollar gain or loss purely from the TAO/USD move, sometimes with the opposite sign to your TAO result. All four are available; the toggles only pick which one you see.

### Stake transfers (in / out)
- Source: api
- Definition: Alpha or TAO you moved to or received from another wallet, valued at the price when it moved. Shown for context, never added on top of your totals.
- Formula: `transfer_stake_* covers cross-coldkey alpha moves; transfer_tao_* covers plain TAO transfers (global only, always 0 per subnet)`
- Request: `GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>`
- Response field: `pnl.transfer_stake_in / _out, pnl.transfer_tao_in / _out`
- Request note: Cumulative, all-time, valued at the market price when the transfer happened.
- Note: A transfer out is already counted inside Realized as a disposal at market price, which is why adding these on top would double-count. On the receiving side the alpha arrives with a fresh cost basis at the market price of the day rather than the sender's basis, so moving stake between two wallets you both own resets your entry price. Moving alpha between your own hotkeys or subnets is a different operation and is not counted here at all.

## Trading

### Price impact
- Source: in-app
- Definition: How much worse your effective price is than the quoted pool price, because your own trade moves the pool. It grows with your size and shrinks with pool depth.
- Formula: `(output at the current pool price − output through the pool curve) / output through the pool curve × 100`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_in_pool, results[].alpha_in_pool, results[].fee_rate`
- Request note: Simulated against the live pool reserves.
- Note: The number shown covers the subnet fee as well as the curve movement, which is the whole cost of trading and therefore a safe floor for a slippage setting. It is not a fee paid to anyone: the difference stays in the pool, which is why splitting a large order into smaller ones genuinely costs less. Above ~1% the swap warns you, and above 5% it is worth splitting. Free TAO and root trade 1:1, so their impact is 0.

### Slippage tolerance
- Source: in-app
- Definition: How far the price may move against you between signing and inclusion before the chain refuses the trade. Default 0.5%, minimum 0.1%.
- Formula: `price limit = expected execution price × (1 ± tolerance), sent to the chain as the limit on the extrinsic`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_in_pool, results[].alpha_in_pool`
- Request note: The price limit is derived from the reserves and sent with the transaction.
- Note: It is applied on top of the expected execution price, which already contains the fee and your own price impact, so the tolerance only has to cover market movement, not the cost of the trade. Set it too low and ordinary movement makes the transaction fail. The chain enforces the limit, so a rejected swap costs you the network fee and nothing else, and with partial fill enabled it executes as much as fits inside the limit instead of rejecting everything.

### Minimum received
- Source: in-app
- Definition: The worst outcome you have agreed to: the least you can walk away with once your slippage tolerance is fully used up.
- Formula: `expected output × (1 − slippage tolerance / 100)`
- Request: `GET https://api.taoswap.org/v2/subnets/`
- Response field: `results[].root_in_pool, results[].alpha_in_pool`
- Request note: Derived from the simulated output.
- Note: A floor, not a forecast: a normal trade lands on the expected output, not on this. If the market moves past it, the chain rejects the trade rather than filling it worse, unless partial fill is on.

### MEV Shield
- Source: in-app
- Definition: Submits your swap encrypted, so nobody can read it while it waits in the queue and trade in front of it. It is only decrypted once its place in a block is fixed.
- Formula: `the swap is wrapped in an encrypted envelope and revealed a couple of blocks later, either through a relay (1 signature, relay pays the outer fee) or straight from your wallet (2 signatures)`
- Note: It costs a couple of blocks of latency, and in self-custody mode roughly twice the network fee, since two transactions are signed. The relay never sees the contents of your order. Each mode can be turned off on the server side, so the toggle is not always available.

### Network fee
- Source: in-app
- Definition: What the blockchain charges to include your transaction. TaoSwap takes no fee of its own.
- Formula: `estimated from the chain for the exact transaction being signed, doubled when MEV Shield runs in self-custody mode (two transactions)`
- Note: Not to be confused with the pool fee, which is the ~0.05% the subnet takes out of the token you put in and which is already inside every quote on the page. That pool fee is a per-subnet chain parameter, so it is not necessarily the same everywhere. The network fee is paid even when the trade is rejected for exceeding your slippage tolerance.

---
62 metrics across 11 categories. Canonical version: https://taoswap.org/glossary