> ## 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.

# Builder Trader P&L Leaderboard

> Rank every trader active through one builder by global wallet P&L, attributed volume, fills, trader-paid fees, active days, or recency.

This endpoint answers the most common Builder leaderboard question first: **which traders active through this Builder have the highest P\&L?** It ranks the Builder's eligible trader cohort without intersecting it with a global Top-N list. Each request returns at most 100 rows, and the supported ranking window is the first 500 ranks.

* `1d`, `7d`, and `30d` rank by **realized P\&L**.
* `all` ranks by **total P\&L** by default and also supports realized or unrealized P\&L.
* Existing builder-attributed volume, fills, trader-paid fees, active-day, and recency rankings remain available.

<Warning>
  P\&L is the trader wallet's global Polymarket P\&L, not P\&L attributed to the builder. The builder determines which wallets are in the cohort. Builder attribution is available for the activity columns, but order attribution alone cannot assign a wallet's eventual P\&L to one builder.
</Warning>

## Request

```http theme={null}
GET /v3/builders/{code}/leaderboard
```

### Path parameter

| Parameter | Type   | Description                                                                                                                                          |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`    | string | Builder code (with or without `0x`) or exact public Builder name. Hex digits, the prefix, and names are case-insensitive; names must be URL-encoded. |

### Query parameters

| Parameter    | Type               | Default  | Description                                                                                                                 |
| ------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `period`     | string             | `30d`    | `1d`, `7d`, `30d`, or `all`                                                                                                 |
| `sort`       | string             | `pnl`    | `pnl`, `realized_pnl`, `total_pnl`, `unrealized_pnl`, `volume`, `trades`, `fees`, `active_days`, or `recent`                |
| `order`      | string             | `desc`   | `asc` or `desc`                                                                                                             |
| `limit`      | integer            | `100`    | Rows per page, from 1 through 100                                                                                           |
| `offset`     | integer            | `0`      | Rank offset. `offset + limit` must not exceed 500. Five full 100-row pages use offsets `0`, `100`, `200`, `300`, and `400`. |
| `pagination` | string             | `offset` | `offset` for the historical contract, or `cursor` for repeat-free All-Time P\&L traversal                                   |
| `cursor`     | string             | --       | Opaque `next_cursor` or `previous_cursor` from a cursor response. Pass it unchanged.                                        |
| `as_of`      | RFC 3339 timestamp | --       | Builder-activity snapshot copied from the first page; required on cursor continuations                                      |
| `pnl_as_of`  | RFC 3339 timestamp | --       | P\&L snapshot copied from the first page; required on cursor continuations                                                  |

`sort=pnl` is the recommended stable default. It resolves to `realized_pnl` for `1d`, `7d`, and `30d`, and to `total_pnl` for `all`. The response reports the resolved sort. Dated windows reject `total_pnl` and `unrealized_pnl`; those marked values are only meaningful for All Time.

The canonical wire values are `1d`, `7d`, `30d`, and `all`. Period, sort, order, and pagination values are case-insensitive, so `30D`, `ALL`, `TOTAL_PNL`, and `CURSOR` are accepted and returned in canonical lowercase where a corresponding response field exists. `all-time` is not an alias for `all`. Treat cursor values and timestamps as opaque and pass them unchanged.

The builder cohort contains every wallet with attributed CLOB V2 maker-order activity in the selected builder window. Fixed builder-activity windows use inclusive UTC dates through `window.complete_through`. Dated P\&L is the canonical rolling realized-P\&L aggregate through `pnl_as_of`; All Time uses the canonical current total, realized, and unrealized wallet summary.

`coverage.complete` means every UTC date in the builder cohort window has a successfully built aggregate. P\&L data fails closed when its canonical aggregate is incomplete or stale. No partial ranking is returned as authoritative data.

Legacy offset pagination remains the default and its response body is unchanged. Retain every filter and add the number of returned rows to `offset`. Stop when `has_more` is `false`; it is always `false` after rank 500. Rankings use wallet address ascending as the tie-break, regardless of metric or direction.

For an All-Time `total_pnl`, `realized_pnl`, or `unrealized_pnl` walk, use `pagination=cursor`. The first request uses `offset=0` without a cursor. Every continuation must keep the same Builder, resolved period, sort, order, and limit; add the number of rows already returned to `offset`; and pass the preceding response's `next_cursor`, `as_of`, and `pnl_as_of`. This pins both snapshots and prevents a wallet already returned in that traversal from appearing again. It does not change any P\&L value, ranking formula, or tie-break.

See [Authentication](/authentication) for key creation and [Rate Limits](/guides/rate-limits) for plan availability and current request limits.

## P\&L-first example

The example uses BetMoar's public builder code.

```bash theme={null}
curl -H "x-api-key: pn_live_YOUR_KEY" \
  "https://api.polynode.dev/v3/builders/0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1/leaderboard?period=30d&sort=pnl&limit=1"
