Building a Crypto Portfolio Tracker: Holdings, Value and Performance
Keep observed holdings, protocol positions, price inputs and performance methods distinct when assembling a combined portfolio view.
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 crypto portfolio tracker can display assets, protocol positions and a total value in one convenient screen. Underneath that screen are several questions: what is held, which observations are included, how are they valued and what explains a change over time?
Treat those questions separately before building a headline total. A useful tracker preserves exact quantities, network identities and observation cutoffs. It then adds a documented valuation and performance layer, allowing users to inspect missing inputs or understand why a later recalculation differs from an earlier view.
Define the portfolio population and observation boundary
List the included accounts, networks and supported record types. A selected account set is not a claim about every asset a person may control. Retain that scope with the observation, including any network or account whose retrieval remains unresolved.
Choose compatible cutoffs for a historical view and state how current observations are combined when exact simultaneity is unavailable. A synthetic portfolio can include two networks with accepted observations and a third whose request failed. Keep the known holdings visible while identifying the unresolved network scope. The interface should not present the same total-completeness label for a fully inspected population and a useful partial view merely because both return a number.
Keep exact holdings beneath display grouping
Preserve qualified asset identities and original quantities before grouping familiar symbols or related representations. Two similarly named tokens need not be interchangeable. A portfolio can intentionally group them for navigation while retaining distinct members and units.
Display rounding should not alter stored quantities. Keep unknown decimals or metadata separate from a known atomic amount. Test two contracts sharing a symbol and a large quantity requiring exact representation. Follow their identities through charts, search and exports, because a correct backend key is insufficient if the frontend cache or CSV uses only a display name. The grouped view should offer a route back to the original observations and the policy that combined them.
Add protocol claims and liabilities without double counting
Protocol positions can include claims on assets, debt and accrued components. A claim token visible in a wallet may overlap with the position shown in a separate section. Define which representation contributes to the aggregate so the same included value is not counted twice.
Retain the position components, units and conversion observations separately. The DeFi position guide explains this relationship. A synthetic portfolio can hold a claim token representing underlying assets and also display its protocol position. Test that the chosen presentation policy keeps both inspectable while counting the intended representation once. An unavailable debt component should remain unresolved rather than disappearing from an otherwise complete-looking net total.
Apply prices as a separate, timestamped layer
A valuation needs base and quote identities, accepted price observations and rounding rules. Preserve those inputs with the quantity cutoff so another developer can reproduce the result. A price update should not rewrite the holding being valued.
Keep unpriced assets in the population. The tracker can show their known quantities while identifying that a displayed value total excludes them. Distinguish an unavailable price from a confirmed zero. For historical reports, retain the actual observation timestamp and permitted staleness policy. A current quote should not silently stand in for a historical requested boundary. The price guide provides the separate calculation contract needed by this layer.
Separate value changes from gains and cash flows
A larger ending value can reflect deposits, withdrawals, price changes, rewards or newly inspected accounts. It is not automatically investment profit. Define the performance question and retain principal-flow treatment, fees, period boundaries and any cost-basis policy relevant to the application.
A synthetic portfolio starting at 100 reporting units and ending at 130 after a 30-unit external contribution does not establish a 30-unit gain. The example illustrates why flows need separate evidence. Different performance methods answer different questions, so name the method rather than publishing an unexplained PnL label. Application-specific accounting and tax interpretations should remain separately versioned decisions over the retained observations and calculation inputs.
Make refreshes and revisions understandable
Track which account observations and valuation inputs contributed to a view. When a total changes, identify whether the cause was market valuation, a movement, broader account scope or a corrected interpretation. Preserve completed report context rather than silently replacing it with the latest dashboard state.
Test repeated retrieval, missing prices, partial network failure, a claim-token overlap and a new external contribution. Check exports as well as the main screen. A useful tracker can provide a concise portfolio summary while retaining the evidence needed to investigate it. Its goal is an explainable view of a declared population, with clear units and unresolved boundaries, rather than a confident number whose component assumptions cannot be recovered later.
Questions about the topic
Frequently asked questions
Does a rising portfolio value prove a profit?
No. Contributions, withdrawals, changed coverage and valuation inputs can change the total. A performance result needs its own defined method and treatment of flows and fees.
Should unpriced assets disappear from the portfolio?
No. Preserve known quantities and identify the missing valuation input. A partial value total should disclose which holdings or position components were excluded.
Can a claim token overlap with a DeFi position?
Yes. Retain both observations and apply an explicit policy preventing double counting in the aggregate. A concise view should still allow inspection of each original identity and conversion input.
Standards & technical documentation
