Build a wallet PnL tracker

What you’ll build

A wallet’s total PnL: realized, unrealized, fees and external flows
Per-token breakdowns for up to 100 tokens in one call
The same token’s performance compared across chains
PnL for a specific time range
Handling for edge cases like the 503 bootstrap and airdrops

Time

~10 minutes

You need

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

Endpoints

GET/v1/wallets/address/pnl

How PnL is calculated

Zerion API uses FIFO (first in, first out): it matches the earliest purchases against the 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

Portfolio-level PnL

Fetch a wallet’s overall PnL across all tokens and chains.GET /v1/wallets/{address}/pnl?currency=usd

const API_KEY = process.env.ZERION_API_KEY;
const BASE_URL = "https://api.zerion.io/v1";
const headers = {
  accept: "application/json",
  authorization: `Basic ${btoa(API_KEY + ":")}`,
};

async function getPortfolioPnL(address, currency = "usd") {
  const response = await fetch(
    `${BASE_URL}/wallets/${address}/pnl?currency=${currency}`,
    { headers }
  );
  const { data } = await response.json();
  return data.attributes;
}

const pnl = await getPortfolioPnL("0x42b9df65b219b3dd36ff330a4dd8f327a6ada990");
console.log(`Realized Gain:     $${pnl.realized_gain.toFixed(2)}`);
console.log(`Unrealized Gain:   $${pnl.unrealized_gain.toFixed(2)}`);
console.log(`Net Invested:      $${pnl.net_invested.toFixed(2)}`);
console.log(`Total Fees:        $${pnl.total_fee.toFixed(2)}`);
console.log(`Received External: $${pnl.received_external.toFixed(2)}`);
console.log(`Sent External:     $${pnl.sent_external.toFixed(2)}`);

Batch PnL for specific tokens

Pass up to 100 tokens in one request to get a per-token breakdown. There are two filtering modes:

Filter	Use case	Format	Breakdown key
`fungible_ids`	Cross-chain aggregate - PnL for a token across all chains	Zerion token ID (`eth`, `usdc`)	`breakdown.by_id`
`fungible_implementations`	Chain-specific - PnL for a token on a specific chain	`chain:contract_address` pair	`breakdown.by_implementation`

Option A: fungible_ids (cross-chain)Aggregates a token’s PnL across all chains. Use it for portfolio-level token views where the chain doesn’t matter.

const params = new URLSearchParams({
  currency: "usd",
  "filter[fungible_ids]": "eth,uni,wbtc",
});

const response = await fetch(
  `${BASE_URL}/wallets/${address}/pnl?${params}`,
  { headers }
);
const { data } = await response.json();
const breakdown = data.attributes.breakdown?.by_id;

for (const [tokenId, stats] of Object.entries(breakdown)) {
  console.log(`${tokenId}: $${stats.total_gain?.toFixed(2)} gain (${stats.relative_total_gain_percentage?.toFixed(1)}%)`);
}

Example response (breakdown.by_id):

{
  "breakdown": {
    "by_id": {
      "eth": {
        "average_buy_price": 3450.85,
        "average_sell_price": 3527.83,
        "realized_gain": -5.48,
        "unrealized_gain": -1.97,
        "total_fee": 1.88,
        "net_invested": 38.24,
        "received_external": 52.18,
        "sent_external": 0.13,
        "sent_for_nfts": 5.00,
        "received_for_nfts": 0
      }
    }
  }
}

When you filter by token, the top-level fields (realized_gain, net_invested, etc.) reflect only the filtered tokens, not your entire wallet.

Option B: fungible_implementations (chain-specific)Tracks PnL per chain deployment, using chain:contract_address pairs. Use it to compare the same token across L1s and L2s, or when you need chain-level precision.

const params = new URLSearchParams({
  currency: "usd",
  "filter[fungible_implementations]": [
    "ethereum:",                                             // ETH on Ethereum (native asset)
    "base:",                                                 // ETH on Base (native asset)
    "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",  // USDC on Ethereum
    "base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",      // USDC on Base
  ].join(","),
});

const response = await fetch(
  `${BASE_URL}/wallets/${address}/pnl?${params}`,
  { headers }
);
const { data } = await response.json();
const breakdown = data.attributes.breakdown?.by_implementation;

for (const [impl, stats] of Object.entries(breakdown)) {
  const [chain, addr] = impl.split(":");
  const label = addr ? `${chain}:${addr.slice(0, 10)}…` : `${chain} (native)`;
  console.log(`${label}: gain $${stats.realized_gain?.toFixed(2)}, unrealized $${stats.unrealized_gain?.toFixed(2)}`);
}

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.

Per-token breakdown fields:Each entry in the breakdown object (whether by_id or by_implementation) contains:

Field	Description
`average_buy_price`	Weighted average purchase price
`average_sell_price`	Weighted average sale price
`realized_gain`	Profit/loss from closed positions
`unrealized_gain`	Paper gain on current holdings
`relative_total_gain_percentage`	Total gain as % of invested
`relative_realized_gain_percentage`	Realized gain as % of cost basis
`relative_unrealized_gain_percentage`	Unrealized gain as % of current holdings cost
`total_invested`	Sum of buys for this token
`net_invested`	Buys minus sells
`total_fee`	Fees paid on this token’s transactions
`received_external`	Value received from external transfers
`sent_external`	Value sent externally
`sent_for_nfts`	Value spent on NFTs (for this token)
`received_for_nfts`	Value received from NFT sales

Time-range PnL

Scope PnL to a time window with the since and till parameters, as Unix timestamps in milliseconds. Omit till to measure up to now.PnL is pre-computed at six marks: now, 1 day ago, 1 week ago, 1 month ago, 1 year ago and the beginning of the year. Ranges on these marks return in under 200 ms at p99. This example uses the beginning of the year:

