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

# Perps Wallet List

<Tabs>
  <Tab title="Usage Note">
    <ul>
      <li>Returns ranked perp-trader wallets on Hyperliquid with performance and exposure metrics.</li>
      <li>Use this endpoint for wallet discovery, leaderboard views, and trader screening.</li>
      <li>This is a wallet ranking surface, not a transaction log or a single-wallet detail page.</li>
      <li>Follow with wallet overview or wallet open positions when you need a deeper read on one trader.</li>
    </ul>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>Hyperliquid</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>This endpoint consumes <code>10 CU</code> per request.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  * Build perp trader leaderboards based on equity, PnL, ROI, ROE, volume, or directional bias.
  * Discover high-conviction or high-performing wallets for deeper research.
  * Feed copy-trading research, trader intelligence, and leaderboard-style product experiences.
  * Screen for notable wallets before loading wallet-level open-position detail.
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  * Start here when you need a ranked universe of Hyperliquid perp wallets.
  * Apply supported sorting and filters to isolate the trader profile you care about.
  * Use the returned wallet address with `Perps Wallet Overview` or `Perps Wallet Open Positions`.
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  * Use ranked lists for discovery, then move to single-wallet endpoints for any serious interpretation.
  * Compare performance fields over consistent snapshots if you are building your own leaderboard history.
  * Avoid mixing spot-wallet metrics and perp-wallet metrics without explicit labeling.
</Accordion>


## OpenAPI

