PnL Leaderboard

Update: A premium_labels parameter is being added to this endpoint. From April 1, the default changes from true to false .

Get TGM PnL Leaderboard Data

post

Rank traders by their profit/loss performance for a specific token. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input token.

Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for TGM PnL leaderboard endpoint. This endpoint provides a token PnL leaderboard showing the most profitable traders for a specific token within a given date range.

chainstring · enumRequired

Blockchain chain

Example: ethereumPossible values:

token_addressstringRequired

Token address

Example: 0x6982508145454ce325ddbe47a25d4ec3d2311933

filtersany ofOptional

Additional filters to apply to the query.

Example: {"holding_usd":{"min":1000},"pnl_usd_realised":{"min":1000}}

premium_labelsany ofOptional

Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.

booleanOptional

order_byany ofOptional

Custom sort order to override the endpoint's default ordering

Responses

200

TGM PnL leaderboard data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

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/tgm/pnl-leaderboard

HTTPcURLJavaScriptPython

POST /api/v1/tgm/pnl-leaderboard HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 339

{
  "chain": "ethereum",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "date": {
    "from": "2025-07-14T00:00:00Z",
    "to": "2025-07-15T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "holding_usd": {
      "min": 1000
    },
    "pnl_usd_realised": {
      "min": 1000
    }
  },
  "premium_labels": true,
  "order_by": [
    {
      "field": "pnl_usd_realised",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "trader_address_label": "🏦 Binance 14 [0x28c6c0]",
      "price_usd": 1.23,
      "pnl_usd_realised": 1250.5,
      "pnl_usd_unrealised": 100.25,
      "holding_amount": 5000,
      "holding_usd": 6000,
      "max_balance_held": 10000,
      "max_balance_held_usd": 12000,
      "still_holding_balance_ratio": 0.5,
      "netflow_amount_usd": 2500.75,
      "netflow_amount": 1500,
      "roi_percent_total": 15.5,
      "roi_percent_realised": 12.3,
      "roi_percent_unrealised": 3.2,
      "pnl_usd_total": 1350.75,
      "nof_trades": 25
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}