Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Address PnL & Trade Performance

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

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

  • The aggregate PnL summary is served from a short server-side cache of up to about an hour, so its figures may lag your most recent trades by up to that long; the detailed per-token PnL breakdown is served live within the standard latency.

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
apikeystringRequired

API key for authentication

Body
wallet_addressany ofOptional

Wallet address to get PnL summary for

Example: 0x39d52da6beec991f075eebe577474fd105c5caec
stringOptional
addressany ofOptionalDeprecated

Deprecated: Use 'wallet_address' instead. Alias of wallet_address. If you send both fields, they must contain the same address.

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
post/api/v1/profiler/address/pnl-summary
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: 149

{
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  },
  "wallet_address": "0x39d52da6beec991f075eebe577474fd105c5caec"
}
{
  "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
}

Retrieve 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
apikeystringRequired

API key for authentication

Body
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 (ISO 8601 date-time)

Example: {"from":"2025-05-01T00:00:00Z","to":"2025-05-03T23:59:59Z"}
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
post/api/v1/profiler/address/pnl
POST /api/v1/profiler/address/pnl HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 180

{
  "address": "0x39d52da6beec991f075eebe577474fd105c5caec",
  "chain": "ethereum",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  },
  "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
    }
  ]
}
PreviousAddress First Funder
NextAddress Labels

Last updated

Was this helpful?