Price Change vs Portfolio Return in Crypto Analytics
Distinguish an asset’s price movement from a wallet’s investment return, including deposits, withdrawals, fees and changing position sizes.
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 token price change is not the return earned by every holder. Wallet-level performance also depends on when quantities changed, external cash flows and the treatment of fees.
Define the measured object
A simple asset price return compares two compatible price observations. A portfolio return compares a changing set of holdings and may need time-weighted or money-weighted methods. Neither can be derived from a closing balance alone. State the valuation currency, period and external-flow treatment before displaying a performance percentage.
Worked example: a late deposit
An asset doubles over a month, but a wallet buys most of its holding just before month-end. Reporting the asset’s monthly doubling as the wallet’s return overstates that wallet’s experience. Preserve transaction timing and quantities, and apply a performance method suited to the reporting question.
Test cash-flow boundaries
Include deposits just before and after valuation cutoffs, withdrawals and fees in another asset. Distinguish investment gains from additional capital. If purchase or opening-value evidence is missing, present a partial calculation or unknown return instead of inferring a cost from today’s price. Keep the formula and input observations available for review.
A practical acceptance test
Use a token that doubles before a wallet makes its main purchase. Assert that the asset’s period return is not copied into the wallet-performance field. Add a deposit near the valuation boundary and verify the chosen flow-adjustment method. Missing opening values should produce an incomplete result rather than a confident percentage from closing holdings alone.
Questions about the topic
Frequently asked questions
Does a doubled token price mean every holder earned 100 percent?
No. Position timing and cash flows matter.
Can a wallet balance establish return by itself?
No. Performance needs appropriate opening values and flow information.
Standards & technical documentation
