Fetch historical PnL by Wallet

Get the Historical PnL for a given wallet address.

POST /api/v1/developer/wallet/pnl/history

Get Pnl History

cURL

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"
}
'

200

{
  "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 Range	Finest Granularity Allowed
0 - 24 hours	15s
1 - 7 days	5m
1 week - 1 year	1h
Over 1 year	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

Show child attributes

Response

200

application/json

Successful Response

data · HistoricalPnl · object

Single item response data of type T

HistoricalPnl

PnlError

Show child attributes

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

HistoricalPnl

PnlError

Show child attributes

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