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.

Which fees are included?

The included fee is specifically the collateral-denominated exchange fee recorded in each signed order’s OrderFilled.fee. It increases BUY cost or reduces SELL proceeds, so do not deduct that fee again from Combo P&L. “Maker” here identifies the signed-order owner; it does not by itself establish who supplied liquidity. This field does not provide a breakdown of fee components. Gas, separately collected application or escrow charges, and rebates or rewards outside this recorded fill fee are not included by this calculation. Do not describe Combo P&L as including every cost or credit. Standard spot Wallet P&L excludes separately reported fees, rebates, and rewards. Perps uses a separate accounting model. The Combo rule must not be applied to either product’s P&L. 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