> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Realtime and historical portfolio holdings with PnL calculations.

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

<CardGroup cols={3}>
  <Card title="Realtime & Historical" icon="clock">
    Latest balances and prices update in realtime, with historical holdings
    available for tracking portfolios over time
  </Card>

  <Card title="Multi-Chain Aggregation" icon="layer-group">
    Request aggregated holdings across multiple chains in a single API call
  </Card>

  <Card title="PnL Calculation" icon="chart-line">
    Automatic profit and loss calculations using average cost basis methodology
  </Card>
</CardGroup>

## 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](https://www.schwab.com/learn/story/save-on-taxes-know-your-cost-basis), which takes a weighted average of all token purchases and reweights the average cost during sale events.

<Tabs>
  <Tab title="Latest PnL">
    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 |
  </Tab>

  <Tab title="Historical PnL">
    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
  </Tab>

  <Tab title="Calculation Details">
    **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.
  </Tab>
</Tabs>

## Supported Chains

Currently supported: **Bitcoin** and **Solana**

<Info>
  Support for additional chains and liquidity pool-based pricing is in
  development. Interested in testing the Holdings API? [Contact
  us](https://www.allium.so/contact) to discuss your needs.
</Info>