Skip to main content
POST
/
api
/
v1
/
developer
/
wallet
/
pnl
/
history
Get Pnl History
curl --request POST \
  --url https://api.allium.so/api/v1/developer/wallet/pnl/history \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "addresses": [
    {
      "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
      "chain": "solana"
    }
  ],
  "end_timestamp": "2025-04-10T00:00:00Z",
  "granularity": "1h",
  "start_timestamp": "2025-04-01T00:00:00Z"
}
'
{
  "data": {
    "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
    "chain": "solana",
    "pnl": [
      {
        "realized_pnl": {
          "amount": "0.002335373911312482",
          "currency": "USD"
        },
        "timestamp": "2026-03-19T22:00:00Z",
        "unrealized_pnl": {
          "amount": "0.145848378518889629",
          "currency": "USD"
        }
      },
      {
        "realized_pnl": {
          "amount": "0.002335373911312482",
          "currency": "USD"
        },
        "timestamp": "2026-03-19T23:00:00Z",
        "unrealized_pnl": {
          "amount": "0.137894957302491137",
          "currency": "USD"
        }
      }
    ]
  },
  "items": [
    {
      "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
      "chain": "solana",
      "pnl": [
        {
          "realized_pnl": {
            "amount": "0.002335373911312482",
            "currency": "USD"
          },
          "timestamp": "2026-03-19T22:00:00Z",
          "unrealized_pnl": {
            "amount": "0.145848378518889629",
            "currency": "USD"
          }
        },
        {
          "realized_pnl": {
            "amount": "0.002335373911312482",
            "currency": "USD"
          },
          "timestamp": "2026-03-19T23:00:00Z",
          "unrealized_pnl": {
            "amount": "0.137894957302491137",
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "error": "<string>",
  "cursor": "<string>"
}
This endpoint provides unrealized and realized PnL for wallet addresses 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

Supported granularities: 15s, 1m, 5m, 1h, 1d Supported time periods & granularity combinations:
  • Less than 1 day: All granularities
  • Between 1 to 7 days: 5m, 1h, 1d
  • Between 7 to 365 days: 1h, 1d
  • More than 365 days: 1d

​
Supported Chains

Authorizations

​
X-API-KEY
string
header
required

Query Parameters

​
min_liquidity
number

Minimum liquidity of which tokens must have to be included in the response.

Body

application/json
​
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
PayloadAddress · object[]
required

List of wallet chain+address pairs

Required array length: 1 - 20 elements

Response

Successful Response

​
data
HistoricalPnl · object

Single item response data of type T

Example:
{
  "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
  "chain": "solana",
  "pnl": [
    {
      "realized_pnl": {
        "amount": "0.002335373911312482",
        "currency": "USD"
      },
      "timestamp": "2026-03-19T22:00:00Z",
      "unrealized_pnl": {
        "amount": "0.145848378518889629",
        "currency": "USD"
      }
    },
    {
      "realized_pnl": {
        "amount": "0.002335373911312482",
        "currency": "USD"
      },
      "timestamp": "2026-03-19T23:00:00Z",
      "unrealized_pnl": {
        "amount": "0.137894957302491137",
        "currency": "USD"
      }
    }
  ]
}
​
items
(HistoricalPnl · object | PnlError · object)[] | null

Response items of type T

Example:
{
  "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
  "chain": "solana",
  "pnl": [
    {
      "realized_pnl": {
        "amount": "0.002335373911312482",
        "currency": "USD"
      },
      "timestamp": "2026-03-19T22:00:00Z",
      "unrealized_pnl": {
        "amount": "0.145848378518889629",
        "currency": "USD"
      }
    },
    {
      "realized_pnl": {
        "amount": "0.002335373911312482",
        "currency": "USD"
      },
      "timestamp": "2026-03-19T23:00:00Z",
      "unrealized_pnl": {
        "amount": "0.137894957302491137",
        "currency": "USD"
      }
    }
  ]
}
​
error
string | null

Error message

​
cursor
string | null

Pagination cursor for next page