```

```json theme={null}
{
  "builder_code": "0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1",
  "builder_name": "BetMoar",
  "builder_logo": "https://example.com/builder.png",
  "builder_verified": true,
  "period": "30d",
  "sort": "realized_pnl",
  "order": "desc",
  "limit": 1,
  "offset": 0,
  "has_more": true,
  "cohort_wallet_count": 2101,
  "eligible_wallet_count": 2101,
  "window": {
    "start_date": "2026-08-01",
    "end_date": "2026-08-30",
    "complete_through": "2026-08-30"
  },
  "coverage": {
    "start_date": "2026-04-03",
    "end_date": "2026-08-30",
    "complete": true
  },
  "as_of": "2026-08-30T08:12:17.000000Z",
  "pnl_as_of": "2026-08-30T08:00:00.000000Z",
  "pnl_scope": "wallet_global_polymarket_not_builder_attributed",
  "pnl_semantics": "Global Polymarket wallet PnL for traders active through this builder in the selected window. PnL is not attributed to the builder.",
  "volume_scope": "clob_v2_onchain",
  "volume_semantics": "outcome_share_par_notional",
  "fee_semantics": "Trader-paid fees on builder-attributed maker orders. These are not builder rebates.",
  "data": [
    {
      "rank": 1,
      "wallet": "0x1111111111111111111111111111111111111111",
      "trader_address": "0x1111111111111111111111111111111111111111",
      "realized_pnl": "184250.75",
      "unrealized_pnl": null,
      "total_pnl": null,
      "volume_e6": "248501250000",
      "volume": "248501.25",
      "buy_volume_e6": "148500000000",
      "buy_volume": "148500",
      "sell_volume_e6": "100001250000",
      "sell_volume": "100001.25",
      "trades": 821,
      "trader_paid_fees_e6": "184200000",
      "trader_paid_fees": "184.2",
      "active_days": 24,
      "first_activity_at": 1785579462,
      "last_activity_at": 1788043265
    }
  ]
}
```

For a dated P\&L ranking, `realized_pnl` is always a decimal string and `total_pnl` / `unrealized_pnl` are `null`. For All Time, all three P\&L fields are decimal strings.

## Walk five All-Time pages without repeats

This loop prints as many as 500 rows in pages of 100. It stops earlier when the Builder has fewer eligible traders. If the API returns HTTP `409` because either snapshot advanced, discard the traversal and restart at offset `0`.

```bash theme={null}
BUILDER="BetMoar"
BASE_URL="https://api.polynode.dev/v3/builders/${BUILDER}/leaderboard"
offset=0
cursor=""
as_of=""
pnl_as_of=""

