# Address PnL & Trade Performance

{% hint style="info" %}
You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: [**Click Here**](https://docs.nansen.ai/api/profiler/entity-name-search)
{% endhint %}

## Get Address PnL Summary Data

> Get aggregate PnL statistics and top profitable tokens for a specific wallet address.\
> This endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens.

```json
{"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apiKey","description":"API key for authentication"}},"schemas":{"ProfilerAddressPnlSummaryRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Address to get PnL summary for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get PnL summary for"},"chain":{"$ref":"#/components/schemas/ProfilerPnLChain","description":"Blockchain chain for the PnL data"},"date":{"$ref":"#/components/schemas/DateRange","description":"Date range for the PnL data"}},"additionalProperties":false,"type":"object","required":["chain","date"],"title":"ProfilerAddressPnlSummaryRequest","description":""},"ProfilerPnLChain":{"type":"string","enum":["all","arbitrum","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic"],"title":"ProfilerPnLChain","description":"Chains supported in profiler PnL analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressPnlSummaryResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"top5_tokens":{"items":{"$ref":"#/components/schemas/ProfilerTopToken"},"type":"array","title":"Top5 Tokens","description":"Top 5 tokens by realized profit"},"traded_token_count":{"type":"integer","title":"Traded Token Count","description":"Total number of different tokens that have been bought or sold"},"traded_times":{"type":"integer","title":"Traded Times","description":"Total number of sales (outflow or dex sell)"},"realized_pnl_usd":{"type":"number","title":"Realized Pnl Usd","description":"Total realized profit and loss in USD"},"realized_pnl_percent":{"type":"number","title":"Realized Pnl Percent","description":"Realized profit and loss as a percentage (not multiplied by 100)"},"win_rate":{"type":"number","title":"Win Rate","description":"Number of sales where price of the token was higher than cost basis"}},"type":"object","required":["pagination","top5_tokens","traded_token_count","traded_times","realized_pnl_usd","realized_pnl_percent","win_rate"],"title":"ProfilerAddressPnlSummaryResponse","description":"Response model for profiler address pnl-summary endpoint.\n\nContains aggregate PnL statistics and top profitable tokens."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerTopToken":{"properties":{"realized_pnl":{"anyOf":[{"type":"number"}],"title":"Realized Pnl","description":"Realized profit and loss in USD"},"realized_roi":{"anyOf":[{"type":"number"}],"title":"Realized Roi","description":"Realized return on investment as percentage"},"token_address":{"type":"string","title":"Token Address","description":"Token contract address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"chain":{"type":"string","title":"Chain","description":"Blockchain chain"}},"type":"object","required":["realized_pnl","realized_roi","token_address","token_symbol","chain"],"title":"ProfilerTopToken","description":"Individual top token record for PnL summary.\n\nRepresents a top profitable token from the wallet's trading history."}},"headers":{"XNansenCreditsUsed":{"description":"Number of credits consumed by this API request","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Time in seconds until the rate limit window resets","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via the x402 protocol. The `Payment-Required` response header contains a base64-encoded JSON object describing accepted payment options (scheme, network, asset, amount, recipient). To pay, include a `Payment-Signature` header with a base64-encoded signed payment payload. See https://www.x402.org for protocol details.","headers":{"Payment-Required":{"description":"Base64-encoded JSON describing accepted payment options","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","description":"Empty object. Payment details are in the Payment-Required header."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string"}}}}}}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}},"paths":{"/api/v1/profiler/address/pnl-summary":{"post":{"tags":["Profiler"],"summary":"Get Address PnL Summary Data","description":"Get aggregate PnL statistics and top profitable tokens for a specific wallet address.\nThis endpoint provides comprehensive profit and loss analysis including realized PnL, win rate, and top performing tokens.","operationId":"get_profiler_address_pnl_summary_api_v1_profiler_address_pnl_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlSummaryRequest"}}},"required":true},"responses":{"200":{"description":"Address PnL summary data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlSummaryResponse"}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get Address PnL Data

> 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.\
> \
> What it helps to answer:\
> \
> \- Realized profits or losses from completed token sales\
> \- Unrealized gains or losses on current token holdings\
> \- Average purchase and sale prices for the token\
> \- Total return on investment

```json
{"openapi":"3.1.0","info":{"title":"Nansen API","version":"1.0.0"},"servers":[{"url":"https://api.nansen.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apiKey","description":"API key for authentication"}},"schemas":{"ProfilerAddressPnlRequest":{"properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","description":"Wallet address to get PnL for"},"entity_name":{"anyOf":[{"type":"string"}],"title":"Entity Name","description":"Entity name to get PnL for"},"chain":{"$ref":"#/components/schemas/ProfilerPnLChain","description":"Blockchain chain for the PnL data"},"date":{"anyOf":[{"$ref":"#/components/schemas/DateRange"}],"description":"Date range for PnL analysis (ISO 8601 date-time)"},"filters":{"anyOf":[{"$ref":"#/components/schemas/ProfilerAddressPnlFilters"}],"description":"Additional filters to apply."},"pagination":{"$ref":"#/components/schemas/PaginationRequest","description":"Pagination parameters"},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/SortOrder_ProfilerAddressPnlSortField_"},"type":"array"}],"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."}},"additionalProperties":false,"type":"object","required":["chain"],"title":"ProfilerAddressPnlRequest","description":""},"ProfilerPnLChain":{"type":"string","enum":["all","arbitrum","avalanche","base","bnb","ethereum","linea","mantle","monad","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic"],"title":"ProfilerPnLChain","description":"Chains supported in profiler PnL analysis."},"DateRange":{"properties":{"from":{"anyOf":[{"type":"string"}],"title":"From","description":"Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"},"to":{"anyOf":[{"type":"string"}],"title":"To","description":"End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"}},"type":"object","title":"DateRange","description":"Date range model matching the API schema."},"ProfilerAddressPnlFilters":{"properties":{"show_realized":{"anyOf":[{"type":"boolean"}],"title":"Show Realized","description":"Include realized profit/loss in results","default":false},"token_address":{"anyOf":[{"type":"string"}],"title":"Token Address","description":"Token address filter for specific token PnL"}},"additionalProperties":false,"type":"object","title":"ProfilerAddressPnlFilters","description":"Filters for profiler address PnL endpoint.\n\nThese filters control token filtering and realized PnL options for analysis."},"PaginationRequest":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Page number (1-based)","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page (max 1000)","default":10}},"type":"object","title":"PaginationRequest","description":"Pagination parameters for API requests."},"SortOrder_ProfilerAddressPnlSortField_":{"properties":{"field":{"$ref":"#/components/schemas/ProfilerAddressPnlSortField","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction (ASC or DESC)"}},"type":"object","required":["field","direction"],"title":"SortOrder[ProfilerAddressPnlSortField]"},"ProfilerAddressPnlSortField":{"type":"string","enum":["pnl_usd_realised","roi_percent_realised","pnl_usd_unrealised","roi_percent_unrealised","bought_usd","sold_usd","holding_usd"],"title":"ProfilerAddressPnlSortField","description":"Enum for sortable fields in profiler address PnL."},"SortDirection":{"type":"string","enum":["ASC","DESC"],"title":"SortDirection","description":"Enum for sort directions."},"ProfilerAddressPnlResponse":{"properties":{"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"},"data":{"items":{"$ref":"#/components/schemas/ProfilerAddressPnl"},"type":"array","title":"Data","description":"List of PnL records"}},"type":"object","required":["pagination","data"],"title":"ProfilerAddressPnlResponse","description":"Response model for profiler address pnl endpoint.\n\nContains the filtered PnL data with metadata."},"PaginationInfo":{"properties":{"page":{"type":"integer","minimum":1,"title":"Page","description":"Current page number","default":1},"per_page":{"type":"integer","maximum":1000,"minimum":1,"title":"Per Page","description":"Number of records per page","default":10},"is_last_page":{"type":"boolean","title":"Is Last Page","description":"Whether this is the last page","default":true}},"type":"object","title":"PaginationInfo","description":"Pagination information for API responses."},"ProfilerAddressPnl":{"properties":{"token_address":{"type":"string","title":"Token Address","description":"Hexadecimal representation of the token's address"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Symbol of the token"},"token_price":{"anyOf":[{"type":"number"}],"title":"Token Price","description":"Price of the token on date_to"},"roi_percent_realised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Realised","description":"Realised return on investment for only realised gains (not multiplied by 100)"},"pnl_usd_realised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Realised","description":"Realised profit and loss in USD"},"pnl_usd_unrealised":{"anyOf":[{"type":"number"}],"title":"Pnl Usd Unrealised","description":"Unrealised profit and loss in USD"},"roi_percent_unrealised":{"anyOf":[{"type":"number"}],"title":"Roi Percent Unrealised","description":"Unrealised return on investment for only unrealised gains (not multiplied by 100)"},"bought_amount":{"anyOf":[{"type":"number"}],"title":"Bought Amount","description":"Amount of tokens bought from date_from to date_to"},"bought_usd":{"anyOf":[{"type":"number"}],"title":"Bought Usd","description":"USD value of bought tokens"},"cost_basis_usd":{"anyOf":[{"type":"number"}],"title":"Cost Basis Usd","description":"Cost basis of tokens in USD as of date_to"},"sold_amount":{"anyOf":[{"type":"number"}],"title":"Sold Amount","description":"Amount of tokens sold from date_from to date_to"},"sold_usd":{"anyOf":[{"type":"number"}],"title":"Sold Usd","description":"USD value of sold tokens"},"avg_sold_price_usd":{"anyOf":[{"type":"number"}],"title":"Avg Sold Price Usd","description":"Average sale price of tokens sold in USD"},"holding_amount":{"anyOf":[{"type":"number"}],"title":"Holding Amount","description":"Current token balance"},"holding_usd":{"anyOf":[{"type":"number"}],"title":"Holding Usd","description":"USD value of token balance"},"nof_buys":{"type":"string","title":"Nof Buys","description":"Number of buys (either inflow or dex buy)"},"nof_sells":{"type":"string","title":"Nof Sells","description":"Number of sells (either outflow or dex sell)"},"max_balance_held":{"anyOf":[{"type":"number"}],"title":"Max Balance Held","description":"Maximum amount of tokens held at some point in time"},"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"}},"type":"object","required":["token_address","token_symbol","nof_buys","nof_sells"],"title":"ProfilerAddressPnl","description":"Individual profiler address PnL record.\n\nRepresents PnL data for a token traded by the wallet."}},"headers":{"XNansenCreditsUsed":{"description":"Number of credits consumed by this API request","schema":{"type":"string"}},"XNansenCreditsRemaining":{"description":"Total credits remaining in the user's account after this request","schema":{"type":"string"}},"RateLimitLimit":{"description":"Combined rate limit across all configured time windows","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current limiting window","schema":{"type":"string"}},"RateLimitReset":{"description":"Time in seconds until the rate limit window resets","schema":{"type":"string"}},"XRateLimitLimitSecond":{"description":"Maximum requests allowed per second","schema":{"type":"string"}},"XRateLimitRemainingSecond":{"description":"Requests remaining in the current second","schema":{"type":"string"}},"XRateLimitLimitMinute":{"description":"Maximum requests allowed per minute","schema":{"type":"string"}},"XRateLimitRemainingMinute":{"description":"Requests remaining in the current minute","schema":{"type":"string"}},"RetryAfter":{"description":"Number of seconds to wait before making a new request","schema":{"type":"string"}}},"responses":{"BadRequestError":{"description":"Bad Request - Invalid request parameters or malformed request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"UnauthorizedError":{"description":"Authentication error - No API key found in request","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"PaymentRequiredError":{"description":"Payment Required - This endpoint supports pay-per-request via the x402 protocol. The `Payment-Required` response header contains a base64-encoded JSON object describing accepted payment options (scheme, network, asset, amount, recipient). To pay, include a `Payment-Signature` header with a base64-encoded signed payment payload. See https://www.x402.org for protocol details.","headers":{"Payment-Required":{"description":"Base64-encoded JSON describing accepted payment options","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","description":"Empty object. Payment details are in the Payment-Required header."}}}},"ForbiddenError":{"description":"Forbidden - User does not have required subscription tier or has exceeded credit limit","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"NotFoundError":{"description":"Not Found - The requested resource was not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"ValidationError":{"description":"Validation error - Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string"}}}}}}}}},"TooManyRequestsError":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"InternalServerError":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}},"paths":{"/api/v1/profiler/address/pnl":{"post":{"tags":["Profiler"],"summary":"Get Address PnL Data","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","operationId":"get_profiler_address_pnl_api_v1_profiler_address_pnl_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlRequest"}}},"required":true},"responses":{"200":{"description":"Address PnL data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfilerAddressPnlResponse"}}},"headers":{"X-Nansen-Credits-Used":{"$ref":"#/components/headers/XNansenCreditsUsed"},"X-Nansen-Credits-Remaining":{"$ref":"#/components/headers/XNansenCreditsRemaining"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-RateLimit-Limit-Second":{"$ref":"#/components/headers/XRateLimitLimitSecond"},"X-RateLimit-Remaining-Second":{"$ref":"#/components/headers/XRateLimitRemainingSecond"},"X-RateLimit-Limit-Minute":{"$ref":"#/components/headers/XRateLimitLimitMinute"},"X-RateLimit-Remaining-Minute":{"$ref":"#/components/headers/XRateLimitRemainingMinute"}}},"400":{"description":"Bad Request","$ref":"#/components/responses/BadRequestError"},"401":{"description":"Unauthorized","$ref":"#/components/responses/UnauthorizedError"},"402":{"description":"Payment Required","$ref":"#/components/responses/PaymentRequiredError"},"403":{"description":"Forbidden","$ref":"#/components/responses/ForbiddenError"},"404":{"description":"Not Found","$ref":"#/components/responses/NotFoundError"},"422":{"description":"Unprocessable Content","$ref":"#/components/responses/ValidationError"},"429":{"description":"Too Many Requests","$ref":"#/components/responses/TooManyRequestsError"},"500":{"description":"Internal Server Error","$ref":"#/components/responses/InternalServerError"}}}}}}
```