````yaml openapi/perps/openapi_perps_docs.json GET /perps/v1/wallet/list
openapi: 3.1.0
info:
  version: 1.1.0
  title: Perps Data API
  description: >-
    To utilize the Perps Data API, an API key is required for authentication.
    You can obtain an API key by signing up for a bds.birdeye.so account and
    generating an API key in your account settings. Include this API key in the
    headers of your API requests for authentication.


    Here's a step-by-step guide on how to obtain an API key: [Birdeye Data
    Authentication and API
    Keys](https://docs.birdeye.so/docs/authentication-api-keys)
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Perps - Token
  - name: Perps - Wallet
paths:
  /perps/v1/wallet/list:
    get:
      tags:
        - Perps - Wallet
      summary: Perps - Wallet List
      operationId: get-perps-v1-wallet-list
      parameters:
        - $ref: '#/components/parameters/xPerpParam'
        - $ref: '#/components/parameters/perpWalletListLastTradeDurationParam'
        - $ref: '#/components/parameters/perpWalletListSortByParam'
        - $ref: '#/components/parameters/sortTypeDescParam'
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limit20Default10Param'
      responses:
        '200':
          $ref: '#/components/responses/perpWalletListResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    xPerpParam:
      name: x-perp
      description: Specify the perpetuals exchange. Currently supports hyperliquid.
      in: header
      required: false
      schema:
        type: string
        enum:
          - hyperliquid
        default: hyperliquid
    perpWalletListLastTradeDurationParam:
      name: last_trade_duration
      in: query
      required: false
      schema:
        type: string
        enum:
          - 1d
          - 7d
          - 30d
          - 90d
          - all
        default: all
    perpWalletListSortByParam:
      name: sort_by
      in: query
      required: false
      schema:
        type: string
        enum:
          - perp_equity
          - long_value
          - short_value
          - unrealized_pnl
          - order_count
          - order_count_90d
          - win
          - win_90d
          - loss
          - loss_90d
          - volume_usd
          - volume_90d_usd
          - open_volume_usd
          - open_volume_90d_usd
          - realized_pnl
          - realized_pnl_90d
          - funding_fee
          - funding_fee_90d
          - first_trade
          - last_trade
          - win_rate
          - win_rate_90d
          - open_value
          - total_pnl
          - total_pnl_90d
          - roe
          - roi
          - roi_90d
          - bias
          - leverage
        default: total_pnl
    sortTypeDescParam:
      name: sort_type
      description: Specify the sort order.
      in: query
      schema:
        type: string
        enum:
          - desc
          - asc
        default: desc
    offsetParam:
      name: offset
      description: >-
        Specify the offset for pagination. Filter for records with offset
        greater than the specified offset value, including those with offset
        equal to the specified offset.
      in: query
      required: false
      schema:
        type: integer
        default: 0
    limit20Default10Param:
      name: limit
      description: Number of items per page.
      in: query
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 20
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    perpWalletListResponse:
      description: JSON object containing a list of wallets with certain fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PerpWalletListResponse'
          examples:
            WalletList:
              value:
                success: true
                data:
                  - wallet: '0x5b5d51203a0f9079f8aeb098a6523a13f298c060'
                    perp_equity: 4820256.661112
                    long_value: 7711796.4816
                    short_value: 27162652.130878
                    unrealized_pnl: 519753.636517
                    order_count: 528268
                    order_count_90d: 40946
                    win: 204298
                    win_90d: 18111
                    loss: 50566
                    loss_90d: 2810
                    volume_usd: 2877059275.010704
                    volume_90d_usd: 287016529.073075
                    open_volume_usd: 1317279026.67999
                    open_volume_90d_usd: 155549308.313184
                    realized_pnl: 171489764.775849
                    realized_pnl_90d: 9018515.858766
                    funding_fee: -1923466.812288
                    funding_fee_90d: -2530808.146744
                    first_trade: 1748185475
                    last_trade: 1778818326
                    open_value: 34874448.612478
                    total_pnl: 172009518.412366
                    total_pnl_90d: 9538269.495283
                    win_rate: 0.8015961453951912
                    win_rate_90d: 0.8656851966923187
                    roe: 0.11145774849176364
                    roi: 0.13018484413895512
                    roi_90d: 0.05797850184333872
                    bias: -4.035232357272615
                    leverage: 7.234977525954543
                    bias_text: Very Bearish
  schemas:
    PerpWalletListResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type: array
          description: Wallets ranked by the requested perp performance or activity metric.
          items:
            allOf:
              - type: object
                properties:
                  wallet:
                    type: string
                    description: Wallet address ranked in the list.
              - $ref: '#/components/schemas/PerpWalletOverviewObject'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    PerpWalletOverviewObject:
      type: object
      additionalProperties: true
      properties:
        perp_equity:
          type: number
          description: Current total perp equity for the wallet.
        long_value:
          type: number
          description: Total notional value of open long positions.
        short_value:
          type: number
          description: Total notional value of open short positions.
        unrealized_pnl:
          type: number
          description: Current unrealized profit and loss across open positions.
        order_count:
          type: integer
          description: Lifetime number of perp orders or fills tracked for the wallet.
        order_count_90d:
          type: integer
          description: Perp orders or fills recorded during the last 90 days.
        win:
          type: integer
          description: Lifetime number of profitable realized trades or position outcomes.
        win_90d:
          type: integer
          description: >-
            Profitable realized trades or position outcomes during the last 90
            days.
        loss:
          type: integer
          description: Lifetime number of losing realized trades or position outcomes.
        loss_90d:
          type: integer
          description: Losing realized trades or position outcomes during the last 90 days.
        volume_usd:
          type: number
          description: Lifetime perp trading volume in USD.
        volume_90d_usd:
          type: number
          description: Perp trading volume in USD during the last 90 days.
        open_volume_usd:
          type: number
          description: Lifetime USD notional value of currently open positions.
        open_volume_90d_usd:
          type: number
          description: USD notional value of positions opened during the last 90 days.
        realized_pnl:
          type: number
          description: Lifetime realized profit and loss in USD.
        realized_pnl_90d:
          type: number
          description: Realized profit and loss in USD during the last 90 days.
        funding_fee:
          type: number
          description: Lifetime net funding paid or received.
        funding_fee_90d:
          type: number
          description: Net funding paid or received during the last 90 days.
        first_trade:
          type: integer
          description: Unix timestamp in seconds of the wallet's first recorded perp trade.
        last_trade:
          type: integer
          description: >-
            Unix timestamp in seconds of the wallet's most recent recorded perp
            trade.
        open_value:
          type: number
          description: Current total notional value of all open positions.
        total_pnl:
          type: number
          description: Lifetime total PnL including realized and unrealized components.
        total_pnl_90d:
          type: number
          description: Total PnL during the last 90 days.
        win_rate:
          type: number
          description: Lifetime win rate across realized outcomes.
        win_rate_90d:
          type: number
          description: Win rate during the last 90 days.
        roe:
          type: number
          description: Aggregate return on equity for the wallet's perp activity.
        roi:
          type: number
          description: >-
            Aggregate return on invested capital across the wallet's perp
            activity.
        roi_90d:
          type: number
          description: Return on invested capital during the last 90 days.
        bias:
          type: number
          description: >-
            Net directional bias between long and short positioning. Positive
            values indicate long skew; negative values indicate short skew.
        bias_text:
          type: string
          description: Human-readable interpretation of the positioning bias.
        leverage:
          type: number
          description: Aggregate effective leverage across open positions.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````