Calculate per-token PnL (realized & unrealized) for any blockchain address via Nansen's on-chain analytics.
What it does
The Nansen Profiler Address PnL endpoint computes profit-and-loss metrics for a specific wallet address and token pair. Given an address (or entity name), chain, and optional date range, it returns realized PnL from completed sales, unrealized PnL from current holdings, average buy/sell prices, cost basis, ROI percentages, and trade counts. It supports 17+ chains including Ethereum, Solana, Base, BNB, Arbitrum, Polygon, and more.
This endpoint is part of the broader Nansen API v1, which offers smart money tracking, token screening, wallet profiling, prediction market analytics, and an AI research agent. The PnL endpoint specifically answers questions like: what are the realized profits from completed token sales, what unrealized gains exist on current holdings, what was the average purchase and sale price, and what is the total return on investment for a given token.
Payment is handled via the x402 protocol at $0.01 per request (fixed pricing). The endpoint accepts POST requests with a JSON body containing address, chain, optional date range, and optional filters (e.g., show_realized, token_address). Responses include paginated PnL records with fields like pnl_usd_realised, pnl_usd_unrealised, roi_percent_realised, bought_usd, sold_usd, holding_usd, and more. Rate limits and credit usage are returned in response headers.
Capabilities
Use cases
- —Calculate realized and unrealized PnL for a wallet's token positions across multiple chains
- —Evaluate a trader's ROI on specific tokens before copying their strategy
- —Build portfolio tracking dashboards with per-token cost basis and performance metrics
- —Audit wallet trading performance for due diligence on fund managers or smart money addresses
- —Backtest trading signals by analyzing historical PnL of identified smart money wallets
Fit
Best for
- —Agents or apps that need per-token PnL breakdowns for any on-chain address
- —Portfolio trackers requiring cost basis and ROI calculations across 17+ chains
- —Research workflows analyzing wallet trading performance with realized vs unrealized splits
Not for
- —Real-time streaming price feeds or sub-second trade execution signals
- —Off-chain or CEX-only portfolio tracking with no on-chain component
- —Free-tier bulk data dumps — each call costs $0.01 via x402
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/pnl \
-H 'Content-Type: application/json' \
-H 'Payment-Signature: <x402_payment_signature>' \
-d '{
"address": "0x39d52da6beec991f075eebe577474fd105c5caec",
"chain": "ethereum",
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-05-03T23:59:59Z",
"from": "2025-05-01T00:00:00Z"
},
"chain": "ethereum",
"address": "0x39d52da6beec991f075eebe577474fd105c5caec",
"filters": {
"show_realized": false
},
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"nof_buys": "12",
"sold_usd": 2750,
"nof_sells": "5",
"bought_usd": 5000,
"holding_usd": 2500,
"sold_amount": 2500,
"token_price": 1,
"token_symbol": "USDC",
"bought_amount": 5000,
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"cost_basis_usd": 4750,
"holding_amount": 2500,
"max_balance_held": 6000,
"pnl_usd_realised": 250,
"avg_sold_price_usd": 1.1,
"pnl_usd_unrealised": 100,
"max_balance_held_usd": 6000,
"roi_percent_realised": 0.05,
"roi_percent_unrealised": 0.02
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear x402 pricing ($0.01/call), live 402 challenge confirmed, and comprehensive endpoint documentation. Minor deduction because no example response was directly captured from a live call — the example is constructed from the schema.
Warnings
- —No live response body captured; example response is synthesized from the OpenAPI schema
- —Crawled docs pages returned 404 — documentation may only be available via the OpenAPI spec or external Nansen docs site
Citations
- —The endpoint is at POST /api/v1/profiler/address/pnl and calculates profit and loss metrics for a specific address and tokenhttps://api.nansen.ai
- —x402 fixed pricing at $0.01 per requesthttps://api.nansen.ai
- —Supports chains including ethereum, solana, base, bnb, arbitrum, avalanche, polygon, and more (ProfilerPnLChain enum)https://api.nansen.ai
- —Returns realized PnL, unrealized PnL, ROI percentages, cost basis, bought/sold amounts, and holding datahttps://api.nansen.ai
- —The endpoint returned HTTP 402 with x402 payment challenge confirming it is livehttps://api.nansen.ai/api/v1/profiler/address/pnl