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

# PnL leaderboard

> Wallets ranked by PnL or ROI over a window, for all assets or one asset category.



## OpenAPI

````yaml /data-api/openapi.json get /v1/leaderboards/pnl
openapi: 3.1.0
info:
  title: Hyperdash Data API
  version: v1
  description: >-
    Hyperliquid data from Hyperdash's own nodes and stored datasets; requests
    never call Hyperliquid's public API. Every response reports the credits it
    cost.
servers:
  - url: https://data.hyperdash.com
security: []
tags:
  - name: Accounts
  - name: Async jobs
  - name: Builders
  - name: Cohorts
  - name: HIP-3 dexes
  - name: Leaderboards
  - name: Lending
  - name: Liquidations
  - name: Markets
  - name: 'Markets: analytics'
  - name: 'Markets: funding'
  - name: 'Markets: liquidation and stop levels'
  - name: 'Markets: open interest and positioning'
  - name: 'Markets: order book'
  - name: 'Markets: prices and candles'
  - name: 'Markets: queue priority'
  - name: 'Markets: trades and flow'
  - name: 'Markets: TWAPs'
  - name: Network
  - name: Outcomes
  - name: Positions
  - name: Referrals
  - name: Snapshots
  - name: Spot
  - name: Staking
  - name: Traders
  - name: Vaults
