Skip to main content
GET
Combo P&L leaderboard
GET /v3/combos/leaderboard ranks wallets using the dedicated Combo cost-basis ledger. It supports realized P&L for 1-day, 7-day, 30-day, and custom windows, plus realized, unrealized, and total P&L for All Time. The route is intentionally global. It does not accept tag, category, market, or event filters.

Request

Query parameters

The window rules are strict:
  • period=custom requires after, before, or both. When both are present, the realized window is half-open: [after, before).
  • after and before are forbidden with all, 1d, 7d, or 30d.
  • All Time accepts all three sort fields and defaults to total_pnl.
  • Fixed and custom windows rank realized_pnl only.

Examples

Rank marked All Time total P&L:
Rank realized P&L in one half-open window:
One-sided custom windows are also valid. Omitting after leaves the lower side open; omitting before leaves the upper side open.

Response

Window and scope

All Time returns two null window bounds. Fixed 1d, 7d, and 30d responses return both concrete resolved bounds. A custom response preserves an omitted side as null.

Row fields

All USD P&L values are decimal strings. Do not parse them through a binary floating-point type when exact arithmetic matters.

Cost basis, marks, and exclusions

coverage.status is always direct_cost_basis_only. The leaderboard uses directly attributable Combo cost-basis events and does not invent basis for an arbitrary wallet-to-wallet transfer. Every ExchangeV3 OrderFilled row is attributed once to its signed-order maker; the event’s collateral-denominated fee increases BUY cost or reduces SELL proceeds. Router and auto-redemptions are admitted only when their paired PositionRedeemed record proves the redeemed size and payout. Open Combo balances are marked with the latest Combo fill. Terminal Combo positions are marked at 1 for a winning payout or 0 for a losing payout. The endpoint does not replace a missing open mark with zero. A wallet is omitted from data when any position lacks complete direct cost basis, its raw-transfer basis is incomplete, or a required mark is unavailable. Omitted wallets are never zero-filled and therefore cannot silently fall to the bottom of the ranking. Inspect these fields before displaying results:

Errors

An unavailable response is exact:
The endpoint fails closed instead of returning a partial ranking.

Authorizations

x-api-key
string
header
required

Query Parameters

period
enum<string>
default:all

Ranking window. All Time is the default. Custom requires after, before, or both. Fixed periods and All Time forbid explicit bounds.

Available options:
all,
1d,
7d,
30d,
custom
after
integer<int64>

Inclusive custom lower bound in Unix seconds. Accepted only with period=custom; at least one custom bound is required.

before
integer<int64>

Exclusive custom upper bound in Unix seconds. Accepted only with period=custom; at least one custom bound is required.

sort_by
enum<string>

All Time accepts total_pnl, realized_pnl, or unrealized_pnl and defaults to total_pnl. Fixed and custom windows accept realized_pnl only.

Available options:
total_pnl,
realized_pnl,
unrealized_pnl
limit
integer
default:100

Rows per page.

Required range: 1 <= x <= 300
offset
integer
default:0

Rank offset. The maximum accepted offset is 100,000.

Required range: 0 <= x <= 100000

Response

Ranked eligible wallets with the resolved window, P&L scope, and explicit exclusion coverage.

data
object[]
required
period
enum<string>
required
Available options:
all,
1d,
7d,
30d,
custom
window
object
required
pnl_scope
enum<string>
required
Available options:
all_time_marked,
realized_only
coverage
object
required
as_of
string<date-time>
required
as_of_block
integer<int64>
required
Required range: x >= 0
source
enum<string>
required
Available options:
combo_state.combo_cost_basis_event