Skip to main content
GET
Builder trader P&L leaderboard
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.
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.

​
Request

​
Path parameter

​
Query parameters

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 for key creation and Rate Limits for plan availability and current request limits.

​
P&L-first example

The example uses BetMoar’s public builder code.
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.

​
Common queries

​
Response fields

​
Errors

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
code
string
required

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.

Required string length: 1 - 180

Query Parameters

​
period
enum<string>
default:30d

Case-insensitive ranking window. Fixed windows end on the latest materialized UTC date; all begins at the first retained date. Responses use canonical lowercase.

Available options:
1d,
7d,
30d,
all
​
sort
enum<string>
default:pnl

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.

Available options:
pnl,
realized_pnl,
total_pnl,
unrealized_pnl,
volume,
trades,
fees,
active_days,
recent
​
order
enum<string>
default:desc

Case-insensitive sort direction. Responses use canonical lowercase.

Available options:
asc,
desc
​
limit
integer
default:100
Required range: 1 <= x <= 100
​
offset
integer
default:0

Rank offset. offset + limit must not exceed 500; five full pages use 0, 100, 200, 300, and 400.

Required range: 0 <= x <= 499
​
pagination
enum<string>
default:offset

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.

Available options:
offset,
cursor
​
cursor
string

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.

Required string length: 1 - 8192
​
as_of
string<date-time>

Builder-activity snapshot copied from the first page. Required on cursor continuations; a changed snapshot returns HTTP 409.

Maximum string length: 80
​
pnl_as_of
string<date-time>

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.

Maximum string length: 80

Response

A complete P&L or builder-attributed activity ranking, current through the returned as_of and optional pnl_as_of timestamps.

​
builder_code
string
required
Pattern: ^0x[a-fA-F0-9]{64}$
​
builder_name
string | null
required
​
builder_logo
string<uri> | null
required
​
builder_verified
boolean | null
required
​
period
enum<string>
required
Available options:
1d,
7d,
30d,
all
​
sort
enum<string>
required

Resolved sort. A request for pnl is returned as realized_pnl or total_pnl.

Available options:
realized_pnl,
total_pnl,
unrealized_pnl,
volume,
trades,
fees,
active_days,
recent
​
order
enum<string>
required
Available options:
asc,
desc
​
limit
integer
required
Required range: 1 <= x <= 100
​
offset
integer
required
Required range: 0 <= x <= 499
​
has_more
boolean
required

True only when another page exists inside the supported first-500-rank window.

​
window
object
required
​
coverage
object
required
​
as_of
string<date-time>
required

Completion timestamp of the newest contributing aggregate snapshot.

​
volume_scope
enum<string>
required
Available options:
clob_v2_onchain
​
volume_semantics
enum<string>
required

One full outcome share represents $1 of par notional.

Available options:
outcome_share_par_notional
​
fee_semantics
string
required

Trader-paid USDC fees attributed to maker orders; not builder rebates, revenue, or P&L.

​
pnl_scope
enum<string>
required
Available options:
wallet_global_polymarket_not_builder_attributed,
not_applicable_builder_attributed_activity_only
​
data
object[]
required
​
pagination
enum<string>

Present only for opt-in cursor responses. Legacy offset responses omit this field.

Available options:
cursor
​
previous_cursor
string | null

Opaque cursor for the preceding page. Null on the first and second pages because offset 0 requires no cursor; omitted from legacy offset responses.

Maximum string length: 8192
​
next_cursor
string | null

Opaque cursor for the next page, or null at the end of the supported traversal. Omitted from legacy offset responses.

Maximum string length: 8192
​
cohort_wallet_count
integer

Complete distinct builder-active wallet cohort. Present for P&L sorts.

Required range: 0 <= x <= 100000
​
eligible_wallet_count
integer

Wallets eligible for the requested P&L ranking. Present for P&L sorts.

Required range: 0 <= x <= 100000
​
pnl_as_of
string<date-time>

Canonical P&L snapshot timestamp. Present for P&L sorts.

​
pnl_semantics
string

Explains that P&L is global wallet P&L and is not attributed to the builder. Present for P&L sorts.