Glossary

What each metric means, its exact formula, the API request behind it, and why it can differ from other explorers.

Guides, help and developer docs: docs.taoswap.org

For AI agents: llms-full.txt

APY (α / τ / $)

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. The position tables show τ and $ as the window's own return, not annualised.

FormulaPer position, time-weighted: each day's growth is measured on the alpha held that day, so a buy or a sale inside the window never reads as yield, and τ follows the subnet's end-of-day price rather than the position's exit value. Portfolio-wide, α chains the same days across your positions, each valued at its subnet's price that day; τ and $ stay organic: (end value rebuilt as if you had never deposited or withdrawn − starting value) / starting value, the alpha leg of your own flows removed then repriced at the end of the window and the TAO leg removed at the amount that actually moved. Both annualise over the days actually observed: a gain linearly, × 365/days; a loss compounds, ((end / start)^(365/days) − 1), and reads exactly −100% only when the position is emptied.

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 not simply the first day you held something: it is the first day you held at least 1% of your peak alpha for that window, which is what stops a dust prefix from printing an astronomical return, and it is why "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. Empty cells have several causes, not one: an alpha return above 1000% blanks all three (the guard against emission-funded and faucet wallets, with the absolute change shown instead), a wallet holding only root, basket shares or free TAO has no α dimension portfolio-wide, so that one alone stays empty in the Returns card while the Staked TAO row still fills its own α cell (root α is τ, and the root line is the stake with its claimable rewards), and a window with no qualifying starting day is empty throughout. A position, and the α of the whole portfolio, observed under 7 days get no annualised rate, and on a 30-day window the app flags a sample shorter than 15 observed days.

API request
GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>

Response fieldapy.alpha, apy.tao, apy.usd, apy.return_tao, apy.return_usd, apy.days_observed (each keyed 7d / 30d / all)

The confidence rules on top of it are applied in the app.

Basket move (your position)

What the basket has done with the dividends your root stake earned since your last claim: those shares at their value today against their value when paid. Not annualized.

Formula(dividend_shares × today's value per share / dividends_tao − 1) × 100, today's value per share = your position's value / your owed shares (the owed shares at the basket's realizable NAV)

It isolates what Root APY (your position) leaves out by pricing each dividend when paid: positive when the alpha the basket holds gained against TAO since, negative when it lost. Shown as soon as there are dividends to compare, with no 7-day minimum, and a dash when the API's history does not reach back to your last claim. Shares you bought are not in it; Total APY (your position) counts them.

Data source
GET https://api.taoswap.org/v1/portfolio-root-yield/?account=<coldkey>

Response fieldresults[].dividend_shares, results[].dividends_tao

Today's value per share comes from the chain: your position's value over your owed shares, both from BetaBasketRuntimeApi.get_root_basket_positions.

Claimable / Claim fee / Worth claiming

In the Root Staking dialog, per validator: what claiming its basket would move to your root stake right now, what that claim costs, and what it leaves once paid. Total claimable, at the foot of the dialog, adds up every basket's Claimable.

