Calculate realized and unrealized PnL for a specific wallet address and token pair across multiple chains.
What it does
This endpoint computes profit and loss metrics for a given blockchain address and token. It returns detailed trading performance data including realized gains from completed sales, unrealized gains from current holdings, average purchase and sale prices, cost basis, buy/sell counts, and maximum balance held. The endpoint supports multiple chains including Ethereum, Solana, Base, Arbitrum, Polygon, and others.
The endpoint is part of Nansen's Profiler suite and accepts POST requests with a JSON body specifying the wallet address (or entity name), chain, optional date range, and filters (such as a specific token_address or show_realized flag). Results can be sorted by realized PnL, unrealized PnL, ROI, bought/sold/holding USD values. Pagination is supported up to 1000 records per page.
Pricing is $0.01 per call via the x402 protocol, or 10 credits (free tier) / 1 credit (pro tier) when using API key authentication. Rate limits apply per-second and per-minute as indicated in response headers.
Capabilities
Use cases
- —Evaluate a wallet's trading performance on a specific token before copying trades
- —Calculate realized and unrealized gains for tax reporting or portfolio tracking
- —Identify profitable traders by analyzing their per-token PnL across chains
- —Build automated trading signals based on smart money wallet performance
- —Audit DeFi fund performance by querying PnL for known fund addresses
Fit
Best for
- —Agents needing per-token PnL breakdown for a specific wallet
- —Portfolio trackers requiring realized vs unrealized gain separation
- —Research workflows analyzing trader profitability on individual tokens
- —Tax tools needing cost basis and average sale price data
Not for
- —Real-time price feeds or live token prices (use OHLCV endpoints instead)
- —Aggregate portfolio-level PnL across all tokens (use pnl-summary endpoint)
- —NFT profit/loss calculations
Quick start
curl -X POST https://api.nansen.ai/api/v1/profiler/address/pnl \
-H "Content-Type: application/json" \
-d '{
"address": "0x39d52da6beec991f075eebe577474fd105c5caec",
"chain": "ethereum",
"date": {"from": "2025-01-01T00:00:00Z", "to": "2025-06-01T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-06-01T23:59:59Z",
"from": "2025-01-01T00:00:00Z"
},
"chain": "ethereum",
"address": "0x39d52da6beec991f075eebe577474fd105c5caec",
"filters": {
"show_realized": true
},
"pagination": {
"page": 1,
"per_page": 10
}
}Response
{
"data": [
{
"nof_buys": "12",
"sold_usd": 26250.5,
"nof_sells": "5",
"bought_usd": 50000,
"holding_usd": 25000,
"sold_amount": 25000,
"token_price": 1,
"token_symbol": "USDC",
"bought_amount": 50000,
"token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"cost_basis_usd": 48000,
"holding_amount": 25000,
"max_balance_held": 60000,
"pnl_usd_realised": 1250.5,
"avg_sold_price_usd": 1.05,
"pnl_usd_unrealised": 300.25,
"max_balance_held_usd": 60000,
"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 pricing ($0.01 via x402), endpoint confirmed live via 402 MPP challenge. No actual response example was captured from a live call, but the schema is comprehensive enough to infer response structure with high confidence.
Warnings
- —No direct probe response body captured — example response is inferred from OpenAPI schema
- —Exact MPP payment flow details (WWW-Authenticate header content) not captured in probe bundle
Citations
- —Endpoint costs $0.01 per call via x402 protocolhttps://api.nansen.ai
- —Credit cost is 10 (free tier) or 1 (pro tier)https://api.nansen.ai
- —Endpoint returns 402 confirming it is live via MPPhttps://api.nansen.ai
- —Supports chains: ethereum, solana, base, arbitrum, avalanche, bnb, linea, mantle, monad, optimism, plasma, polygon, ronin, scroll, sei, sonichttps://api.nansen.ai