while [ "$offset" -lt 500 ]; do
  args=(
    --data-urlencode "period=all"
    --data-urlencode "sort=total_pnl"
    --data-urlencode "order=desc"
    --data-urlencode "limit=100"
    --data-urlencode "offset=${offset}"
    --data-urlencode "pagination=cursor"
  )
  if [ "$offset" -gt 0 ]; then
    args+=(
      --data-urlencode "cursor=${cursor}"
      --data-urlencode "as_of=${as_of}"
      --data-urlencode "pnl_as_of=${pnl_as_of}"
    )
  fi

  page=$(curl -fsS -G -H "x-api-key: $POLYNODE_API_KEY" \
    "${args[@]}" "$BASE_URL") || exit 1
  jq -c '.data[]' <<<"$page"

  rows=$(jq -r '.data | length' <<<"$page")
  [ "$(jq -r '.has_more' <<<"$page")" = "true" ] || break
  cursor=$(jq -r '.next_cursor // empty' <<<"$page")
  [ "$rows" -gt 0 ] && [ -n "$cursor" ] || exit 1
  as_of=$(jq -r '.as_of' <<<"$page")
  pnl_as_of=$(jq -r '.pnl_as_of' <<<"$page")
  offset=$((offset + rows))
done
```

## Common queries

```bash theme={null}
BUILDER_CODE="0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1"
BASE_URL="https://api.polynode.dev/v3/builders/${BUILDER_CODE}/leaderboard"

# Recommended defaults: 30-day realized P&L
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}"

# 1-day realized P&L
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=1d&sort=pnl"

# 7-day realized P&L
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=7d&sort=realized_pnl"

# All-Time total, realized, and unrealized P&L rankings
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=all&sort=total_pnl"
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=all&sort=realized_pnl"
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=all&sort=unrealized_pnl"

# Existing builder-attributed activity rankings
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=30d&sort=volume"
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=30d&sort=trades"
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=all&sort=fees"

# Second 100-row page of the same ranking
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=30d&sort=pnl&limit=100&offset=100"

# Fifth and final supported 100-row page
curl -H "x-api-key: pn_live_YOUR_KEY" "${BASE_URL}?period=30d&sort=pnl&limit=100&offset=400"

# An exact public name also resolves directly
curl -H "x-api-key: pn_live_YOUR_KEY" \
  "https://api.polynode.dev/v3/builders/BetMoar/leaderboard?period=30d&sort=pnl&limit=100"
