POST
/
api
/
v1
/
developer
/
wallet
/
pnl-beta
curl --request POST \
  --url https://api.allium.so/api/v1/developer/wallet/pnl-beta \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '[
  {
    "chain": "<string>",
    "address": "<string>",
    "token_address": "<string>"
  }
]'
{
  "data": {
    "result": {
      "address": "<string>",
      "mint": "<string>",
      "token_symbol": "<string>",
      "pnl_usd": 123,
      "current_balance": 123,
      "current_balance_usd": 123,
      "average_cost_usd": 123
    },
    "address": "<string>",
    "token_address": "<string>",
    "chain": "<string>",
    "error": {
      "message": "<string>"
    }
  },
  "items": [
    {
      "result": {
        "address": "<string>",
        "mint": "<string>",
        "token_symbol": "<string>",
        "pnl_usd": 123,
        "current_balance": 123,
        "current_balance_usd": 123,
        "average_cost_usd": 123
      },
      "address": "<string>",
      "token_address": "<string>",
      "chain": "<string>",
      "error": {
        "message": "<string>"
      }
    }
  ],
  "error": "<string>",
  "cursor": "<string>"
}

This endpoint provides the unrealized PnL, average cost, current balance, and current usd balance for given wallet and token addresses. This endpoint is in beta and subject to change.

Important notes and error handling

  • This endpoint is currently only supported for solana. The underlying tables are currently being optimized, so data is only available for 2025/01/01 onwards and the endpoint is much slower than usual.
  • Value errors are returned for invalid address/token address and unsupported chains.
  • If no latest balance is found for a given address/token pair, the endpoint will return that no PnL data has been found.

Supported Chains and Holdings

  • Solana

How is PnL calculated?

PnL is calculated using the following formula:

PnL=Current Balance(Token)×(Current USD Price(Token)−Average Cost(Token))\text{PnL} = \text{Current Balance(Token)} \times \left( \text{Current USD Price(Token)} - \text{Average Cost(Token)} \right)

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

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.

We’ve also made the following assumptions:

  • To prevent false positive such as multiple transfers in intermediate hops of a swap, we only take transfers of tokens with a net change on the tx-level
  • The average cost of a token is the price of the token when bought, not the price paid with the other token in a swap. This means slippage/arbitrage is not accounted for
  • P2P transfers are not included in the average cost calculation i.e. the token is received for free
  • Average cost is “reset” when the token balance decreases. i.e. if you sell some tokens, and your new balance is B, the new average cost will be calculated using B(avgcost(B)B)B \left( \frac{avg cost(B)}{B} \right )
  • The pnl calculation shown above is for unrealized gains only. To calculated realized gains, you can do so using the average cost field.

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

Authorizations

​
X-API-KEY
string
header
required

Body

application/json · object[]

The body is of type object[].

Response

200
application/json
Successful Response

The response is of type object.