Aave V3 Position Tracking: aTokens, Debt Tokens, and the Health Factor

What makes an Aave V3 position unlike any plain token holding is that the asset you supplied grows in your wallet on its own through the aToken mechanic, the debt you took grows too as a variableDebtToken, and a single oracle move can liquidate both legs at once. A balance snapshot misreads all three. This guide is the aToken/debt-token model and what it changes for tracking. It is one spoke of the broader multi-wallet aggregation problem, narrowed to a single lending protocol's accrual mechanics.

What's unique about an Aave V3 position

• Supply gives you aTokens (e.g. aUSDC) whose balance grows as interest accrues, "interest in the balance" rather than a fixed deposit.
• Borrowing creates variableDebtTokens that also grow with accrued interest, a liability that compounds against you.
• The real position is the collateral leg netted against the debt leg, never the supply side read alone.
• The Health Factor moves with oracle prices and accrued interest; below the threshold it triggers a liquidation, a real economic event.
• aToken balances change without any transfer (the scaled-balance design), so transfer-only ingestion misses the accrual entirely.
• Tax characterisation is jurisdiction-specific: track the mechanics, confirm tax separately.

Supply: a balance that grows by itself

Supply an asset to Aave V3 and you receive aTokens (e.g. aUSDC). The defining property is that interest accrues into the aToken balance: balanceOf() rises over time with no new transfer. So a tracker that treats the aToken as a fixed deposit is wrong from block two onward. The balance is continuously changing, and the growth must be attributed as accrued yield, not read as mysterious inflows or, worse, as phantom acquisitions.

Borrow: a liability that grows too

Borrowing creates variableDebtTokens (e.g. variableDebtUSDC) tracking the outstanding debt plus accrued interest, so the debt side grows as well. A correct Aave position is:

net = aToken collateral − variableDebtToken debt

Reading only the supply side overstates the position and ignores a growing liability. The position is a pair, and both legs move.

The Health Factor

Aave's Health Factor is the risk metric. It moves with:

• collateral and debt values (oracle prices plus accrued interest);
• per-reserve liquidation thresholds.

Below the threshold the position is liquidatable, and a liquidation is a real economic event that changes both legs. A tracker that ignores the Health Factor sees a position "suddenly change" with no explanation; the explanation is the liquidation, and it must be modelled as such.

Why the balance moves with no transaction

Aave V3 uses a scaled-balance design for gas efficiency: internally a scaled value is stored and the displayed balance is derived via an index, so the visible balance grows without a per-block transfer. The tracking consequence is sharp. A tool that only ingests transfer events misses the accrual entirely; it must read the derived balance and attribute the change, the same "don't trust a transfer-only view" lesson as DeFi position reconciliation.

How the scaled balance index works

Aave stores a scaledBalance for each aToken holder and a liquidityIndex for each reserve. The actual balance is computed as:

balance = scaledBalance × liquidityIndex / 10^27

The liquidityIndex increases over time as interest accrues. To correctly compute the aToken balance at any point in time, the tracker must query either balanceOf() (which runs this formula on-chain) or retrieve the scaledBalance and the current liquidityIndex from the DataTypes.ReserveData storage. Querying only the scaledBalance and treating it as the nominal balance understates the position from the first block after deposit.

Step-by-step: how to track an Aave V3 position

1. Identify the pool address. On Ethereum mainnet the Aave V3 Pool is at a known address. Each deployment (Polygon, Arbitrum, Optimism, Avalanche, etc.) has its own pool address. Confirm from the Aave V3 deployments registry.
2. Call getUserAccountData(user) on the Pool contract. This returns totalCollateralBase, totalDebtBase, availableBorrowsBase, currentLiquidationThreshold, ltv, and healthFactor — all in USD with 8 decimals. Use this for the net position overview and to monitor liquidation risk.
3. Read individual reserve positions via getUserReserveData(asset, user). This returns the currentATokenBalance, currentStableDebt, currentVariableDebt, and liquidityRate per reserve. The currentATokenBalance already applies the index and reflects accrued interest.
4. Snapshot balances at regular intervals (or at each transaction block) to compute accrual since the last snapshot. The difference between two currentATokenBalance readings with no supply/withdraw transactions is pure interest accrual.
5. Subscribe to LiquidationCall events on the Pool for each monitored user address. When triggered, record the collateralAsset, debtAsset, liquidatedCollateralAmount, debtToCover, and liquidator. This is the event that explains an otherwise mysterious position collapse.
6. Track Supply, Withdraw, Borrow, Repay, and FlashLoan events for the complete transaction history.
7. Apply the jurisdiction cost-basis method to supplies, withdrawals, and liquidation events; confirm interest accrual characterisation with an adviser.

