Liquidity Provider Positions: Tokens, Ranges and Fees
Represent liquidity positions with pool identity, price ranges and claimable fees, instead of flattening every position into a simple token balance.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A liquidity position can involve two assets, a range and fee accounting. A position token may represent that claim, but its wallet balance alone does not explain the assets or fees economically associated with it.
Preserve position dimensions
Record pool, fee tier, position identity and the relevant range where the protocol uses concentrated liquidity. Distinguish liquidity units from token amounts. Fee growth and collected fees are different measurements. A position outside the current price range can have a different asset composition from one actively spanning the market price.
Worked example: unchanged position, changed mix
A wallet keeps the same position while the pool price moves through its range. The estimated quantities of the two underlying assets change without a wallet-level transfer of the position token. A holdings report needs a state-dependent position calculation rather than a fixed amount assigned when the position was first created.
Track claims and collections separately
Store calculation block and protocol version. Test added liquidity, partial removal and fee collection without position closure. Do not count claimable fees as both an existing asset holding and a new inflow when collected. Keep principal estimates, accrued fees and realised movements distinct so downstream totals can choose a consistent treatment.
A practical acceptance test
Use one range position with unchanged liquidity units across a price movement. Assert that its estimated token composition can change independently of position-token transfer history. Then collect fees without removing liquidity. The holdings view must not duplicate those fees as both outstanding claim and newly received asset after reconciliation of the claim state.
Questions about the topic
Frequently asked questions
Are liquidity units ordinary token units?
No. They describe a protocol-specific position quantity.
Does collecting fees close the position?
Not necessarily; collection and liquidity removal are distinct operations.
Standards & technical documentation