```

## Response fields

| Field                                                   | Type                    | Description                                                                                                                                                                               |
| ------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `builder_code`                                          | string                  | Normalized builder code                                                                                                                                                                   |
| `builder_name`, `builder_logo`, `builder_verified`      | string / boolean / null | Public builder identity when available                                                                                                                                                    |
| `period`                                                | string                  | Resolved cohort and P\&L window                                                                                                                                                           |
| `sort`                                                  | string                  | Resolved sort; `pnl` is returned as `realized_pnl` or `total_pnl`                                                                                                                         |
| `order`                                                 | string                  | Resolved sort direction                                                                                                                                                                   |
| `limit`, `offset`, `has_more`                           | integer / boolean       | Bounded pagination state inside the supported first 500 ranks                                                                                                                             |
| `pagination`                                            | string                  | `cursor` on opt-in cursor responses; omitted from legacy offset responses                                                                                                                 |
| `previous_cursor`, `next_cursor`                        | string \| null          | Opaque traversal tokens on cursor responses. The first page has no previous cursor; the last page has no next cursor.                                                                     |
| `cohort_wallet_count`                                   | integer                 | Distinct wallets active through this builder in the selected window; returned for P\&L sorts                                                                                              |
| `eligible_wallet_count`                                 | integer                 | Wallets eligible for the requested P\&L ranking; dated realized-P\&L cohorts include explicit zeroes, while All Time excludes wallets whose canonical current basis or mark is incomplete |
| `window`                                                | object                  | Inclusive UTC dates used to construct the builder-attributed wallet cohort                                                                                                                |
| `coverage`                                              | object                  | Full retained builder-activity extent and selected-window completeness                                                                                                                    |
| `as_of`                                                 | string                  | Completion timestamp of the latest builder-activity aggregate                                                                                                                             |
| `pnl_as_of`                                             | string                  | Canonical P\&L snapshot timestamp; returned for P\&L sorts                                                                                                                                |
| `pnl_scope`                                             | string                  | `wallet_global_polymarket_not_builder_attributed` for P\&L sorts; `not_applicable_builder_attributed_activity_only` for activity sorts                                                    |
| `pnl_semantics`                                         | string                  | Explicit reminder that P\&L is global wallet P\&L, not builder-attributed P\&L; returned for P\&L sorts                                                                                   |
| `volume_scope`                                          | string                  | Always `clob_v2_onchain`                                                                                                                                                                  |
| `volume_semantics`                                      | string                  | Always `outcome_share_par_notional`; one full outcome share represents \$1 of par notional                                                                                                |
| `fee_semantics`                                         | string                  | Trader-paid fees on attributed maker orders, not builder rebates or revenue                                                                                                               |
| `data[].rank`                                           | integer                 | Rank after the requested metric and ascending wallet-address tie-break                                                                                                                    |
| `data[].wallet`, `data[].trader_address`                | string                  | Same normalized trader wallet address                                                                                                                                                     |
| `data[].realized_pnl`                                   | string                  | Global wallet realized P\&L for the requested period; returned for P\&L sorts                                                                                                             |
| `data[].unrealized_pnl`                                 | string \| null          | Global wallet current unrealized P\&L for All Time; `null` for dated P\&L                                                                                                                 |
| `data[].total_pnl`                                      | string \| null          | Global wallet current total P\&L for All Time; `null` for dated P\&L                                                                                                                      |
| `data[].volume_e6`, `data[].volume`                     | string                  | Builder-attributed outcome-share par notional in raw 6-decimal and decimal units                                                                                                          |
| `data[].buy_volume_e6`, `data[].sell_volume_e6`         | string                  | Raw 6-decimal signed-order-side attributed volume                                                                                                                                         |
| `data[].buy_volume`, `data[].sell_volume`               | string                  | Decimal signed-order-side attributed volume                                                                                                                                               |
| `data[].trades`                                         | integer                 | Builder-attributed maker-order fills in the cohort window                                                                                                                                 |
| `data[].trader_paid_fees_e6`, `data[].trader_paid_fees` | string                  | Trader-paid fees in raw six-decimal and decimal USDC units                                                                                                                                |
| `data[].active_days`                                    | integer                 | UTC dates with at least one attributed fill in the cohort window                                                                                                                          |
| `data[].first_activity_at`, `data[].last_activity_at`   | integer                 | First and last attributed fill times in Unix seconds                                                                                                                                      |

## Errors

| Status | Error                                                                                                                                                                                    | Meaning                                                                                                                         |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_builder`, `invalid_period`, `invalid_sort`, `invalid_order`, `invalid_limit`, `invalid_offset`, `invalid_pagination`, `invalid_cursor`, `invalid_as_of`, or `invalid_pnl_as_of` | A path or query value is invalid, a cursor continuation changed its bound inputs, or the requested page extends beyond rank 500 |
| `401`  | authentication error                                                                                                                                                                     | The API key is missing or invalid                                                                                               |
| `402`  | payment required                                                                                                                                                                         | The key's plan does not include paid V3 REST data                                                                               |
| `404`  | `builder_not_found`                                                                                                                                                                      | The normalized builder has no metadata or indexed activity                                                                      |
| `409`  | `ambiguous_builder_name` or `builder_trader_leaderboard_snapshot_changed`                                                                                                                | Use a code for an ambiguous name, or restart a traversal at offset `0` when a pinned snapshot advances                          |
| `429`  | rate limit exceeded                                                                                                                                                                      | The account's shared V3 REST request limit was exceeded                                                                         |
| `503`  | `builder_trader_leaderboard_unavailable`                                                                                                                                                 | Required builder activity or P\&L data is incomplete, stale, or unavailable; no partial ranking is returned                     |

