DeFi Position Data: Lending, Borrowing and Liquidity
Represent deposits, debt, liquidity positions and claim tokens without equating a wallet balance with the complete economic position.
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.
DeFi position data describes relationships between an account and a protocol: supplied assets, borrowed amounts, liquidity positions or claims on a pooled arrangement. A token visible in a wallet may represent part of that relationship without describing the complete position.
A useful model retains protocol context and separates observed quantities from derived interpretations. It can explain debt, accrued components, missing valuations and positions whose meaning depends on an implementation version. Starting with these distinctions is more reliable than treating every visible token as an independent amount of spendable underlying assets.
Start with the protocol relationship
Identify the network, protocol deployment, relevant contracts or position identifier and the account relationship being observed. A protocol name can describe several deployments and versions. Retain the exact context used by the interpretation and its selected state boundary.
Define what the application means by a position. A lending account, pool share and individually identified liquidity position can require different fields. A consistent outer schema can carry these differences without forcing them into an ambiguous balance. Test deployments sharing the same display name. Storage, valuation and exports should retain their separate identities, versions and calculation rules, allowing a consumer to inspect the relationship behind the concise interface label.
Keep claim tokens and underlying assets distinct
An account can hold a token representing a claim on other assets. Claim quantity and underlying quantity are different observations or calculations. Preserve the conversion rule and observation boundary rather than renaming the claim as its underlying asset.
The ERC-4626 standard defines one model for tokenized vault shares and assets. Other mechanisms need their own interpretation. Record which rule applies and retain both units where relevant. Avoid adding a claim token and its represented underlying value to one total without an explicit policy preventing double counting. A useful export makes the selected presentation basis understandable while keeping both technical identities available for inspection.
Represent debt and collateral separately
A net-position headline can hide the quantities that produced it. Preserve supplied assets, debt, collateral status and other included components independently before deriving a net value. Different assets need suitable valuation inputs before they can be combined into a reporting unit.
The Aave documentation is one primary reference for lending and borrowing concepts. A general integration still needs an explicit observation scope. If a debt component or price is unresolved, show that boundary rather than claiming a fully known net position. Keep the known quantities and their references available so a later observation can complete the calculation without changing what was previously confirmed.
Describe liquidity positions in their own units
A pooled position can have a share quantity, an asset composition and accrued components. Some arrangements also need a range or position-specific configuration. These values should not be flattened into an unexplained token balance that hides how the claim is represented.
Retain the position reference, included assets and interpretation version. If an application derives underlying composition, record the state used. A synthetic example can hold a constant share quantity while its represented assets change. Explain that composition change rather than inventing a deposit or reporting a missing wallet transfer. Keep direct wallet holdings distinct from assets represented through the position when constructing a combined portfolio view.
Derive a value after the components are understood
Valuation adds price observations, quote units and cutoff policy to position components. Keep this layer separate from quantities so a changed price does not rewrite the underlying relationship. The selected prices should be compatible with the position observation and the stated reporting question.
A synthetic case can contain two asset components and one debt quantity with an unavailable price. The known components remain useful, but a complete net value is unresolved. Do not treat the unknown liability value as zero. Preserve excluded components and reasons in both interface and export, letting a reviewer understand the visible total and decide which missing input is needed to finish it.
Explain changes with observations and method versions
A position value can change through deposits, withdrawals, accrued components, price movements or a revised interpretation. Track these causes separately where supported. A changed headline value is not by itself a realized gain, a reward distribution or a cash movement.
Test a new position, a closed position, a claim token, an unresolved debt component and repeated processing. Keep references and versions so revisions can be explained. Useful position data offers a technical picture of the included relationship while leaving accounting decisions, risk policy and transaction execution in their own workflows. A consumer should be able to revisit the record without relying on a single number whose component assumptions have disappeared.
Questions about the topic
Frequently asked questions
Is a wallet balance enough to describe a DeFi position?
Not always. A relationship can include underlying claims, debt, collateral and accrued components needing separate observations and interpretation. Retain the mechanism behind each quantity.
Can claim tokens and represented assets both contribute to a total?
Only under a clear policy preventing double counting. Preserve both identities and units while documenting which representation contributes to the chosen aggregate.
What if a debt or price is unavailable?
Keep known quantities and the unresolved component separately. A useful partial view should not turn an unknown liability or valuation into zero to produce a complete-looking net headline.
Standards & technical documentation
