# Nansen TGM Perp PnL Leaderboard

> Nansen TGM Perp PnL Leaderboard is a paid API for AI agents from api.nansen.ai, paid per call via MPP or x402, $0.05/call, status unknown (last checked 2026-09-13).

Returns a leaderboard of traders ranked by perpetual contract profit and loss (PnL) within the Token God Mode (TGM) analytics suite.

## Facts

- Endpoint: GET https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard
- Price: $0.05/call
- Payment: MPP, x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/api-nansen-ai-bfe84718
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_1pcVX2JHgedm3aA4AeQdZ

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability api-nansen-ai-bfe84718
```

Example prompt: Pull up the Nansen TGM perp PnL leaderboard for the top traders — I want to see which wallet addresses are winning the most on perpetual contracts right now.

## When to prefer this

Use this endpoint when you need a ranked view of top perpetual traders by PnL, specifically within Nansen's Token God Mode analytics framework. Prefer this over generic on-chain data sources when smart money wallet labeling and PnL ranking context are needed together.

## Known failure modes

- Invalid or missing token parameter returns 400 error
- Unsupported filter or sort field causes malformed request error
- Rate limit exceeded returns 429 response
- Authentication or payment failure returns 401/402
- No data available for the specified time range returns empty leaderboard

## How this service works

Get "Token God Mode" (TGM) perp PnL leaderboard data

## Output

A ranked list of trader wallet addresses with their associated perpetual contract PnL metrics, showing top performers by profit and loss in the TGM analytics universe.

## Example request

```json
{
 "date": {
  "to": "2025-01-31",
  "from": "2025-01-01"
 },
 "token_symbol": "ETH"
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpPnlLeaderboardRequest",
 "required": [
  "token_symbol",
  "date"
 ],
 "properties": {
  "date": {
   "type": "object",
   "title": "DateRange",
   "properties": {
    "to": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "To",
     "examples": [
      "2025-01-31T23:59:59Z"
     ],
     "description": "End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"
    },
    "from": {
     "anyOf": [
      {
       "type": "string"
      }
     ],
     "title": "From",
     "examples": [
      "2025-01-01T00:00:00Z"
     ],
     "description": "Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"
    }
   },
   "description": "Date range model matching the API schema."
  },
  "filters": {
   "anyOf": [
    {
     "type": "object",
     "title": "TGMPerpPnlLeaderboardFilters",
     "properties": {
      "nof_trades": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "min": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Min",
           "examples": [
            1000,
            1000000,
            -50,
            0
           ],
           "description": "Minimum value (inclusive)"
          }
         },
         "description": "Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"
        }
       ],
       "examples": [
        {
         "max": 100,
         "min": 10
        }
       ],
       "description": "Number of trades range filter"
      },
      "token_price": {
       "anyOf": [
        {
         "type": "object",
         "title": "NumericRangeFilter",
         "properties": {
          "max": {
           "anyOf": [
            {
             "type": "number"
            }
           ],
           "title": "Max",
           "examples": [
            50000,
            10000000,
            100
           ],
           "description": "Maximum value (inclusive)"
          },
          "mi
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TGMPerpPnlLeaderboardResponse",
 "required": [
  "data",
  "pagination"
 ],
 "properties": {
  "data": {
   "type": "array",
   "items": {
    "type": "object",
    "title": "TGMPerpPnlLeaderboard",
    "required": [
     "trader_address"
    ],
    "properties": {
     "price_usd": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Price Usd",
      "examples": [
       1.23
      ],
      "description": "Token price in USD at date_to. Uses latest spot price if date_to is today or later, otherwise the daily median price for that date."
     },
     "nof_trades": {
      "anyOf": [
       {
        "type": "integer"
       }
      ],
      "title": "Nof Trades",
      "examples": [
       25
      ],
      "description": "Number of trades."
     },
     "pnl_usd_total": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Pnl Usd Total",
      "examples": [
       1350.75
      ],
      "description": "Total PNL in USD."
     },
     "holding_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Holding Amount",
      "examples": [
       5000
      ],
      "description": "Current token balance"
     },
     "netflow_amount": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Netflow Amount",
      "examples": [
       1500
      ],
      "description": "Netflow amount."
     },
     "trader_address": {
      "type": "string",
      "title": "Trader Address",
      "examples": [
       "0x28c6c06298d514db089934071355e5743bf21d60"
      ],
      "description": "Hexadecimal representation of the trader's address."
     },
     "max_balance_held": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Max Balance Held",
      "examples": [
       10000
      ],
      "description": "Maximum amount of tokens held at some point in time."
     },
     "pnl_usd_realised": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Pnl Usd Realised",
      "examples": [
       1250.5
      ],
      "description": "Realised profit and loss in USD."
     },
     "roi_percent_total": {
      "anyOf": [
       {
        "type": "number"
       }
      ],
      "title": "Roi Percent Total",
      "examples": [
       15.5
      ],
      "description": "Total ROI."
     },
     "netflow_amount_usd": {
      "anyOf": [
       {
       
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/api-nansen-ai-bfe84718/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)