Skip to main content
POST
/
api
/
v1
/
developer
/
wallet
/
pnl-by-token
/
history
Get Pnl By Token With Historical Breakdown
curl --request POST \
  --url https://api.allium.so/api/v1/developer/wallet/pnl-by-token/history \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "addresses": [
    {
      "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
      "chain": "solana",
      "token_address": "So11111111111111111111111111111111111111112"
    }
  ],
  "end_timestamp": "2025-04-10T00:00:00Z",
  "granularity": "1h",
  "start_timestamp": "2025-04-01T00:00:00Z"
}
'
{
  "data": {
    "chain": "<string>",
    "address": "<string>",
    "token_address": "<string>",
    "pnl": [
      {
        "timestamp": "2023-11-07T05:31:56Z",
        "unrealized_pnl": {
          "amount": "<string>",
          "currency": "USD"
        },
        "realized_pnl": {
          "amount": "<string>",
          "currency": "USD"
        }
      }
    ]
  },
  "items": [
    {
      "chain": "<string>",
      "address": "<string>",
      "token_address": "<string>",
      "pnl": [
        {
          "timestamp": "2023-11-07T05:31:56Z",
          "unrealized_pnl": {
            "amount": "<string>",
            "currency": "USD"
          },
          "realized_pnl": {
            "amount": "<string>",
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "error": "<string>",
  "cursor": "<string>"
}
This endpoint provides unrealized and realized PnL for specific wallet and token address combinations at specified time periods and granularities.
This is a beta endpoint currently under active development. We’re working to stabilize the API and will minimize breaking changes wherever possible, but they may still occur as we refine the interface.For production support or migration assistance, reach out at hello@allium.so.

​
Time Range Parameters

  • start_timestamp - Beginning of the time range (inclusive)
  • end_timestamp - End of the time range (exclusive)
  • Both timestamps are assumed to be in UTC if no timezone is specified
  • All returned data is in UTC

​
Granularity Options

  • 1d - Daily intervals
  • 1h - Hourly intervals

​
Supported Chains

Authorizations

​
X-API-KEY
string
header
required

Body

application/json

Payload for historical PNL by token.

​
start_timestamp
string<date-time>
required

Start of time range (UTC ISO 8601)

​
end_timestamp
string<date-time>
required

End of time range (UTC ISO 8601)

​
granularity
enum<string>
required

Time interval granularity (1d, 1h, 5m, 1m, 15s)

Available options:
1h,
1d,
1m,
5m,
15s
​
addresses
PayloadAddressHoldingsByToken · object[]
required

List of wallet chain+address+token triples

Required array length: 1 - 20 elements

Response

Successful Response

​
data
HistoricalPnlByToken · object

Single item response data of type T

​
items
(HistoricalPnlByToken · object | PnlError · object)[] | null

Response items of type T

​
error
string | null

Error message

​
cursor
string | null

Pagination cursor for next page