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.

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