{"uid":"cap_ldNjAKbHDjTI_lu3L1vnm","slug":"api-nansen-ai-8e7ddd89","name":"Nansen Address PnL Data","description":"Retrieve address PnL data","url":"https://api.nansen.ai/api/v1/profiler/address/pnl","method":"GET","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","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic"],"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":"SortOrder[ProfilerAddressPnlSortField]","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":{"request":{"date":{"to":"2025-01-31T23:59:59Z","from":"2025-01-01T00:00:00Z"},"chain":"ethereum","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"},"response":{"data":[{"nof_buys":"13","sold_usd":0,"nof_sells":"0","bought_usd":49.330990952307786,"holding_usd":2299552.264425837,"sold_amount":0,"token_price":0.00007664588795512441,"token_symbol":"MOODENG","bought_amount":2185502.811077946,"token_address":"0x28561b8a2360f463011c16b6cc0b0cbef8dbbcad","cost_basis_usd":1.8402753905083405e-7,"holding_amount":30002291391.968834,"max_balance_held":30002291391.968834,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":2294031.016575087,"max_balance_held_usd":2299552.264425837,"roi_percent_realised":null,"roi_percent_unrealised":415.49140313696455},{"nof_buys":"4592","sold_usd":6284741.103068229,"nof_sells":"28","bought_usd":6313231.872267447,"holding_usd":18691.332267464968,"sold_amount":2434.8445592663315,"token_price":3292.5181889582327,"token_symbol":"ETH","bought_amount":2151.26462390715,"token_address":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","cost_basis_usd":2288.8793541029513,"holding_amount":5.676910861160341,"max_balance_held":1012.7624963697671,"pnl_usd_realised":-739762.9628129738,"avg_sold_price_usd":2581.1672778659636,"pnl_usd_unrealised":5697.568202272257,"max_balance_held_usd":3334538.940392204,"roi_percent_realised":-0.10531177089156864,"roi_percent_unrealised":0.43848481269062944},{"nof_buys":"12","sold_usd":43301.74481932273,"nof_sells":"1","bought_usd":9368.32659980857,"holding_usd":4814.8474086663,"sold_amount":16.39510978771529,"token_price":3293.558694559951,"token_symbol":"WETH","bought_amount":3.2933651553592846,"token_address":"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","cost_basis_usd":2323.5363393530242,"holding_amount":1.461898164019089,"max_balance_held":16.39510978771529,"pnl_usd_realised":-11712.250364807998,"avg_sold_price_usd":2641.137838050243,"pnl_usd_unrealised":1418.073900134479,"max_balance_held_usd":53998.256389594644,"roi_percent_realised":-0.21289583360756353,"roi_percent_unrealised":0.41747673095443144},{"nof_buys":"2","sold_usd":21200.684595607734,"nof_sells":"1","bought_usd":17.56042666019685,"holding_usd":178.6900122237979,"sold_amount":4206900000,"token_price":0.000009017020323531712,"token_symbol":"PEEZY","bought_amount":19816969,"token_address":"0x698b1d54e936b9f772b8f58447194bbc82ec1933","cost_basis_usd":8.861308033633624e-7,"holding_amount":19816969,"max_balance_held":4206900000,"pnl_usd_realised":17808.644289989646,"avg_sold_price_usd":0.000005039502863297852,"pnl_usd_unrealised":161.12958556360104,"max_balance_held_usd":37933.702799065555,"roi_percent_realised":5.250127559066435,"roi_percent_unrealised":9.175721563122591},{"nof_buys":"1","sold_usd":0,"nof_sells":"0","bought_usd":8.459365501773245,"holding_usd":137.26761955581705,"sold_amount":0,"token_price":0.019893857906640153,"token_symbol":"BUSINESS","bought_amount":6900,"token_address":"0xc06caead870d3a8af2504637b6c5b7248bed6116","cost_basis_usd":0.001225995000256992,"holding_amount":6900,"max_balance_held":6900,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":128.8082540540438,"max_balance_held_usd":137.26761955581705,"roi_percent_realised":null,"roi_percent_unrealised":15.226703944526705},{"nof_buys":"1","sold_usd":0,"nof_sells":"0","bought_usd":437.5736888322781,"holding_usd":472.19618253805123,"sold_amount":0,"token_price":0.001837339231665569,"token_symbol":"CATALORIAN","bought_amount":257000,"token_address":"0x8baf5d75cae25c7df6d1e0d26c52d19ee848301a","cost_basis_usd":0.0017026213573240394,"holding_amount":257000,"max_balance_held":257000,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":34.62249370577312,"max_balance_held_usd":472.19618253805123,"roi_percent_realised":null,"roi_percent_unrealised":0.07912380152053414},{"nof_buys":"2","sold_usd":0,"nof_sells":"0","bought_usd":1.2778837691646472,"holding_usd":20.27416962124089,"sold_amount":0,"token_price":2.9967667946376615,"token_symbol":"EIGEN","bought_amount":6.765347793334795,"token_address":"0xec53bf9167f50cdeb3ae105f56099aaab9061f83","cost_basis_usd":0.18888663350369295,"holding_amount":6.765347793334795,"max_balance_held":6.765347793334795,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":18.99628585207624,"max_balance_held_usd":20.27416962124089,"roi_percent_realised":null,"roi_percent_unrealised":14.865425409146653},{"nof_buys":"1","sold_usd":0,"nof_sells":"0","bought_usd":5.012790897826157,"holding_usd":16.45866548767041,"sold_amount":0,"token_price":3.634150939557273e-7,"token_symbol":"TITANX","bought_amount":45288888,"token_address":"0xf19308f923582a6f7c465e5ce7a9dc1bec6665b1","cost_basis_usd":1.106847864718197e-7,"holding_amount":45288888,"max_balance_held":45288888,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":11.445874589844252,"max_balance_held_usd":16.45866548767041,"roi_percent_realised":null,"roi_percent_unrealised":2.283333740253929},{"nof_buys":"4","sold_usd":0,"nof_sells":"0","bought_usd":14.13951075259385,"holding_usd":34.20033563395344,"sold_amount":0,"token_price":0.19092072364917068,"token_symbol":"BOOE","bought_amount":111.1337,"token_address":"0x289ff00235d2b98b0145ff5d4435d3e92f9540a6","cost_basis_usd":0.1463164541546388,"holding_amount":179.13369999999998,"max_balance_held":179.13369999999998,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":7.990127830352626,"max_balance_held_usd":34.20033563395344,"roi_percent_realised":null,"roi_percent_unrealised":0.3048479390253033},{"nof_buys":"1","sold_usd":0,"nof_sells":"0","bought_usd":5.175724769813666,"holding_usd":13.075988806314957,"sold_amount":0,"token_price":19.932430225138837,"token_symbol":"VISTA","bought_amount":0.6560157822513525,"token_address":"0xc9bca88b04581699fab5aa276ccaff7df957cbbf","cost_basis_usd":7.889634532954859,"holding_amount":0.6560157822513525,"max_balance_held":0.6560157822513525,"pnl_usd_realised":0,"avg_sold_price_usd":null,"pnl_usd_unrealised":7.900264036501291,"max_balance_held_usd":13.075988806314957,"roi_percent_realised":null,"roi_percent_unrealised":1.526407293250586}],"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"date":{"to":"2025-01-31T23:59:59Z","from":"2025-01-01T00:00:00Z"},"chain":"ethereum","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"},"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_yK8nFVMMk1wR9h5H32USm","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_Qg_lOft0ZyJic6YtSEB5J","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves profit and loss (PnL) data for a given blockchain address, powered by Nansen's smart money analytics.","exampleAgentPrompt":"Pull the Nansen PnL data for wallet address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 and tell me how profitable this address has been overall.","exampleUseCases":null,"resultDescription":"Returns profit and loss metrics for the specified blockchain address, including realized and unrealized PnL figures derived from Nansen's on-chain transaction and wallet analytics.","failureModes":["Invalid or malformed wallet address returns a 400 error","Address not found or no trading history results in empty or null PnL data","Rate limiting or quota exhaustion returns a 429 error","Payment failure (x402 protocol) results in unauthorized response","Network timeout for addresses with extensive transaction history"],"whenToPreferThis":"Use this endpoint when you need detailed PnL performance metrics for a specific blockchain address, especially when you want Nansen's smart money labeling context. Prefer this over generic on-chain explorers when you need aggregated profit/loss figures rather than raw transaction data.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:50:25.499Z","isFirstParty":false}