paths:
  /v1/leaderboards/pnl:
    get:
      tags:
        - Leaderboards
      summary: PnL leaderboard
      description: >-
        Wallets ranked by PnL or ROI over a window, for all assets or one asset
        category. Each row has the realized and unrealized split, capital,
        volume, trades, and win and loss counts.


        **How ranking works**

        - `24h`, `7d`, `30d`, `ytd`: portfolio PnL, the change in account value
        net of transfers, with open positions included.

        - `alltime`: Hyperliquid's all-time PnL for category `all`, and
        completed-trade PnL for the other categories.


        **Limits**

        - One query returns at most your plan's wallet-list cap across its
        pages: Starter 100, Growth 500, Scale and Enterprise 1,000.

        - A query cut at the cap ends with `meta.truncated` set to `true`.


        **Notes**

        - This is the leaderboard shown on hyperdash.com.

        - `account_value` is the wallet's live perps equity, or the
        leaderboard's hourly snapshot when a live read is unavailable. It never
        affects rank.

        - For one wallet's row, use `GET /v1/accounts/{address}/leaderboard`.


        **Credits:** 400 per request + 5 per row + 5 per node read.


        **Scope:** `analytics:read`
      operationId: getPnlLeaderboard
      parameters:
        - name: window
          in: query
          required: false
          description: >-
            Ranking window. Defaults to `30d`, as on the hyperdash.com
            leaderboard.
          schema:
            type: string
            default: 30d
            enum:
              - alltime
              - 24h
              - 7d
              - 30d
              - ytd
        - name: category
          in: query
          required: false
          description: Asset category.
          schema:
            type: string
            default: all
            enum:
              - all
              - crypto
              - majors
              - memes
              - alts
              - equities
              - indices
              - commodities
              - fx
        - name: sort
          in: query
          required: false
          description: >-
            Ranked metric: `total` for net PnL, `realized`, `unrealized`, or
            their ROI. ROI is the PnL divided by capital, for wallets with
            capital of at least 1,000 USD. Wallets without that value are not
            ranked.
          schema:
            type: string
            default: total
            enum:
              - total
              - realized
              - unrealized
              - roi
              - realized_roi
              - unrealized_roi
        - name: min_trades
          in: query
          required: false
          description: Minimum completed trades.
          schema:
            type: integer
            minimum: 0
            maximum: 1000000
            default: 0
        - name: min_account_value
          in: query
          required: false
          description: >-
            Only wallets with at least this account value, in USD. This is the
            equity filter on hyperdash.com. It filters on the leaderboard's
            hourly account value, so the live value returned can differ
            slightly.
          schema:
            type: string
            enum:
              - '1000'
              - '10000'
              - '100000'
              - '1000000'
              - '10000000'
        - name: max_account_value
          in: query
          required: false
          description: >-
            Only wallets with at most this account value, in USD. Filtered on
            the leaderboard's hourly value, like `min_account_value`.
          schema:
            type: string
            enum:
              - '10000'
              - '100000'
              - '1000000'
              - '10000000'
              - '100000000'
        - name: limit
          in: query
          required: false
          description: Rows per page.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          required: false
          description: Opaque cursor from `next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            X-Credits-Charged:
              schema:
                type: integer
            X-Credit-Price-Version:
              schema:
                type: integer
            X-Request-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - has_more
                  - next_cursor
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        rank:
                          type: integer
                          description: Rank.
                        address:
                          type: string
                          description: Wallet.
                        display_name:
                          type:
                            - string
                            - 'null'
                          description: Display name.
                        tag:
                          type:
                            - string
                            - 'null'
                          description: Trader tag.
                        net_pnl:
                          type: string
                          description: Net PnL, in USD. Decimal string.
                        realized_pnl:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Realized PnL over the window, in USD, which is
                            closed PnL minus fees plus funding, partial closes
                            included. Decimal string.
                        unrealized_pnl:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Change in open-position unrealized PnL over the
                            window, in USD. For all time, the open unrealized
                            PnL now. Decimal string.
                        capital:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Capital, in USD, which is equity at the window start
                            plus peak net external inflow. Decimal string.
                        roi:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Net PnL divided by capital, as a ratio. `0.417`
                            means 41.7%. Decimal string.
                        realized_roi:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Realized PnL divided by capital, as a ratio. Decimal
                            string.
                        unrealized_roi:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Unrealized PnL divided by capital, as a ratio.
                            Decimal string.
                        gross_pnl:
                          type: string
                          description: >-
                            Gross PnL before fees and funding, in USD. For
                            `24h`, `7d`, `30d` or `ytd`, the price PnL including
                            open positions, which is `net_pnl` plus fees minus
                            funding. For all time, the completed-trade gross PnL
                            (closed round trips). Decimal string.
                        funding_pnl:
                          type: string
                          description: Funding PnL. Decimal string.
                        total_fees:
                          type: string
                          description: Fees. Decimal string.
                        volume:
                          type: string
                          description: Volume, in USD. Decimal string.
                        trades:
                          type: integer
                          description: Completed trades.
                        winning_trades:
                          type: integer
                          description: Winning trades.
                        losing_trades:
                          type: integer
                          description: Losing trades.
                        account_value:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Account value, in USD, as shown on the hyperdash.com
                            leaderboard: live perps equity, every perp dex's
                            account value summed. For unified accounts, their
                            collateral stablecoins (USDC, USDH, USDE, USDT0).
                            For portfolio-margin accounts, their signed spot
                            portfolio at mids, else the leaderboard's hourly
                            snapshot. See `account_value_source`. Decimal
                            string.
                        account_value_as_of:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            When the live value was read, in epoch milliseconds.
                            `null` for the snapshot value.
                        account_value_source:
                          type:
                            - string
                            - 'null'
                          description: >-
                            `live` when read within the last 5 seconds or
                            `snapshot` when the live read did not answer for
                            this wallet within 1.5 seconds.
                        last_trade_at:
                          type:
                            - integer
                            - 'null'
                          description: Last trade, in epoch milliseconds.
                        label:
                          type:
                            - string
                            - 'null'
                          description: Hyperdash label.
                        avatar:
                          type:
                            - string
                            - 'null'
                          description: Avatar image URL.
                        twitter:
                          type:
                            - string
                            - 'null'
                          description: X (Twitter) profile URL.
                        verified:
                          type:
                            - boolean
                            - 'null'
                          description: Verified profile.
                        copy_score:
                          type:
                            - string
                            - 'null'
                          description: Copy score, from 0 to 100. Decimal string.
                        mark_quality:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            Quality of the mark behind the unrealized part. `1`
                            means a live mark of every open position and `0`
                            means some fell back.
                        window_start:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            Leaderboard window start, in epoch milliseconds.
                            `null` for all time.
                        as_of:
                          type:
                            - integer
                            - 'null'
                          description: >-
                            When the leaderboard was computed, in epoch
                            milliseconds.
                    description: Result rows.
                  has_more:
                    type: boolean
                    description: '`true` when another page follows.'
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Cursor for the next page, passed as `cursor`. `null` on
                      the last page.
                  meta:
                    type: object
                    description: >-
                      Response metadata. Its keys depend on the endpoint and are
                      described above.
        '400':
          description: 'Invalid parameter (also: a request body that is not valid JSON)'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Invalid, expired or revoked key
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Scope, plan, history or credit limit
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Price version changed, or a cursor's snapshot expired
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: >-
            Rate limited (Retry-After; free): request rate, concurrent requests
            (a request counts one slot per 1,000 rows it can return), or this
            server busy with your workspace's requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream data source failed (free; retry later)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Backend at capacity or temporarily unavailable (Retry-After)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '504':
          description: Upstream data source timed out (free; retry later)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearer: []
      x-codeSamples:
        - lang: curl
          source: >-
            curl -H "Authorization: Bearer $HYPERDASH_API_KEY"
            'https://data.hyperdash.com/v1/leaderboards/pnl?window=7d'
components:
  schemas:
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - code
        - request_id
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        code:
          type: string
        detail:
          type: string
        hint:
          type: string
        request_id:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your API key, sent as `Bearer hdk_sk_live_v1_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.