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 field
apy.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 field
results[].dividend_shares, results[].dividends_taoToday'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 feeClaimable 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 rateWAC 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 field
pnl.*.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 bothThe 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 field
results[].price, results[].root_in_pool, results[].alpha_in_poolBoth 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.
- 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 PnLUnrealized 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 field
pnl.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 claimA 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 field
results[].dividends_tao, results[].stake_tao_days, results[].staked_days, results[].completeOne 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 cumulativeA 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 field
pnl.transfer_stake_in / _out, pnl.transfer_tao_in / _outCumulative, 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 readingA 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 field
results[].dividend_shares, results[].bought_shares, results[].bought_tao, results[].stake_tao_days, results[].bought_tao_days, results[].staked_days, results[].bought_daysToday'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 subnetsA 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_outResponse field
results[].tao_rao, results[].tao_price_usdThe product is taken in the app; tao_rao is in rao, so divide it by 10^9 for τ.