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

# Native observed trader leaderboard

> Ranks observed signer-flow estimates, not fee/transfer-aware wallet PnL. Native same-transaction round-trip signers are excluded; detection is partial. 30/90-day requests return 422 while only seven days are retained. md.read required. 120/min/IP plus API-key limit, two concurrent requests per IP per web process; service also enforces 30/min/IP, two per IP and 16 global reads.



## OpenAPI

````yaml https://www.oceanx.trade/api/v1/openapi.json get /api/v1/leaderboards/traders
openapi: 3.1.0
info:
  title: OceanX Developer API
  version: 1.0.0
  description: >-
    Public API for the OceanX trading platform. Currently in beta and free to
    use while in beta.


    This spec covers the **spot quote** domain. The wallet **tracker** and
    **perps** domains are documented at https://docs.oceanx.trade/api/overview
    and are not yet described here.
  contact:
    url: https://docs.oceanx.trade
  termsOfService: https://www.oceanx.trade/legal/terms
  license:
    name: Proprietary
    url: https://www.oceanx.trade/legal/terms
servers:
  - url: https://www.oceanx.trade
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Router
    description: >-
      Read-only Raptor route quotes and public Solana transaction status. Build
      and execution remain separately gated.
  - name: Market Data
    description: Read-only OceanX market context sourced and cached by VM producers.
  - name: Spot
    description: >-
      Executable Solana swap quotes off OceanX's own router, and the exit
      checker that reports whether a whole position can be sold.
  - name: Callouts
    description: >-
      Public token callouts — user-posted token calls with live click/volume
      attribution stats. Read-only.
  - name: Copy Trading
    description: Key-owner follow, fill and PnL reads; no execution authority.
  - name: Price Alerts
    description: Key-owner alert management through the existing evaluator; no webhooks.
paths:
  /api/v1/leaderboards/traders:
    get:
      tags:
        - Research
      summary: Native observed trader leaderboard
      description: >-
        Ranks observed signer-flow estimates, not fee/transfer-aware wallet PnL.
        Native same-transaction round-trip signers are excluded; detection is
        partial. 30/90-day requests return 422 while only seven days are
        retained. md.read required. 120/min/IP plus API-key limit, two
        concurrent requests per IP per web process; service also enforces
        30/min/IP, two per IP and 16 global reads.
      operationId: getNativeTraderLeaderboard
      parameters:
        - name: days
          in: query
          description: Selected window; never silently shortened.
          schema:
            type: integer
            enum:
              - 1
              - 7
              - 30
              - 90
            default: 1
        - name: limit
          in: query
          description: Page size.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 200
        - name: cursor
          in: query
          description: Native nextCursor from preceding page.
          schema:
            type: string
        - name: direction
          in: query
          description: Ordering.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: >-
            Native snapshot. All coverage and provenance fields remain in data;
            unknown values are null.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    additionalProperties: true
        '400':
          description: Invalid selectors.
        '401':
          description: Missing or invalid API key.
        '403':
          description: API-key policy or md.read scope forbids the request.
        '409':
          description: Snapshot/query mismatch; restart pagination.
        '422':
          description: Requested window is unavailable from native history.
        '429':
          description: Per-caller rate or concurrency limit; retry with backoff.
        '503':
          description: >-
            Native source, admission or verified KOL roster unavailable; no
            vendor fallback.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An OceanX API key, created in the app under Settings → Developer API.
        Send it as `Authorization: Bearer ox_live_…`. Required scopes are
        operation-specific: market reads use md.read, tracker uses tracker.read,
        copy reads use copy.read, and alert operations use alerts.read or
        alerts.write. New scopes require explicit selection and grant no trading
        authority. Existing perps operations retain their documented scopes.

````

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