## Related endpoints

| Endpoint                                                                  | Description                                                    |
| ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`GET /v3/builders`](/data/builders/list)                                 | Rank all builders by attributed activity                       |
| [`GET /v3/builders/{code}`](/data/builders/detail)                        | Inspect one builder's profile and totals                       |
| [`GET /v3/builders/{code}/activity/daily`](/data/builders/daily-activity) | Inspect daily activity and recent composition for this Builder |
| [`GET /v3/builders/{code}/trades`](/data/builders/trades)                 | Paginate the underlying builder-attributed fills               |


## OpenAPI

````yaml GET /v3/builders/{code}/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/builders/{code}/leaderboard:
    get:
      tags:
        - V3 Builders
      summary: Builder trader P&L leaderboard
      description: >-
        Rank eligible wallets active through one Builder inside the supported
        first-500-rank window. P&L is first-class: dated windows expose global
        wallet realized P&L and All Time exposes total, realized, and unrealized
        P&L. P&L is global Polymarket wallet P&L and is not attributed to the
        Builder. Existing Builder-attributed volume, fills, fees, active-day,
        and recency sorts remain available. Legacy offset pagination remains the
        default; opt-in cursor pagination prevents repeated wallet identities
        during one pinned All-Time P&L traversal.
      operationId: v3_builder_trader_leaderboard
      parameters:
        - name: code
          in: path
          required: true
          description: >-
            Builder code with or without 0x, or an exact public Builder name.
            Hex digits, the optional prefix, and names are case-insensitive;
            names must be URL-encoded.
          schema:
            type: string
            minLength: 1
            maxLength: 180
          example: '0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1'
        - name: period
          in: query
          required: false
          description: >-
            Case-insensitive ranking window. Fixed windows end on the latest
            materialized UTC date; all begins at the first retained date.
            Responses use canonical lowercase.
          schema:
            type: string
            enum:
              - 1d
              - 7d
              - 30d
              - all
            default: 30d
        - name: sort
          in: query
          required: false
          description: >-
            Case-insensitive ranking metric. pnl resolves to realized_pnl for
            dated periods and total_pnl for All Time. total_pnl and
            unrealized_pnl are All-Time-only. recent maps to last_activity_at.
          schema:
            type: string
            enum:
              - pnl
              - realized_pnl
              - total_pnl
              - unrealized_pnl
              - volume
              - trades
              - fees
              - active_days
              - recent
            default: pnl
        - name: order
          in: query
          required: false
          description: Case-insensitive sort direction. Responses use canonical lowercase.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: offset
          in: query
          required: false
          description: >-
            Rank offset. offset + limit must not exceed 500; five full pages use
            0, 100, 200, 300, and 400.
          schema:
            type: integer
            minimum: 0
            maximum: 499
            default: 0
        - name: pagination
          in: query
          required: false
          description: >-
            Case-insensitive pagination mode. offset preserves the historical
            contract. cursor is available for All-Time P&L sorts and prevents a
            wallet already returned in the same pinned traversal from appearing
            again.
          schema:
            type: string
            enum:
              - offset
              - cursor
            default: offset
        - name: cursor
          in: query
          required: false
          description: >-
            Opaque next_cursor or previous_cursor from a cursor response. Pass
            it unchanged with the same Builder, period, sort, order, limit,
            as_of, and pnl_as_of. Omit it on the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 8192
        - name: as_of
          in: query
          required: false
          description: >-
            Builder-activity snapshot copied from the first page. Required on
            cursor continuations; a changed snapshot returns HTTP 409.
          schema:
            type: string
            format: date-time
            maxLength: 80
        - name: pnl_as_of
          in: query
          required: false
          description: >-
            P&L snapshot copied from the first page. Required on cursor
            continuations and valid only for P&L sorts; a changed snapshot
            returns HTTP 409.
          schema:
            type: string
            format: date-time
            maxLength: 80
      responses:
        '200':
          description: >-
            A complete P&L or builder-attributed activity ranking, current
            through the returned as_of and optional pnl_as_of timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3BuilderTraderLeaderboardResponse'
              example:
                builder_code: >-
                  0xceebf77a833b30520287ddd9478ff51abbdffa30aa90a8d655dba0e8a79ce0c1
                builder_name: BetMoar
                builder_logo: null
                builder_verified: true
                period: 30d
                sort: realized_pnl
                order: desc
                limit: 100
                offset: 0
                has_more: true
                cohort_wallet_count: 803
                eligible_wallet_count: 803
                window:
                  start_date: '2026-08-02'
                  end_date: '2026-08-31'
                  complete_through: '2026-08-31'
                coverage:
                  start_date: '2026-04-03'
                  end_date: '2026-08-31'
                  complete: true
                as_of: '2026-09-01T02:10:00Z'
                pnl_as_of: '2026-09-01T02:00:00Z'
                pnl_scope: wallet_global_polymarket_not_builder_attributed
                pnl_semantics: >-
                  Global Polymarket wallet PnL for traders active through this
                  builder in the selected window. PnL is not attributed to the
                  builder.
                volume_scope: clob_v2_onchain
                volume_semantics: outcome_share_par_notional
                fee_semantics: >-
                  Trader-paid fees on builder-attributed maker orders. These are
                  not builder rebates.
                data:
                  - rank: 1
                    wallet: '0x1111111111111111111111111111111111111111'
                    trader_address: '0x1111111111111111111111111111111111111111'
                    realized_pnl: '184250.75'
                    unrealized_pnl: null
                    total_pnl: null
                    volume_e6: '248501250000'
                    volume: '248501.25'
                    buy_volume_e6: '148500000000'
                    buy_volume: '148500'
                    sell_volume_e6: '100001250000'
                    sell_volume: '100001.25'
                    trades: 821
                    trader_paid_fees_e6: '184200000'
                    trader_paid_fees: '184.2'
                    active_days: 24
                    first_activity_at: 1785579462
                    last_activity_at: 1788043265
        '400':
          description: Invalid builder code or query value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3BuilderTraderLeaderboardBadRequest'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: The API key's plan does not include paid V3 REST data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The normalized builder has no metadata or indexed activity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3BuilderTraderLeaderboardNotFound'
        '409':
          description: >-
            The public name is ambiguous, or a pinned Builder-activity/P&L
            snapshot advanced. Use a Builder code for the former; restart cursor
            traversal at offset 0 for the latter.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/V3BuilderNameAmbiguous'
                  - $ref: >-
                      #/components/schemas/V3BuilderTraderLeaderboardSnapshotChanged
        '429':
          description: The account's shared V3 REST request limit was exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Required builder activity or P&L data is incomplete, stale, or
            unavailable; no partial ranking is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3BuilderTraderLeaderboardUnavailable'
      security:
        - api_key: []
