Overview

Allium’s Holdings APIs provide comprehensive realtime and historical USD holdings for wallets, with built-in PnL calculations. Track portfolio performance over time with data aggregated from balance history and price feeds. Supported Networks: Bitcoin and Solana (more chains coming soon)

Key Features

Realtime & Historical

Latest balances and prices update in realtime, with historical holdings available for tracking portfolios over time

Multi-Chain Aggregation

Request aggregated holdings across multiple chains in a single API call

PnL Calculation

Automatic profit and loss calculations using average cost basis methodology

Holdings Aggregation

Holdings data is aggregated at multiple time granularities with corresponding retention periods:

Granularity	Retention
15s	5 days
5m	30 days
1h	All
1d	All

USD holdings for each wallet are aggregated across all tokens held and returned at these set time intervals.

PnL Methodology

PnL calculations are based on the average cost basis method, which takes a weighted average of all token purchases and reweights the average cost during sale events.

Latest PnL
Historical PnL
Calculation Details

Latest PnL represents the current unrealized profit or loss for a wallet’s holdings.Formula:

Latest PnL = Current Balance × (Current Price - Average Cost)

Where:

Current Balance = Latest token balance for the address
Current Price = Latest token price in USD
Average Cost = Weighted average cost of the token

Example Scenario

Action	Token	Amount	Balance	Price	Average Cost Calculation	PnL
Buy	SOL	50	50	$210	(50 × $210) / 50	$0
Buy	SOL	10	60	$200	(50 × $210 + 10 ×$ 200) / 60	-$500
Sell	SOL	10	50	$220	Previous avg cost maintained	$583.50
Sell	SOL	2	48	$220	Previous avg cost maintained	$560.16
Price check	SOL	—	48	$230	48 × $208.33 / 48	$1,040.16
Buy	SOL	7	55	$180	(48 × $208.33 + 7 ×$ 180) / 55	-$1,359.84
Price check	SOL	—	55	$185	$204.72	-$1,084.60

Historical PnL calculates profit or loss between two time periods, combining realized PnL from sales and changes in unrealized PnL.Formula:

Historical PnL (X to Y) = Realized PnL (X to Y) +
                          (Unrealized PnL at Y - Unrealized PnL at X)

Where:

Realized PnL = Profit/loss from token sales between times X and Y
Unrealized PnL = Profit/loss from tokens still held, calculated from genesis

Important Notes

If end_timestamp is earlier than start_timestamp, an error is returned
If end_timestamp is in the future, it’s adjusted to the current time
If a wallet has no holdings or doesn’t exist, PnL is interpolated to 0

PnL Components:

Realized PnL = Tokens sold × (Sale price - Average cost)
Unrealized PnL = Tokens held × (Current price - Average cost)

Average Cost Calculation:Average cost is recalculated with each purchase:

New Avg Cost = (Previous Balance × Previous Avg Cost + New Amount × Purchase Price) /
               (Previous Balance + New Amount)

During sales, the average cost remains constant for remaining tokens.

Supported Chains

Currently supported: Bitcoin and Solana

Support for additional chains and liquidity pool-based pricing is in development. Interested in testing the Holdings API? Contact us to discuss your needs.

Realtime API

Stream Transformation API

Beam API

Explorer API

Account API

Deep Dives

Key Features

Realtime & Historical

Multi-Chain Aggregation

PnL Calculation

Holdings Aggregation

PnL Methodology

Example Scenario

Important Notes

Supported Chains

​Key Features

Realtime & Historical

Multi-Chain Aggregation

PnL Calculation

​Holdings Aggregation

​PnL Methodology

​Example Scenario

​Important Notes

​Supported Chains

Key Features

Holdings Aggregation

PnL Methodology

Example Scenario

Important Notes

Supported Chains