Address PnL & Trade Performance

You can use this endpoint to find correct entity name format to use in this Profiler Endpoint: Click Here

Get Address PnL Summary Data

post

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.

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

addressany ofOptional

Address to get PnL summary for

Example: 0x39d52da6beec991f075eebe577474fd105c5caec

stringOptional

entity_nameany ofOptional

Entity name to get PnL summary for

Example: Vitalik Buterin

stringOptional

chainstring · enumRequired

Blockchain chain for the PnL data

Example: ethereumPossible values:

Responses

200

Address PnL summary data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/pnl-summary

HTTPcURLJavaScriptPython

POST /api/v1/profiler/address/pnl-summary HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "address": "0x39d52da6beec991f075eebe577474fd105c5caec",
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  }
}

{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "top5_tokens": [
    {
      "realized_pnl": 1,
      "realized_roi": 1,
      "token_address": "text",
      "token_symbol": "text",
      "chain": "text"
    }
  ],
  "traded_token_count": 1,
  "traded_times": 1,
  "realized_pnl_usd": 1,
  "realized_pnl_percent": 1,
  "win_rate": 1
}

Get Address PnL Data

post

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

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

addressany ofOptional

Wallet address to get PnL for

Example: 0x39d52da6beec991f075eebe577474fd105c5caec

stringOptional

entity_nameany ofOptional

Entity name to get PnL for

Example: Vitalik Buterin

stringOptional

chainstring · enumRequired

Blockchain chain for the PnL data

Example: ethereumPossible values:

dateany ofOptional

Date range for PnL analysis

Example: {"from":"2025-05-01","to":"2025-05-03"}

filtersany ofOptional

Additional filters to apply.

Example: {"show_realized":false}

order_byany ofOptional

Custom sort order to override the endpoint's default ordering (default: pnl_usd_realised DESC).

If the parameter show_realized is false, the default sort order is pnl_usd_unrealised DESC.

Responses

200

Address PnL data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/profiler/address/pnl

HTTPcURLJavaScriptPython

POST /api/v1/profiler/address/pnl HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "address": "0x39d52da6beec991f075eebe577474fd105c5caec",
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01",
    "to": "2025-05-03"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  }
}

{
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "data": [
    {
      "token_address": "text",
      "token_symbol": "text",
      "token_price": 1,
      "roi_percent_realised": 1,
      "pnl_usd_realised": 1,
      "pnl_usd_unrealised": 1,
      "roi_percent_unrealised": 1,
      "bought_amount": 1,
      "bought_usd": 1,
      "cost_basis_usd": 1,
      "sold_amount": 1,
      "sold_usd": 1,
      "avg_sold_price_usd": 1,
      "holding_amount": 1,
      "holding_usd": 1,
      "nof_buys": "text",
      "nof_sells": "text",
      "max_balance_held": 1,
      "max_balance_held_usd": 1
    }
  ]
}