{"uid":"cap_oy3deNNchURuq1ResoibE","slug":"nansen-pnl-e95992bb","name":"Nansen Address PnL","description":"Calculate profit and loss metrics for a specific address and token. Provides detailed trading performance including realized gains from sales and unrealized gains from current holdings.\n\nWhat it helps to answer:\n\n- Realized profits or losses from completed token sales\n- Unrealized gains or losses on current token holdings\n- Average purchase and sale prices for the token\n- Total return on investment","url":"https://api.nansen.ai/api/v1/profiler/address/pnl?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"ProfilerAddressPnlRequest","examples":[{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","address":"0x39d52da6beec991f075eebe577474fd105c5caec","pagination":{"page":1,"per_page":10}},{"date":{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"},"chain":"ethereum","pagination":{"page":1,"per_page":10},"entity_name":"Vitalik Buterin"}],"required":["chain"],"properties":{"date":{"anyOf":[{"type":"object","title":"DateRange","properties":{"to":{"anyOf":[{"type":"string"}],"title":"To","examples":["2025-01-31T23:59:59Z"],"description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"},"from":{"anyOf":[{"type":"string"}],"title":"From","examples":["2025-01-01T00:00:00Z"],"description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"}},"description":"Date range model matching the API schema."}],"examples":[{"to":"2025-05-03T23:59:59Z","from":"2025-05-01T00:00:00Z"}],"description":"Date range for PnL analysis (ISO 8601 date-time)"},"chain":{"enum":["all","arbitrum","arc","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","robinhood","sei","solana","sonic","sui"],"type":"string","title":"ProfilerPnLChain","description":"Chains supported in profiler PnL analysis."},"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x39d52da6beec991f075eebe577474fd105c5caec","8zFZHuSRuDpuAR7J6FzwyF3vKNx4CVW3DFHJerQhc7Zd"],"description":"Wallet address to get PnL for"},"filters":{"anyOf":[{"type":"object","title":"ProfilerAddressPnlFilters","properties":{"show_realized":{"anyOf":[{"type":"boolean"}],"title":"Show Realized","default":false,"examples":[true,false],"description":"Include realized profit/loss in results"},"token_address":{"anyOf":[{"type":"string"}],"title":"Token Address","examples":["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],"description":"Token address filter for specific token PnL"}},"description":"Filters for profiler address PnL endpoint.\n\nThese filters control token filtering and realized PnL options for analysis.","additionalProperties":false}],"examples":[{"show_realized":false}],"description":"Additional filters to apply."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"ProfilerAddressPnlSortOrder","required":["field","direction"],"properties":{"field":{"enum":["pnl_usd_realised","roi_percent_realised","pnl_usd_unrealised","roi_percent_unrealised","bought_usd","sold_usd","holding_usd"],"type":"string","title":"ProfilerAddressPnlSortField","description":"Enum for sortable fields in profiler address PnL."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering (default: pnl_usd_realised DESC).\n\nIf the parameter show_realized is false, the default sort order is pnl_usd_unrealised DESC."},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","examples":["Vitalik Buterin","Binance"],"description":"Entity name to get PnL for"}},"description":"","additionalProperties":false},"responseSchema":{"type":"object","title":"ProfilerAddressPnlResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"ProfilerAddressPnl","required":["token_address","token_symbol","nof_buys","nof_sells"],"properties":{"nof_buys":{"type":"string","title":"Nof Buys","description":"Number of buys (either inflow or dex buy)"},"sold_usd":{"anyOf":[{"type":"number"}],"title":"Sold Usd","description":"USD value of sold tokens"},"nof_sells":{"type":"string","title":"Nof Sells","description":"Number of sells (either outflow or dex sell)"},"bought_usd":{"anyOf":[{"type":"number"}],"title":"Bought Usd","description":"USD value of bought tokens"},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","description":"USD value of token balance"},"sold_amount":{"anyOf":[{"type":"number"}],"title":"Sold Amount","description":"Amount of tokens sold from date_from to date_to"},"token_price":{"anyOf":[{"type":"number"}],"title":"Token Price","description":"Price of the token on date_to"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"bought_amount":{"anyOf":[{"type":"number"}],"title":"Bought Amount","description":"Amount of tokens bought from date_from to date_to"},"token_address":{"type":"string","title":"Token Address","description":"Hexadecimal representation of the token's address"},"cost_basis_usd":{"anyOf":[{"type":"number"}],"title":"Cost Basis Usd","description":"Cost basis of tokens in USD as of date_to"},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time"},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD"},"avg_sold_price_usd":{"anyOf":[{"type":"number"}],"title":"Avg Sold Price Usd","description":"Average sale price of tokens sold in USD"},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD"},"max_balance_held_usd":{"anyOf":[{"type":"number"}],"title":"Max Balance Held Usd","description":"Maximum amount of tokens in current USD value, held at some point in time"},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised return on investment for only realised gains (not multiplied by 100)"},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised return on investment for only unrealised gains (not multiplied by 100)"}},"description":"Individual profiler address PnL record.\n\nRepresents PnL data for a token traded by the wallet."},"title":"Data","description":"List of PnL records"},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response model for profiler address pnl endpoint.\n\nContains the filtered PnL data with metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_1AdY2Ix0EoSR_2Rzq9TR2","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Calculates realized and unrealized profit/loss metrics for a wallet address across tokens on a specified blockchain and date range.","exampleAgentPrompt":"Can you pull the profit and loss breakdown for wallet 0x39d52da6beec991f075eebe577474fd105c5caec on Ethereum from May 1 to May 3, 2025, including both realized and unrealized gains, showing 10 results per page?","exampleUseCases":null,"resultDescription":"Returns a paginated array of per-token PnL records for the wallet, each containing realized PnL in USD, unrealized/holding value, cost basis, number of buys/sells, bought and sold amounts and USD values, average buy/sell prices, max balance held, current token price, and ROI percentage.","failureModes":["Invalid or unsupported chain returns 400 error","Malformed wallet address returns validation error","Date range with no trading activity returns empty data array","Unsupported chain/network combination returns error","Missing required 'chain' field returns 422 validation error","Rate limit exceeded returns 429 error","Insufficient payment or expired payment header returns 402"],"whenToPreferThis":"Use this endpoint when you need granular, per-token trading performance for a specific wallet address including both realized gains from completed trades and unrealized gains on current holdings. Prefer this over general token holder endpoints when you need cost basis, average price, and ROI metrics specifically. Best for smart money tracking, alpha research, and portfolio performance analysis across 17 supported chains.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:41:43.885Z","isFirstParty":false,"canonicalSlug":"nansen-pnl-e95992bb"}