The Holdings API includes PnL and historical holdings endpoints. If you are interested in testing the Holdings API or need portfolio data for other chains, please reach out to our team.

​
Historical Holdings

It provides comprehensive realtime and historical coverage of USD holdings for a given wallet. These endpoints are based on balance history and price data aggregated over set granularities. Prices are derived from Allium’s real-time DEX trade feeds. Holdings are aggregated at 15s, 5m, 1h, and 1d level granularities with corresponding retentions. Key Features:
  • Real-Time & Historical Data: Latest balances & prices update in real time, while historical holdings data is available for tracking portfolios over time.
  • Aggregated Coverage: USD Holdings for each wallet is aggregated over all tokens that a user holds and returned at set time granularities.
  • Single Call Multi-chain Support: Request aggregated holdings across several chains in a single API call.
  • PnL Calculation: Calculate the PnL of a portfolio over a given time period.
Current Limitations & Roadmap:
  • Currently, the Holdings API only supports Bitcoin and Solana.
  • Support for additional chains and liquidity pool-based pricing is in development.

​
PnL

PnL calculation requires knowing the average cost of a wallet’s tokens. Average Cost is based on the average cost basis method calculated by taking a weighted average of all token purchases and reweighting the average cost during sale events.

​
Methodology

  • PnL calculation is based on token balances
  • Realized PnL is calculated by multiplying the number of tokens sold with the difference between sold price and average price
  • Unrealized PnL is calculated by multiplying the number of tokens held with the difference between current price and average price

​
Latest PnL

How is Latest PnL calculated? PnL is calculated using the following formula:
Latest PnL = Current Balance(Token) x (Current USD Price(Token) - Average Cost(Token))
Where:
  • Current Balance(Token) = Latest balance of the token for the given address
  • Current USD Price(Token) = Latest price of the token in USD
  • Average Cost(Token) = Average cost of the token for the given address
Important notes and error handling
  • Invalid data (such as unsupported chains or invalid address/token address) returns status code 400.
Example Each row represents a user interaction and what the PnL would be if the user checked the app following the interaction.
Buy/SellTokenAmtBalancePriceAvg Cost CalculationPnL
BuySOL5050$210(50 * $210) / (50)0
BuySOL1060$200(50 * 210)+(10∗210) + (10 * 200) / (50 + 10)-$500
SellSOL1050$22050 * avg cost / 50 = 50 * ((50 * 210)+(10∗210) + (10 * 200) / (50 + 10)) / 50$583.50
SellSOL248$22048 * avg cost / 48 = 48 * ((50 * 210)+(10∗210) + (10 * 200) / (50 + 10)) / 48$560.16
User checking app48$23048 * $208.33 / 48$1040.16
BuySOL755$18048 * $208.33 + 7 * 180 / 48 + 7-$1359.84
User checking app55$18548 * $208.33 + 7 * 180 / 48 + 7 = 204.72-$1084.6

​
Historical PnL

How is Historical PnL calculated? PnL is calculated using the following formula:
Historical PnL between time X and time Y = Realized PnL from sales between X and Y + (Total unrealized PnL at time Y calculated from genesis - Total unrealized PnL at time X calculated from genesis)
Important notes and error handling
  • Invalid data (such as unsupported chains or invalid address/token address) returns status code 400.
  • If end_timestamp is earlier than start_timestamp, an error will be returned
  • If end_timestamp is in the future, it will be adjusted to the current time
  • If a wallet has no holdings or does not exist, the endpoint will interpolate the aggregated pnl to be 0