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

# Trader leaderboard

> Users of this app ranked by realizedPnl (default) or volume over an inclusive UTC day range; omit from/to for all time. rank is exact within the top 100 and null beyond. Identity fields follow the app's leaderboardIdentity setting. Pass exactly one of userId, externalId, username or walletAddress to look up a single user. realizedPnl is gross, position-level realized P&L in USD: sell proceeds against the position's average entry, plus settlement payout against entry, attributed to the order's creation day (sells) or the settlement day. It excludes venue and app fees. Positions with an unknown cost basis (imported inventory) contribute 0. History: volume and order counts are complete; P&L is complete from the deploy date, and earlier settled positions carry their lifetime P&L on their redemption day. Data refreshes every 5 minutes.



## OpenAPI

````yaml /openapi/openapi.json get /leaderboard
openapi: 3.0.2
info:
  title: AGG API
  version: 1.0.0
  description: >-
    Prediction market aggregator REST API — authentication, users, venue events,
    venue markets, orderbooks, charts, and execution workflows.
servers:
  - url: https://api.agg.market
    description: Production
  - url: https://api.staging.agg.market
    description: Staging
security: []
paths:
  /leaderboard:
    get:
      tags:
        - Leaderboard
      summary: Trader leaderboard
      description: >-
        Users of this app ranked by realizedPnl (default) or volume over an
        inclusive UTC day range; omit from/to for all time. rank is exact within
        the top 100 and null beyond. Identity fields follow the app's
        leaderboardIdentity setting. Pass exactly one of userId, externalId,
        username or walletAddress to look up a single user. realizedPnl is
        gross, position-level realized P&L in USD: sell proceeds against the
        position's average entry, plus settlement payout against entry,
        attributed to the order's creation day (sells) or the settlement day. It
        excludes venue and app fees. Positions with an unknown cost basis
        (imported inventory) contribute 0. History: volume and order counts are
        complete; P&L is complete from the deploy date, and earlier settled
        positions carry their lifetime P&L on their redemption day. Data
        refreshes every 5 minutes.
      operationId: getLeaderboard
      parameters:
        - name: from
          in: query
          required: false
          schema:
            pattern: ^\d{4}-\d{2}-\d{2}$
            description: UTC calendar day, inclusive
            type: string
        - name: to
          in: query
          required: false
          schema:
            pattern: ^\d{4}-\d{2}-\d{2}$
            description: UTC calendar day, inclusive
            type: string
        - name: metric
          in: query
          required: false
          schema:
            type: string
            enum:
              - realizedPnl
              - volume
        - name: limit
          in: query
          required: false
          schema:
            minimum: 1
            maximum: 100
            type: integer
        - name: cursor
          in: query
          required: false
          schema:
            maxLength: 200
            type: string
        - name: userId
          in: query
          required: false
          schema:
            minLength: 1
            type: string
        - name: externalId
          in: query
          required: false
          schema:
            minLength: 1
            type: string
        - name: username
          in: query
          required: false
          schema:
            minLength: 1
            type: string
        - name: walletAddress
          in: query
          required: false
          schema:
            minLength: 1
            type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - nextCursor
                  - hasMore
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                        - rank
                        - userId
                        - username
                        - avatarUrl
                        - walletAddress
                        - orders
                        - volume
                        - spent
                        - realizedPnl
                      properties:
                        rank:
                          minimum: 1
                          maximum: 100
                          type: integer
                          nullable: true
                        userId:
                          type: string
                        username:
                          type: string
                          nullable: true
                        avatarUrl:
                          type: string
                          nullable: true
                        walletAddress:
                          type: string
                          nullable: true
                        orders:
                          type: integer
                        volume:
                          type: number
                        spent:
                          type: number
                        realizedPnl:
                          type: number
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '429':
          description: '429'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                  statusCode:
                    type: number
                    enum:
                      - 429
                  code:
                    type: string
                    enum:
                      - rate_limited
                  retryAfter:
                    minimum: 1
                    description: Retry delay in seconds.
                    type: integer
          headers:
            Retry-After:
              schema:
                pattern: ^[1-9][0-9]*$
                description: Seconds to wait before another request; do not retry earlier.
                type: string
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
      security:
        - appId: []
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-app-id
      description: Your application ID. Required for all app-tier and user-tier routes.

````