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.

​
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
  • 5m - 5-minute intervals
  • 1m - 1-minute intervals
  • 15s - 15-second intervals

​
Granularity Constraints

The allowed granularity depends on the requested time range:
Time RangeFinest Granularity Allowed
0 - 24 hours15s
1 - 7 days5m
1 week - 1 year1h
Over 1 year1d

​
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