Common errors and how to fix them

Error 1 — Reading aToken balance at deposit as permanent. The balance at supply time is the initial amount, but it grows daily. A tracker that caches the balance on deposit and only updates on the next supply/withdraw transaction silently under-counts the position. Fix: read currentATokenBalance (the derived balance) at each portfolio snapshot, not from the supply transaction amount.

Error 2 — Ignoring variableDebtToken growth. Borrow interest also accrues continuously. A position tracker that only monitors the supply side and omits the debt leg overstates net exposure by the full outstanding debt plus accrued interest. Fix: always read currentVariableDebt alongside currentATokenBalance and compute the net.

Error 3 — Booking a liquidation as an unexplained withdrawal. When a position is liquidated, collateral leaves the wallet without a Withdraw event from the user. A tracker relying only on user-initiated transactions will show collateral disappearing inexplicably. Fix: monitor the LiquidationCall event on the Pool contract for the user address as the user parameter.

Error 4 — Missing aToken positions on non-mainnet deployments. Aave V3 is deployed on many chains and L2s with separate pool contracts. An aggregator that only checks the Ethereum mainnet pool will miss positions on Polygon, Arbitrum, Optimism, Avalanche, and others. Fix: query every chain's Aave V3 pool address for each user address in the inventory.

Tax is jurisdiction-specific

Whether supplying is a disposal of the underlying, whether the accrual is income, and how a liquidation is treated are framework- and jurisdiction-specific and must not be assumed (see cost-basis methods and yield farming tracking). The mechanics above are the tracking layer; the tax characterisation is a separate, adviser-confirmed question.

Practical guidance

1. Treat aTokens as growing balances, not fixed deposits, and attribute the accrual.
2. Always net collateral against debt, tracking variableDebtToken growth too.
3. Model the Health Factor so liquidations are explained, not surprises.
4. Read derived balances, not just transfer events (scaled-balance design).
5. Confirm tax characterisation of supply, accrual and liquidation per jurisdiction.
6. Reconcile the position pair to the protocol with an audit trail.

Choosing a tool for Aave V3 positions

Most general crypto-tax tools, including Koinly and CoinTracker, claim to model lending positions, but Aave's accrual mechanics expose where that support is thin. Before you trust an Aave figure, confirm the tool:

• reads the derived currentATokenBalance at each snapshot rather than caching the deposit-time amount, so the daily accrual is captured;
• nets the variableDebtToken leg against the aToken leg instead of reporting the supply side alone;
• ingests the LiquidationCall event so a liquidation is modelled as an event, not an unexplained collateral disappearance;
• queries every chain's Aave V3 pool, not just Ethereum mainnet, so Polygon, Arbitrum, Optimism and Avalanche positions are not silently dropped.

A tool that books accrual growth as phantom acquisitions is making the recurring Aave mistake, and the clean-looking number it returns will not reconcile to the protocol.

How Wag3s handles it

Wag3s Folio reads Aave V3 aToken and variableDebtToken derived balances, attributes interest accrual to the right category, nets the collateral and debt legs, models Health-Factor liquidations as discrete events, and surfaces the result for the jurisdiction-specific tax characterisation. See the Folio product page.

Further reading

• DeFi Lending Position Tracking
• Rebasing vs Non-Rebasing Token Tracking
• DeFi Position Reconciliation
• Yield Farming Tracking
• Crypto Cost Basis Methods 2026
• Liquidity Pool Accounting

Sources

• Aave — Aave V3 documentation: aTokens (interest accrues into the balance, balanceOf grows), variableDebtTokens (outstanding debt plus accrued interest), the scaled-balance/index design, and the Health Factor with per-reserve liquidation thresholds.