Historical Token PnL Leaderboard

Get historical "Token God Mode" (TGM) PnL leaderboard (Beta)

post

Beta — subject to breaking changes.

Per-trader PnL statistics for a specific token over a historical date range with temporally-correct labels resolved at date_to. Uses label history tables to avoid forward-looking bias.

Key differences from /tgm/pnl-leaderboard:

• Accepts an explicit date_range with Date-only granularity

• Labels resolved at date_to, not the current state

• Supports page-based pagination via per_page and page

• Filter parameters are applied server-side before pagination

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for the historical PnL leaderboard endpoint.

Returns per-trader PnL statistics for a token over a date range with temporally-correct labels resolved at date_to. Uses label history tables to avoid forward-looking bias.

Supports page-based pagination via per_page and page.

chainstring · enumRequired

Blockchain chain

Example: ethereumPossible values:

token_addressstringRequired

Token contract address

Example: 0x6982508145454ce325ddbe47a25d4ec3d2311933

filtersany ofOptional

Optional filters applied server-side

order_byany ofOptional

Sort order. Defaults to pnl_usd_total DESC. Only the first element is used.

apply_blacklist_filterbooleanOptional

When True, exclude blacklisted addresses from the results. Defaults to True.

Default: trueExample: true

Responses

200

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

HTTPcURLJavaScriptPython

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

{
  "chain": "ethereum",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "date_range": {
    "from": "2025-06-01",
    "to": "2025-06-15"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "trader_address": [
      "0x28c6c06298d514db089934071355e5743bf21d60"
    ],
    "pnl_usd_total": {
      "max": 100000,
      "min": -1000
    },
    "roi_percent_total": {
      "max": 500,
      "min": -50
    },
    "pnl_usd_realised": {
      "max": 100000,
      "min": -1000
    },
    "roi_percent_realised": {
      "max": 500,
      "min": -50
    },
    "pnl_usd_unrealised": {
      "max": 100000,
      "min": -1000
    },
    "roi_percent_unrealised": {
      "max": 500,
      "min": -50
    },
    "netflow_amount_usd": {
      "max": 10000,
      "min": -10000
    },
    "holding_usd": {
      "max": 1000000,
      "min": 100
    },
    "nof_trades": {
      "max": 1000,
      "min": 1
    },
    "still_holding_balance_ratio": {
      "max": 1,
      "min": 0.1
    },
    "holding_amount": {
      "max": 1000000,
      "min": 100
    },
    "nof_buys": {
      "max": 100,
      "min": 1
    },
    "nof_sells": {
      "max": 100,
      "min": 1
    },
    "bought_amount": {
      "max": 1000000,
      "min": 100
    },
    "sold_amount": {
      "max": 1000000,
      "min": 100
    },
    "bought_usd": {
      "max": 1000000,
      "min": 1000
    },
    "sold_usd": {
      "max": 1000000,
      "min": 1000
    },
    "max_balance_held": {
      "max": 1000000,
      "min": 100
    },
    "max_balance_held_usd": {
      "max": 1000000,
      "min": 1000
    }
  },
  "order_by": [
    {
      "field": "pnl_usd_total",
      "direction": "ASC"
    }
  ],
  "apply_blacklist_filter": true
}

{
  "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
  }
}