Formulaclaimable = the chain's own preview of that claim: your owed shares, once the basket has credited the dividends it holds in queue, × the realizable value of its holdings without the dust slices the claim skips / every share. claim fee = the node's quote for a claim, flat whatever the basket holds, doubled for a redemption (a basket holding bought shares) that signs its own MEV Shield envelope, the envelope counted as one more claim fee, an upper bound. worth claiming = (claimable under the chain's claim minimum ? 0 : claimable) − claim fee

Claimable can differ from the Value of the Basket shares table either way: the preview first credits the queued dividends, then leaves the dust slices in the basket for its other holders (the info mark estimates them); without a preview it is that Value. Under the chain's claim minimum (0.0005 τ by default) a claim takes nothing and still pays its fee, so the row's Claim is disabled and Worth claiming is minus the fee; a negative figure means the claim costs more than it returns, for now. The chain takes each fee up front from your free TAO, one transaction and one signature per basket. Claim all skips the baskets under the minimum and those holding bought shares, which are redeemed on their own row since a claim would sell the purchase too, while Total claimable counts every basket and is the amount on the button that opens the dialog. Until the node quotes the fee, the dialog shows 0.008251 τ, the flat fee measured at runtime 468.

Cost basis (WAC / FIFO) & USD method

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.

FormulaWAC: one running (quantity, cost) pair per hotkey and subnet. A buy adds its cost, a sale drains the cost pro-rata, staking rewards enter at zero cost, a same-subnet move carries its cost to the new hotkey, and a cross-subnet swap closes the position at the pool price and opens the destination one at what it paid. FIFO: the same events against a queue of lots, oldest consumed first. usd_throughout books each leg at the TAO/USD rate of the hour it happened (the day's close before February 2024, where the hourly record starts); usd_then converts the finished TAO result at today's rate

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. Where the toggles apply is narrower than it looks: the four flavours are all served, but only the PnL dialog lets you switch between them. The holdings table is fixed on WAC in TAO, and the CSV export always writes FIFO with the throughout dollars, whatever you had selected.

API request
GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>

Response fieldpnl.*.tao.{wac,fifo}, pnl.*.{usd_throughout,usd_then}

Market price vs If sold now

The two ways the portfolio can value your alpha, picked in Settings under Portfolio value. Market price counts every token at its pool's current price, as if size did not matter; If sold now estimates what selling everything right now would pay, so a large position gets a lower price.

Formulamarket price = α held × the pool's spot price. If sold now = per wallet and subnet, all that wallet's α on the subnet sold at once into the pool at constant product on the raw reserves, no fee: τ received = TAO reserve × α / (alpha reserve + α), then split over the wallet's hotkeys in proportion to their α. Free TAO and root count 1:1 in both

The gap is the cost of your own size: it widens with the position and with how thin the pool is. One sale per wallet and subnet is what a full exit would pay, and the rule the stored balance history follows, so the chart's live point continues it; a single hotkey's α sold alone would fetch more per alpha than its share of the joint sale. It is not the swap page's quote, which also takes the pool's fee and follows its weights, so a real sale lands slightly apart, usually lower. The choice moves the Total Balance, every row, share and slice, the chart with its 1D, 7D and 30D changes, and the Σ total on the swap card; Market price is the default, and beside its Total the If sold now figure shows once the gap passes 5% (basket shares aside, which keep their own value in both). Where Settings does not offer the choice, the page reads at market price while the chart and its changes read if sold now. Chart points stored before the market price was recorded keep their sale value, so a market-price line steps where those records begin.

Data source
GET https://api.taoswap.org/v2/subnets/

Response fieldresults[].price, results[].root_in_pool, results[].alpha_in_pool

Both are computed in the app against the pools read live from the chain. The stored history carries both: /portfolio-balance/ results[].staked_alpha_spot_in_tao and results[].staked_alpha_in_tao.

Net (basket shares)

Your whole position in one validator's basket, root rewards included, against what you paid for the shares you bought into it since your last claim of it: the Net column of the Basket shares table.

Formulanet = value − paid, in τ; net % = (value − paid) / paid × 100. value and paid as in Value / Root rewards / Paid / Gain or loss (basket shares): your owed shares at the basket's realizable NAV, and the τ your purchases of this basket cost since your last claim of it

Without purchases nothing was paid, so the net is the root rewards alone and carries no percentage. Root rewards cost nothing, so on a position that mixes them with purchases the net reads well above the Gain or loss of the purchases alone. A claim or a redemption takes the whole position, so paid restarts at zero after one. Empty while the cost of the purchases cannot be read.

Data source
GET https://api.taoswap.org/v1/beta-baskets/{hotkey}/cost-basis/?coldkey=<coldkey>

Response fieldpaid_tao

The value is read from the chain, as your owed shares at the basket's realizable NAV; the endpoint gives what your purchases since your last claim of the basket cost.

PnL (Realized / Unrealized)

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.

FormulaRealized: for every sale (a plain unstake, a transfer out, or the origin side of a cross-subnet swap or move, which the chain executes as a sale in the origin pool), and every burn, the proceeds minus the cost basis consumed. Unrealized: what you hold on-chain × the latest hourly close of its subnet, minus the cost basis left against it. Root counts as cash, like free TAO, and carries no PnL

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". Swapping or moving alpha to another subnet goes through both pools, so it books the gain or loss on the subnet you leave and the destination position starts at what the swap paid for it; moving alpha between two of your hotkeys inside one subnet realizes nothing and carries its cost across; a burn realizes the full loss. 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. Realized 24h is the change since the previous daily snapshot rather than a rolling 24 hours, so it steps once a day; the baseline is anchored to the snapshot date, so a late sync shifts the window instead of breaking it, and the payload names the date it started from. Unrealized 24h is a different animal: a live trailing window, what you hold right now × (price now − price 24 hours ago), recomputed on every request with no cost basis involved, so it moves with the market all day and exists from the first day you hold something.

API request
GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>

Response fieldpnl.realized, pnl.unrealized (each: tao.wac, tao.fifo, usd_throughout, usd_then); rolling_24h.unrealized_tao (live 24h, global and per subnet)

Computed over your whole trade history.

Root APY (your position)

What your own root stake with one validator was paid since your last claim of its basket, per year: the dividends at their value when paid, against the stake you actually held. It is your rate, not the validator's, which the Root Staking dialog shows as Validator APY (see Root staking APY).

Formula((1 + dividends_tao / stake_tao_days)^365 − 1) × 100, the τ paid per τ·day of root stake compounded daily over a year. dividends_tao = the basket shares your stake earned between each pair of consecutive basket readings (your average stake × the shares the basket minted per staked τ in between), each priced at the average share price of those two readings; stake_tao_days = your stake × the days held, from the first to the last reading since your last claim

A dash until your stake has been held 7 days since your last claim, while the basket has fewer than two readings since then, and when the API's history does not reach back to that claim (a stake held since before the history starts, until a claim restarts the window, or a basket that restarted). Readings are hourly, daily before the hourly ones begin, so the rate moves once an hour. Stake added or removed counts only for the time it was held, which is why the rate can differ from Validator APY, measured on 1 τ staked through the validator's own window. Never negative: a dividend is a payment, and what the basket made of it since is the Basket move (your position).

Data source
GET https://api.taoswap.org/v1/portfolio-root-yield/?account=<coldkey>

Response fieldresults[].dividends_tao, results[].stake_tao_days, results[].staked_days, results[].complete

One row per validator, matched on results[].hotkey; the rate itself is computed in the app.

Stake transfers (in / out)

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.

FormulaStake transfers: alpha that entered or left this wallet through a wallet-to-wallet transfer on a subnet other than root, counted at the TAO value the chain recorded for the move, plus its dollar value at the TAO/USD rate of that hour. TAO transfers: plain TAO in and out of the free balance, plus root stake sent to or received from another wallet, whole-wallet only. Both are all-time cumulative

A transfer of alpha out is already counted inside Realized as a disposal at market price, which is why adding these on top would double-count. Root carries no PnL, so root stake moved between wallets counts with the TAO, like cash. 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.

API request
GET https://api.taoswap.org/portfolio-pnl-apy/?account=<coldkey>

Response fieldpnl.transfer_stake_in / _out, pnl.transfer_tao_in / _out

Cumulative, all-time, valued at the market price when the transfer happened.

Total APY (your position)

What your whole position with one validator made since your last claim of its basket, per year: the dividends and the shares you bought, both at their value today, less what the purchases cost, against the root stake and the τ of purchases you held over that time.

Formula((1 + (position now − bought_tao) / (stake_tao_days + bought_tao_days))^365 − 1) × 100. position now = (dividend_shares + bought_shares) × today's value per share (your position's value / your owed shares); bought_tao = the τ those purchases cost; bought_tao_days = each purchase's τ × the days it was held, from its block or the window's first reading, whichever is later, to the last reading

A dash until the stake, or the oldest purchase since your last claim, has been held 7 days, and when the API's history does not reach back to that claim. Valued at today's prices, it can be negative, unlike Root APY (your position). Without purchases it prices the same dividends as Root APY (your position), at their value today instead of when paid, so the gap between the two comes from the Basket move (your position).

Data source
GET https://api.taoswap.org/v1/portfolio-root-yield/?account=<coldkey>

Response fieldresults[].dividend_shares, results[].bought_shares, results[].bought_tao, results[].stake_tao_days, results[].bought_tao_days, results[].staked_days, results[].bought_days

Today's value per share comes from the chain, as for Basket move (your position).

Value (transfers)

What a row of the Transfers table was worth in dollars when it moved: its τ, or on an alpha transfer the τ the chain recorded for the move, at the TAO price of that hour.

Formulavalue = tao_rao / 10^9 × the TAO/USD price of the hour holding the block, else the closest hour before (the day's close before February 2024, where the hourly record starts). tao_rao = the τ sent or received; on an α transfer, the τ the chain recorded on your side of it: α × the pool's spot price inside one subnet, where no pool is used, or the τ that went through the pools when the transfer crosses subnets

A value at the time, not today: Value now, a column of the Transactions table, prices the τ at the current rate instead. A dash when the row carries no τ or no price covers its hour. On an α transfer it states what the α was worth when it moved, not what it is worth now. These are the transfers one by one; the PnL dialog keeps their all-time totals (see Stake transfers (in / out)).

Data source
GET https://api.taoswap.org/v1/account-ledger/?account=<coldkey>&kinds=tao_transfer_in,tao_transfer_out,alpha_transfer_in,alpha_transfer_out

Response fieldresults[].tao_rao, results[].tao_price_usd

The product is taken in the app; tao_rao is in rao, so divide it by 10^9 for τ.

Value (τ) / Share

What a position is worth in TAO under the valuation the page uses, and how much of the Total Balance it represents.

Formulavalue = the position at Market price or If sold now, whichever the page uses (see Market price vs If sold now), free TAO and root at 1:1. share = value / Total Balance × 100, the Total Balance being every position held, in the same valuation, plus your basket shares

Live balances and pool reserves come straight from the chain, so the portfolio never lags behind your wallet. Switching the valuation changes every value, and therefore every share, at once. Under If sold now each hotkey row carries its part of the wallet's one sale on that subnet, so the rows of a subnet add up to it. The basket shares (root rewards and any shares you bought) take a row of their own, one line per basket, at your owed shares × that basket's realizable NAV whichever valuation the page uses: they leave through a claim, never through a swap, which is why the Staked TAO row counts the stake alone. The chart's Rewards / Basket button draws that series alone. The If sold now column always shows the sale value, whatever the page's valuation.

Data source
GET https://api.taoswap.org/portfolio-balance/?account=<coldkey>

Response fieldresults[].staked_alpha_spot_in_tao, results[].staked_alpha_in_tao, results[].root_rewards

Live positions are read from the chain; this is the stored history the balance chart draws, the alpha valued both ways and the basket shares apart.

Value / Root rewards / Paid / Gain or loss (basket shares)

Your shares of one validator's basket, as the Basket shares table and the Your position card of a validator page state them: what they are worth, how much of it is root rewards, what the shares you bought cost, and the gain or loss on those purchases alone. Share of basket is the part of the whole basket they make up.

Formulavalue = min(owed shares × realizable NAV / every share of the basket, realizable NAV), the NAV being what selling each holding whole through its pool would pay, no fee, added up; owed shares = your root stake × the basket's accumulated shares per staked τ, less those already claimed, bought shares included. paid = the τ your purchases cost since your last claim of this basket; bought part = value × min(1, shares those purchases received / owed shares); gain or loss = bought part − paid, in τ and as % of paid; root rewards = value − bought part, the whole value without purchases. share of basket = owed shares / every share of the basket × 100

Read from the chain, not from the API's snapshots, when the page loads and after each claim; dividends the basket has queued and not credited yet are in neither the shares nor the NAV. This value is what the Basket shares row in Balances adds up, before the dust slices a claim skips, so the Root Staking dialog's Claimable can differ (see Claimable / Claim fee / Worth claiming). Root rewards cost nothing and stay out of Gain or loss, which judges the purchases alone at the same NAV: a fresh purchase reads as a small loss at once, since the τ it pays buys the basket's holdings through their pools and adds less than that to the NAV. A claim or a redemption takes the whole position, bought shares included, so Paid restarts at zero after one. Root rewards, Paid and Gain or loss stay empty while the cost of the purchases cannot be read, and on a validator page until the API has read your latest purchase or redemption there, so a purchase it has not counted never reads as root rewards. The table hides baskets worth under $10 until Show dust.

Data source
GET https://api.taoswap.org/v1/beta-baskets/{hotkey}/cost-basis/?coldkey=<coldkey>

Response fieldpaid_tao, shares

The value and the share of basket are read from the chain (BetaBasketRuntimeApi: get_root_basket_positions for the owed shares and their value, get_validator_basket_summary for every share); the endpoint gives what your purchases since your last claim of the basket cost and the shares they received.