// Year-to-date PnL: the beginning of the year is a pre-computed mark
const since = Date.UTC(new Date().getUTCFullYear(), 0, 1); // 1767225600000 in 2026

const params = new URLSearchParams({
  currency: "usd",
  since: since.toString(),
});

const response = await fetch(
  `${BASE_URL}/wallets/${address}/pnl?${params}`,
  { headers }
);

# Year-to-date PnL (since January 1, 2026)
curl -u YOUR_API_KEY: \
  -H "accept: application/json" \
  "https://api.zerion.io/v1/wallets/{address}/pnl?currency=usd&since=1767225600000"

A since or till that isn’t on a mark works only if fewer than 3,000 transactions sit between it and the nearest mark. Otherwise the request returns 503, and retrying doesn’t help. For example, calendar year 2025 (since=1735689600000&till=1767225600000) returns 503 for vitalik.eth. On busy wallets, use the marks.

You can combine since/till with token filters.

Unrealized gains are always calculated using current market prices, regardless of the till parameter. If you set till to a past date, realized gains reflect that period, but unrealized gains use today’s prices.

Filter by chain

Scope PnL to specific chains with filter[chain_ids].GET /v1/wallets/{address}/pnl?currency=usd&filter[chain_ids]=ethereum,base

curl -g -u "YOUR_API_KEY:" \
  "https://api.zerion.io/v1/wallets/0x42b9df65b219b3dd36ff330a4dd8f327a6ada990/pnl?currency=usd&filter[chain_ids]=ethereum,base"

Use it when your app is chain-specific (for example, a Base-only wallet) or to compare PnL across L2s.

Zerion API ignores filter[chain_ids] when you use fungible_implementations. The chain is already part of each implementation string.

Full working example

Save as pnl-dashboard.mjs and run node pnl-dashboard.mjs. It prints the output shown at the top of this page and retries 503 responses while a cold wallet bootstraps.

pnl-dashboard.mjs

const API_KEY = process.env.ZERION_API_KEY;
const BASE_URL = "https://api.zerion.io/v1";
const headers = {
  accept: "application/json",
  authorization: `Basic ${btoa(API_KEY + ":")}`,
};

async function fetchPnL(address, params = {}, retries = 3) {
  const query = new URLSearchParams({ currency: "usd", ...params });
  const res = await fetch(`${BASE_URL}/wallets/${address}/pnl?${query}`, { headers });

  // Handle bootstrap: new/cold wallets may return 503 with Retry-After
  if (res.status === 503) {
    if (retries <= 0) throw new Error("Wallet PnL bootstrap timed out after retries");
    const retryAfter = res.headers.get("Retry-After") || "5";
    console.log(`Wallet bootstrapping... retrying in ${retryAfter}s (${retries} retries left)`);
    await new Promise((r) => setTimeout(r, parseInt(retryAfter) * 1000));
    return fetchPnL(address, params, retries - 1);
  }

  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

async function buildDashboard(address, tokenIds) {
  // 1. Portfolio-level PnL
  const overall = await fetchPnL(address);
  const pnl = overall.data.attributes;

  console.log("=== PORTFOLIO SUMMARY ===");
  console.log(`Realized Gain:     $${pnl.realized_gain.toFixed(2)}`);
  console.log(`Unrealized Gain:   $${pnl.unrealized_gain.toFixed(2)}`);
  console.log(`Net Invested:      $${pnl.net_invested.toFixed(2)}`);
  console.log(`Fees:              $${pnl.total_fee.toFixed(2)}`);
  console.log(`Received External: $${pnl.received_external.toFixed(2)}`);
  console.log(`Sent External:     $${pnl.sent_external.toFixed(2)}`);

  // 2. Per-token breakdown
  if (tokenIds?.length) {
    const batch = await fetchPnL(address, {
      "filter[fungible_ids]": tokenIds.join(","),
    });
    const breakdown = batch.data.attributes.breakdown?.by_id || {};

    console.log("\n=== TOKEN BREAKDOWN ===");
    for (const [id, s] of Object.entries(breakdown)) {
      console.log(`${id.toUpperCase()}`);
      console.log(`  Buy avg: $${s.average_buy_price?.toFixed(2)}  ->  Sell avg: $${s.average_sell_price?.toFixed(2)}`);
      console.log(`  Realized: $${s.realized_gain?.toFixed(2)} (${s.relative_realized_gain_percentage?.toFixed(1)}%)`);
      console.log(`  Unrealized: $${s.unrealized_gain?.toFixed(2)}`);
      console.log(`  Invested: $${s.total_invested?.toFixed(2)}  |  Fees: $${s.total_fee?.toFixed(2)}`);
    }
  }
}

buildDashboard("0x42b9df65b219b3dd36ff330a4dd8f327a6ada990", [
  "eth", "uni", "wbtc",
]);

Edge cases and 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)

Zerion only calculates PnL for addresses that behave like user wallets. Zerion rejects contract addresses that aren’t recognized smart-contract wallets, burn addresses, and high-volume addresses such as exchange hot wallets before doing any work:

{
  "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 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 show portfolio value over time alongside PnL.
Set up webhooks to trigger PnL recalculations when new transactions land.

Build a multi-chain portfolio tracker Total value, holdings and charts across chains. Portfolio Set up wallet activity alerts Webhooks for every send, receive and swap. Webhooks

​How PnL is calculated

​Response fields

​Steps

​Edge cases and operational notes

​Next steps

How PnL is calculated

Response fields

Steps

Edge cases and operational notes

Next steps