Build a wallet PnL tracker

What you’ll build:

Fetch a wallet’s total PnL (realized, unrealized, fees, external flows)
Batch-query PnL for up to 100 tokens in one call, with per-token breakdowns
Compare the same token’s performance across different chains
Use time-range filters for period-specific PnL
Handle edge cases (503 bootstrap, airdrops)

=== PORTFOLIO SUMMARY ===
Realized Gain:     $1,245.67
Unrealized Gain:   $3,891.02
Net Invested:      $12,500.00
Fees:              $342.18
Received External: $500.00
Sent External:     $150.00

=== TOKEN BREAKDOWN ===
ETH
  Buy avg: $2450.85  ->  Sell avg: $3527.83
  Realized: $1076.98 (43.9%)
  Unrealized: $3214.50
  Invested: $7353.00  |  Fees: $245.12
UNI
  Buy avg: $6.42  ->  Sell avg: $8.15
  Realized: $168.69 (26.3%)
  Unrealized: $676.52
  Invested: $642.00  |  Fees: $84.56

Time: ~10 minutes

Prerequisites

A Zerion API key (get one here)
Node.js 18+ (for native fetch) or any HTTP client

How PnL is calculated

Zerion uses FIFO (First In, First Out) - earliest purchases are matched against earliest sales. This is the most common standard for tax reporting.

Response fields

Field	Description
`realized_gain`	Profit/loss from sold tokens
`unrealized_gain`	Paper gains on tokens you still hold
`total_fee`	Cumulative transaction fees paid
`net_invested`	Total buys minus sale proceeds
`received_external`	Value of tokens received from external sources (transfers in)
`sent_external`	Value of tokens sent externally (transfers out)
`sent_for_nfts`	Value spent purchasing NFTs
`received_for_nfts`	Value received from selling NFTs

When you add token filters (fungible_ids or fungible_implementations), the response also includes a breakdown object with per-token stats like average_buy_price, average_sell_price, and gain percentages.

The resource type in the response is wallet_pnl (not pnl).

Steps

Edge cases & operational notes

503 + Retry-After (cold wallets)

For wallets that haven’t been queried before, or wallets with long transaction histories, the first request may return a 503 with a Retry-After header while PnL is being bootstrapped. This is non-billable. Retry after the indicated delay (usually a few seconds). Once bootstrapped, subsequent requests are fast (under 200 ms for basic PnL queries without a breakdown; building a breakdown adds 150–300 ms depending on the number of tokens). Snapshots are retained for ~1 month; after that, a re-bootstrap may be triggered.A 503 always carries a Retry-After header. If you get an error without one, retrying is not the answer. See the next two entries.

422 (wallets too large to calculate)

Wallets with more than 1 million actions are too large for PnL to be calculated, and return 422 with no Retry-After header:

{
  "errors": [
    {
      "title": "This request is not supported",
      "detail": "This request cannot be processed, and retrying will not help. Please contact support if you need it enabled."
    }
  ]
}

Don’t fold this into your 503 retry loop. The helper above only recurses on 503, so a 422 surfaces to the caller instead. Don’t cache it against the address either: the same wallet can return 503 again later if its cached state is rebuilt.

400 (addresses Zerion doesn't track)

PnL is only calculated for addresses that behave like user wallets. Contract addresses that aren’t recognized smart-contract wallets, burn addresses, and high-volume addresses such as exchange hot wallets are rejected before any work is done:

{
  "errors": [
    {
      "title": "Malformed parameter was sent",
      "detail": "address 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 is not trackable"
    }
  ]
}

Smart-contract wallets are fine: Safe, Coinbase Smart Wallet and ERC-4337 accounts all work. See Error handling for the full rule.

Excluded tokens

Tokens without reliable price data are omitted from breakdown calculations rather than erroring. They simply won’t appear in the breakdown object.

Airdrop cost basis

Tokens received as “pure mints” (from the zero address or a token contract with no payment beyond gas) are assigned zero cost basis. However, many airdrops are actually distributed from a non-zero address, which causes them to be misclassified as purchases at the market price at the time of receipt. Keep this in mind when reviewing cost basis data for airdropped tokens.

Base asset format

Native chain tokens use chain: with an empty address after the colon: ethereum: for ETH, base: for Base ETH, polygon: for MATIC, solana: for SOL.

Supported currencies

16 options via the currency param: usd, eur, gbp, btc, eth, krw, jpy, aud, cad, inr, nzd, try, zar, cny, chf, rub.

Batch limits

Max 100 tokens per request for either fungible_ids or fungible_implementations. For larger portfolios, paginate with multiple calls.

Next steps

Combine with wallet positions to fetch current holdings, then batch those token IDs into PnL for a complete dashboard
Add balance charts to visualize portfolio value over time alongside PnL
Set up webhooks to trigger PnL recalculations when new transactions land

​Prerequisites

​How PnL is calculated

​Response fields

​Steps

​Edge cases & operational notes

​Next steps

Prerequisites

How PnL is calculated

Response fields

Steps

Edge cases & operational notes

Next steps