> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Whale Leaderboard

> Top perps accounts, ranked. `metric=equity` ranks by account equity; `metric=size` by total open notional; `metric=pnl` by total unrealized PnL. Optional `instrument` filter. **Polymarket has no perps leaderboard** — perps trades carry no account attribution, so this only exists because we snapshot every account's portfolio over time.

Rank perps accounts three ways:

* **`metric=equity`** (default) — by account equity. The biggest accounts by capital.
* **`metric=size`** — by total open notional across all their positions. The biggest active risk-takers.
* **`metric=pnl`** — by total unrealized profit/loss across their open positions.

Add `?instrument=BTC-USD` to rank within a single market, and `?limit=` to control how many rows.

Polymarket has no perps leaderboard, and can't easily build one: its public trade feed carries no account attribution, so there's no way to rank accounts from it. This works because we snapshot every account's portfolio continuously. Each row is drawn from that account's most recent snapshot, with an `as_of` timestamp.


## OpenAPI

````yaml GET /v3/perps/leaderboard
openapi: 3.1.0
info:
  title: PolyNode API
  description: >-
    Real-time Polymarket data API with decoded mempool settlements, OHLCV
    candles, and full Polygon JSON-RPC proxy.
  contact:
    name: PolyNode
    url: https://polynode.dev
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.polynode.dev
    description: Production
security:
  - api_key: []
paths:
  /v3/perps/leaderboard:
    get:
      tags:
        - Perps
      summary: Whale leaderboard
      description: >-
        Top perps accounts, ranked. `metric=equity` ranks by account equity;
        `metric=size` by total open notional; `metric=pnl` by total unrealized
        PnL. Optional `instrument` filter. **Polymarket has no perps
        leaderboard** — perps trades carry no account attribution, so this only
        exists because we snapshot every account's portfolio over time.
      operationId: perps_leaderboard
      parameters:
        - name: metric
          in: query
          required: false
          description: equity (default) | size | pnl
          schema:
            type: string
        - name: instrument
          in: query
          required: false
          description: Restrict to one instrument
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Max rows (default 100)
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                data:
                  - address: '0x4f78dcb560f85bb028d6b75467c4bcb6412f8731'
                    as_of: 1783602532386
                    positions: 3
                    total_notional: '1815468.212200'
                    total_unrealized_pnl: '-5581.58753631389691173079221197'
                  - address: '0x2e4f2c311efbb8ab3adb9f7b7667af92e8a2af96'
                    as_of: 1783602083934
                    positions: 2
                    total_notional: '1789051.590600'
                    total_unrealized_pnl: '4691.6233452882009376598302290'
                  - address: '0xece7144d08695fee681496a5de501a0faa6c05ec'
                    as_of: 1783602083934
                    positions: 2
                    total_notional: '1785020.450360'
                    total_unrealized_pnl: '-13626.8974648418160300000000169'
                metric: size
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````