components:
  schemas:
    V3BuilderTraderLeaderboardResponse:
      type: object
      additionalProperties: false
      required:
        - builder_code
        - builder_name
        - builder_logo
        - builder_verified
        - period
        - sort
        - order
        - limit
        - offset
        - has_more
        - window
        - coverage
        - as_of
        - volume_scope
        - volume_semantics
        - fee_semantics
        - pnl_scope
        - data
      properties:
        builder_code:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
        builder_name:
          type:
            - string
            - 'null'
        builder_logo:
          type:
            - string
            - 'null'
          format: uri
        builder_verified:
          type:
            - boolean
            - 'null'
        period:
          type: string
          enum:
            - 1d
            - 7d
            - 30d
            - all
        sort:
          type: string
          enum:
            - realized_pnl
            - total_pnl
            - unrealized_pnl
            - volume
            - trades
            - fees
            - active_days
            - recent
          description: >-
            Resolved sort. A request for pnl is returned as realized_pnl or
            total_pnl.
        order:
          type: string
          enum:
            - asc
            - desc
        limit:
          type: integer
          minimum: 1
          maximum: 100
        offset:
          type: integer
          minimum: 0
          maximum: 499
        has_more:
          type: boolean
          description: >-
            True only when another page exists inside the supported
            first-500-rank window.
        pagination:
          type: string
          enum:
            - cursor
          description: >-
            Present only for opt-in cursor responses. Legacy offset responses
            omit this field.
        previous_cursor:
          type:
            - string
            - 'null'
          maxLength: 8192
          description: >-
            Opaque cursor for the preceding page. Null on the first and second
            pages because offset 0 requires no cursor; omitted from legacy
            offset responses.
        next_cursor:
          type:
            - string
            - 'null'
          maxLength: 8192
          description: >-
            Opaque cursor for the next page, or null at the end of the supported
            traversal. Omitted from legacy offset responses.
        window:
          $ref: '#/components/schemas/V3BuilderTraderLeaderboardWindow'
        coverage:
          $ref: '#/components/schemas/V3BuilderTraderLeaderboardCoverage'
        as_of:
          type: string
          format: date-time
          description: Completion timestamp of the newest contributing aggregate snapshot.
        cohort_wallet_count:
          type: integer
          minimum: 0
          maximum: 100000
          description: >-
            Complete distinct builder-active wallet cohort. Present for P&L
            sorts.
        eligible_wallet_count:
          type: integer
          minimum: 0
          maximum: 100000
          description: >-
            Wallets eligible for the requested P&L ranking. Present for P&L
            sorts.
        pnl_as_of:
          type: string
          format: date-time
          description: Canonical P&L snapshot timestamp. Present for P&L sorts.
        volume_scope:
          type: string
          enum:
            - clob_v2_onchain
        volume_semantics:
          type: string
          enum:
            - outcome_share_par_notional
          description: One full outcome share represents $1 of par notional.
        fee_semantics:
          type: string
          description: >-
            Trader-paid USDC fees attributed to maker orders; not builder
            rebates, revenue, or P&L.
        pnl_scope:
          type: string
          enum:
            - wallet_global_polymarket_not_builder_attributed
            - not_applicable_builder_attributed_activity_only
        pnl_semantics:
          type: string
          description: >-
            Explains that P&L is global wallet P&L and is not attributed to the
            builder. Present for P&L sorts.
        data:
          type: array
          items:
            $ref: '#/components/schemas/V3BuilderTraderLeaderboardRow'
    V3BuilderTraderLeaderboardBadRequest:
      type: object
      additionalProperties: false
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - invalid_builder
            - invalid_period
            - invalid_sort
            - invalid_order
            - invalid_limit
            - invalid_offset
            - invalid_pagination
            - invalid_cursor
            - invalid_as_of
            - invalid_pnl_as_of
        message:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    V3BuilderTraderLeaderboardNotFound:
      type: object
      additionalProperties: false
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - builder_not_found
        message:
          type: string
          enum:
            - The requested builder was not found.
    V3BuilderNameAmbiguous:
      type: object
      additionalProperties: false
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - ambiguous_builder_name
        message:
          type: string
          enum:
            - >-
              More than one builder uses that name. Use the builder code
              instead.
    V3BuilderTraderLeaderboardSnapshotChanged:
      type: object
      additionalProperties: false
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - builder_trader_leaderboard_snapshot_changed
        message:
          type: string
          description: >-
            Restart at offset 0 and use the new as_of, pnl_as_of, and cursor
            values.
    V3BuilderTraderLeaderboardUnavailable:
      type: object
      additionalProperties: false
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - builder_trader_leaderboard_unavailable
            - builder_lookup_unavailable
        message:
          type: string
    V3BuilderTraderLeaderboardWindow:
      type: object
      additionalProperties: false
      required:
        - start_date
        - end_date
        - complete_through
      properties:
        start_date:
          type: string
          format: date
          description: First inclusive UTC date in the ranking window.
        end_date:
          type: string
          format: date
          description: >-
            Last inclusive UTC date in the ranking window; it can be the current
            UTC date.
        complete_through:
          type: string
          format: date
          description: >-
            Latest contiguous materialized UTC date included in the window. A
            current-day bucket is a snapshot through as_of.
    V3BuilderTraderLeaderboardCoverage:
      type: object
      additionalProperties: false
      required:
        - start_date
        - end_date
        - complete
      properties:
        start_date:
          type: string
          format: date
          description: First retained UTC date.
        end_date:
          type: string
          format: date
          description: Latest retained UTC date.
        complete:
          type: boolean
          description: >-
            True when every UTC date in the selected window has a successfully
            materialized aggregate row.
    V3BuilderTraderLeaderboardRow:
      type: object
      additionalProperties: false
      required:
        - rank
        - wallet
        - trader_address
        - volume_e6
        - volume
        - buy_volume_e6
        - buy_volume
        - sell_volume_e6
        - sell_volume
        - trades
        - trader_paid_fees_e6
        - trader_paid_fees
        - active_days
        - first_activity_at
        - last_activity_at
      properties:
        rank:
          type: integer
          minimum: 1
          maximum: 500
          description: >-
            Rank after the requested metric and direction, with wallet address
            ascending as the deterministic tie-break.
        wallet:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        trader_address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        realized_pnl:
          $ref: '#/components/schemas/V3SignedDecimalString'
          description: >-
            Global wallet realized P&L. Present for P&L sorts and omitted for
            activity-only sorts.
        unrealized_pnl:
          description: >-
            Global wallet current unrealized P&L for All Time, null for dated
            P&L, or omitted for activity-only sorts.
          anyOf:
            - $ref: '#/components/schemas/V3SignedDecimalString'
            - type: 'null'
        total_pnl:
          description: >-
            Global wallet current total P&L for All Time, null for dated P&L, or
            omitted for activity-only sorts.
          anyOf:
            - $ref: '#/components/schemas/V3SignedDecimalString'
            - type: 'null'
        volume_e6:
          $ref: '#/components/schemas/V3UnsignedIntegerString'
        volume:
          $ref: '#/components/schemas/V3NonNegativeDecimalString'
        buy_volume_e6:
          $ref: '#/components/schemas/V3UnsignedIntegerString'
        buy_volume:
          $ref: '#/components/schemas/V3NonNegativeDecimalString'
        sell_volume_e6:
          $ref: '#/components/schemas/V3UnsignedIntegerString'
        sell_volume:
          $ref: '#/components/schemas/V3NonNegativeDecimalString'
        trades:
          type: integer
          minimum: 0
        trader_paid_fees_e6:
          allOf:
            - $ref: '#/components/schemas/V3UnsignedIntegerString'
          description: Exact trader-paid fees in raw six-decimal USDC units.
        trader_paid_fees:
          allOf:
            - $ref: '#/components/schemas/V3NonNegativeDecimalString'
          description: Decimal trader-paid fees in USDC; not builder rebates or revenue.
        active_days:
          type: integer
          minimum: 0
        first_activity_at:
          type: integer
          format: int64
          minimum: 0
          description: Exact first attributed fill time in Unix seconds.
        last_activity_at:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Exact last attributed fill time in Unix seconds; used by
            sort=recent.
    V3SignedDecimalString:
      type: string
      pattern: ^-?[0-9]+(?:[.][0-9]+)?$
      description: An exact signed decimal encoded as a string.
    V3UnsignedIntegerString:
      type: string
      pattern: ^[0-9]+$
      description: An exact non-negative integer encoded as a string.
    V3NonNegativeDecimalString:
      type: string
      pattern: ^[0-9]+(?:[.][0-9]+)?$
      description: An exact non-negative decimal encoded as a string.
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key

````