ZEzerion
wallets

Get wallet PnL

Changed on

Returns a wallet's profit and loss (PnL): unrealized PnL, realized PnL and net invested amounts, with filters for asset categories such as NFTs. Calculations use FIFO (first in, first out).

The first request for a wallet can return 503. Retry it later: only the 503 carries a Retry-After header.

Addresses Zerion doesn't track return 400. That covers contract addresses that aren't smart-contract wallets. Safe and ERC-4337 accounts work as normal.

Wallets with more than 1 million actions can't be served and return 422 once the limit is detected.

get/v1/wallets/{address}/pnl

Request

  • Base URL
    https://api.zerion.io
  • URL
    https://api.zerion.io/v1/wallets/{address}/pnl
  • Auth
    HTTP basic

Path parameters

string required

Ethereum-compatible address (EVM).

OR
string required

Solana address

Example:0x42b9df65b219b3dd36ff330a4dd8f327a6ada990

The web3 wallet address. Must be a valid EVM or Solana address. The PnL endpoint additionally requires an address Zerion tracks, and returns 400 otherwise; see that endpoint's description for what that excludes.

Query parameters

currency'eth' | 'btc' | 'usd' | 'eur' | 'krw' | 'rub' | 'gbp' | 'aud' | 'cad' | 'inr' | 'jpy' | 'nzd' | 'try' | 'zar' | 'cny' | 'chf'

Denominated currency value of returned prices

filter[chain_ids]string[]

Calculate PnL only for specified chains (comma-separated list). Only chains reporting both supports_transactions and supports_positions in the flags of GET /v1/chains/ are accepted here. Naming a chain that fails that gate returns 400 rather than an empty result, with detail reading chain <id> does not support PnL (for example chain bob does not support PnL). When the filter is omitted, chains that fail the gate are left out of data silently, with no error and no meta signal.

[
  "ethereum",
  "polygon"
]
filter[fungible_ids]string[]

Calculate PnL only for these fungible IDs (comma-separated list, up to 100).

With filter[fungible_ids] or filter[fungible_implementations], assets without a price are left out of the calculation instead of causing an error. The excluded assets are listed in the response metadata.

filter[fungible_implementations]string[]

Calculate PnL only for these token implementations (comma-separated list of chain_id:address pairs, up to 100).

For example: base:0xae16c445d8a4082cecb49a9465e4dd5499df947d,ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

With filter[fungible_ids] or filter[fungible_implementations], assets without a price are left out of the calculation instead of causing an error. The excluded assets are listed in the response metadata.

sincestring
Example:1688842525735

Count only sales since this time, as a Unix timestamp in milliseconds.

Note: PnL is pre-computed at standard marks (now, 1 day ago, 1 week ago, 1 month ago, 1 year ago, beginning of the year). Other values are supported only if fewer than 3,000 transactions sit between your timestamp and the nearest mark. Otherwise the request errors out.

tillstring
Example:1688842525735

Count only sales until this time, as a Unix timestamp in milliseconds.

Note: PnL is pre-computed at standard marks (now, 1 day ago, 1 week ago, 1 month ago, 1 year ago, beginning of the year). Other values are supported only if fewer than 3,000 transactions sit between your timestamp and the nearest mark. Otherwise the request errors out.

Response

Response for requested wallet's pnl

Example response

{
  "links": {
    "self": "https://api.zerion.io/v1/wallets/0x42b9df65b219b3dd36ff330a4dd8f327a6ada990/pnl"
  },
  "data": {
    "id": "0x42b9df65b219b3dd36ff330a4dd8f327a6ada990",
    "attributes": {
      "total_gain": -637.8173517,
      "realized_gain": -655.3618983,
      "unrealized_gain": 17.5445466,
      "relative_total_gain_percentage": -11.38,
      "relative_realized_gain_percentage": -15.15,
      "relative_unrealized_gain_percentage": -0.19,
      "total_fee": 281.9088917,
      "total_invested": 701.2,
      "realized_cost_basis": 655.36,
      "net_invested": 45.84218703,
      "received_external": 133971.2931,
      "sent_external": 133270.089,
      "sent_for_nfts": 133971.2931,
      "received_for_nfts": 133971.2931,
      "breakdown": {
        "by_id": {
          "eth": {
            "average_buy_price": 1258.8,
            "average_sell_price": 1224.96,
            "total_gain": -6900.85,
            "realized_gain": -6871.21,
            "unrealized_gain": -29.64,
            "relative_total_gain_percentage": -11.38,
            "relative_realized_gain_percentage": -15.15,
            "relative_unrealized_gain_percentage": -0.19,
            "total_fee": 4679.93,
            "total_invested": 60643.33,
            "realized_cost_basis": 45363.2,
            "net_invested": 15280.13,
            "received_external": 35402.73,
            "sent_external": 22213.21,
            "sent_for_nfts": 1713.23,
            "received_for_nfts": 1635.05
          }
        },
        "by_implementation": {
          "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
            "average_buy_price": 1,
            "average_sell_price": 1,
            "total_gain": 0,
            "realized_gain": 0,
            "unrealized_gain": 0,
            "relative_total_gain_percentage": 0,
            "relative_realized_gain_percentage": 0,
            "relative_unrealized_gain_percentage": 0,
            "total_fee": 12.5,
            "total_invested": 5000,
            "realized_cost_basis": 3000,
            "net_invested": 2000,
            "received_external": 1000,
            "sent_external": 500,
            "sent_for_nfts": 0,
            "received_for_nfts": 0
          }
        }
      }
    }
  },
  "meta": {
    "excluded_fungible_ids": [
      "4a702a34-5cfd-41af-96ad-bd1c45c3672e"
    ],
    "excluded_fungible_implementations": [
      "ethereum:0x6b175474e89094c44da98b954eedeac495271d0f",
      "ethereum:"
    ]
  }
}

Changes