> ## 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. # Combo P&L Leaderboard > Rank eligible Combo wallets by realized P&L over fixed or custom windows, or by marked All Time P&L. `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 ```text theme={null} GET /v3/combos/leaderboard ``` ### Query parameters | Parameter | Type | Default | Description | | - | - | - | - | | `period` | string | `all` | `all`, `1d`, `7d`, `30d`, or `custom` | | `after` | integer | none | Inclusive custom lower bound in Unix seconds | | `before` | integer | none | Exclusive custom upper bound in Unix seconds | | `sort_by` | string | mode-specific | `total_pnl`, `realized_pnl`, or `unrealized_pnl` | | `limit` | integer | `100` | Rows per page; maximum `300` | | `offset` | integer | `0` | Rank offset; maximum `100000` | 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: ```bash theme={null} curl "https://api.polynode.dev/v3/combos/leaderboard?period=all&sort_by=total_pnl" \ -H "x-api-key: $POLYNODE_API_KEY" ``` Rank realized P\&L in one half-open window: ```bash theme={null} curl "https://api.polynode.dev/v3/combos/leaderboard?period=custom&after=1788134400&before=1788220800&sort_by=realized_pnl" \ -H "x-api-key: $POLYNODE_API_KEY" ``` One-sided custom windows are also valid. Omitting `after` leaves the lower side open; omitting `before` leaves the upper side open. ## Response ```json theme={null} { "data": [ { "rank": 1, "wallet_address": "0x1111111111111111111111111111111111111111", "realized_pnl": "125.5", "unrealized_pnl": "12.25", "total_pnl": "137.75", "open_combo_count": 2, "closed_combo_count": 4, "position_count": 6, "event_count": 18, "last_activity_at": "2026-08-29T16:00:00Z", "win_count": 3, "loss_count": 1, "resolved_count": 4, "win_rate": "0.7500" } ], "period": "all", "window": { "after": null, "before": null }, "pnl_scope": "all_time_marked", "coverage": { "status": "direct_cost_basis_only", "raw_wallet_transfers_included": false, "eligible_wallet_count": 40, "excluded_wallet_count": 3, "transfer_incomplete_wallet_count": 2, "unmarked_wallet_count": 1 }, "as_of": "2026-08-29T16:01:00Z", "as_of_block": 90123456, "source": "combo_state.combo_cost_basis_event" } ``` ### Window and scope | Field | Meaning | | - | - | | `period` | Normalized requested period | | `window.after` | Inclusive resolved lower bound in Unix seconds, or `null` | | `window.before` | Exclusive resolved upper bound in Unix seconds, or `null` | | `pnl_scope` | `all_time_marked` for All Time; `realized_only` for fixed and custom windows | | `as_of` | RFC3339 ledger-snapshot time | | `as_of_block` | Indexed block used by the snapshot | | `source` | Always `combo_state.combo_cost_basis_event` | 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. | Field | Meaning | | - | - | | `rank` | Rank in the requested ordering | | `wallet_address` | Eligible wallet address | | `realized_pnl` | Realized Combo P\&L in decimal USD | | `unrealized_pnl` | Marked unrealized Combo P\&L in decimal USD; `null` in realized-only modes | | `total_pnl` | Realized plus unrealized P\&L in decimal USD; `null` in realized-only modes | | `open_combo_count` | Current eligible open Combo positions, not window-scoped | | `closed_combo_count` | Current eligible closed Combo positions, not window-scoped | | `position_count` | Current eligible Combo position snapshot count, not window-scoped | | `event_count` | Eligible direct-basis events in the realized window; All Time counts all eligible direct-basis events | | `last_activity_at` | RFC3339 time of the wallet's latest eligible Combo activity, or `null` | | `win_count` | Resolved Combo positions the wallet won, all time, not window-scoped | | `loss_count` | Resolved Combo positions the wallet lost, all time, not window-scoped | | `resolved_count` | `win_count` + `loss_count` | | `win_rate` | `win_count` / `resolved_count` as a 4-decimal fraction string (`"0.7500"` = 75%), or `null` when the wallet has no resolved Combo | A Combo position is won or lost once its legs resolve: a YES position wins when every leg wins and loses as soon as any leg loses; a NO position is the reverse. For one wallet's win and loss counts inside a time window, call [Wallet Combo Summary](https://docs.polynode.dev/data/combos/wallet-summary.md#time-windows) with `period=custom` and this response's `window.after` / `window.before`. The two place activity differently: ranged leaderboard P\&L follows realized events, and windowed win/loss counts follow when each combo settled. ## 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](https://docs.polynode.dev/data/wallets/pnl.md) 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: | Coverage field | Meaning | | - | - | | `eligible_wallet_count` | Wallets eligible for this ranking snapshot | | `excluded_wallet_count` | Wallets omitted for incomplete direct/transfer basis or a missing mark | | `transfer_incomplete_wallet_count` | Wallets whose arbitrary raw transfer prevents complete direct basis | | `unmarked_wallet_count` | Wallets without every mark required by the requested ranking | | `raw_wallet_transfers_included` | Always `false`; arbitrary transferred basis is not inferred | ## Errors | Status | Error | When it occurs | | - | - | - | | `400` | `invalid_request` | Invalid period, custom bound combination, sort, limit, or offset | | `401` | authentication error | The API key is missing or invalid | | `503` | `combo_pnl_unavailable` | The Combo P\&L ledger or required mark snapshot is unavailable | An unavailable response is exact: ```json theme={null} { "error": "combo_pnl_unavailable", "message": "Combo P&L is temporarily unavailable." } ``` The endpoint fails closed instead of returning a partial ranking. ## OpenAPI ````yaml GET /v3/combos/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/combos/leaderboard: get: tags: - V3 Combos summary: Combo P&L leaderboard description: >- Rank eligible wallets by Combo realized P&L over 1-day, 7-day, 30-day, or custom half-open windows, or by All Time realized, unrealized, or total P&L. Each signed ExchangeV3 order is attributed once to its maker; the collateral-denominated exchange fee recorded in OrderFilled.fee increases BUY cost or reduces SELL proceeds, and wrapped redemptions require an exact paired underlying redemption. Wallets with incomplete direct cost basis, incomplete arbitrary raw-transfer basis, or without a required current mark are excluded and disclosed in coverage; they are never returned as zero-P&L rows. This route does not accept category or tag filters. The signed-order maker is the order owner, not necessarily the liquidity supplier. The fill fee has no component breakdown; gas, separate application or escrow charges, and rebates or rewards outside that field are excluded. This Combo fee treatment does not apply to standard spot or perps P&L. operationId: v3_combo_pnl_leaderboard parameters: - name: period in: query required: false description: >- Ranking window. All Time is the default. Custom requires after, before, or both. Fixed periods and All Time forbid explicit bounds. schema: type: string enum: - all - 1d - 7d - 30d - custom default: all - name: after in: query required: false description: >- Inclusive custom lower bound in Unix seconds. Accepted only with period=custom; at least one custom bound is required. schema: type: integer format: int64 - name: before in: query required: false description: >- Exclusive custom upper bound in Unix seconds. Accepted only with period=custom; at least one custom bound is required. schema: type: integer format: int64 - name: sort_by in: query required: false description: >- All Time accepts total_pnl, realized_pnl, or unrealized_pnl and defaults to total_pnl. Fixed and custom windows accept realized_pnl only. schema: type: string enum: - total_pnl - realized_pnl - unrealized_pnl - name: limit in: query required: false description: Rows per page. schema: type: integer minimum: 1 maximum: 300 default: 100 - name: offset in: query required: false description: Rank offset. The maximum accepted offset is 100,000. schema: type: integer minimum: 0 maximum: 100000 default: 0 responses: '200': description: >- Ranked eligible wallets with the resolved window, P&L scope, and explicit exclusion coverage. content: application/json: schema: $ref: '#/components/schemas/V3ComboPnlLeaderboardResponse' example: data: - rank: 1 wallet_address: '0x1111111111111111111111111111111111111111' realized_pnl: '125.5' unrealized_pnl: '12.25' total_pnl: '137.75' open_combo_count: 2 closed_combo_count: 4 position_count: 6 event_count: 18 last_activity_at: '2026-08-29T16:00:00Z' win_count: 3 loss_count: 1 resolved_count: 4 win_rate: '0.7500' period: all window: after: null before: null pnl_scope: all_time_marked coverage: status: direct_cost_basis_only raw_wallet_transfers_included: false eligible_wallet_count: 40 excluded_wallet_count: 3 transfer_incomplete_wallet_count: 2 unmarked_wallet_count: 1 as_of: '2026-08-29T16:01:00Z' as_of_block: 90123456 source: combo_state.combo_cost_basis_event '400': description: Invalid period, bound combination, sort, limit, or offset. content: application/json: schema: $ref: '#/components/schemas/V3ComboPnlInvalidRequest' example: error: invalid_request message: period=custom requires after, before, or both '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The Combo P&L ledger or required mark snapshot is unavailable; no partial ranking is returned. content: application/json: schema: $ref: '#/components/schemas/V3ComboPnlUnavailable' example: error: combo_pnl_unavailable message: Combo P&L is temporarily unavailable. security: - api_key: [] components: schemas: V3ComboPnlLeaderboardResponse: type: object additionalProperties: false required: - data - period - window - pnl_scope - coverage - as_of - as_of_block - source properties: data: type: array items: $ref: '#/components/schemas/V3ComboPnlLeaderboardRow' period: $ref: '#/components/schemas/V3ComboPnlLeaderboardPeriod' window: $ref: '#/components/schemas/V3ComboPnlLeaderboardWindow' pnl_scope: type: string enum: - all_time_marked - realized_only coverage: $ref: '#/components/schemas/V3ComboPnlLeaderboardCoverage' as_of: type: string format: date-time as_of_block: type: integer format: int64 minimum: 0 source: type: string enum: - combo_state.combo_cost_basis_event V3ComboPnlInvalidRequest: type: object additionalProperties: false required: - error - message properties: error: type: string enum: - invalid_request message: type: string ErrorResponse: type: object required: - error properties: error: type: string V3ComboPnlUnavailable: type: object additionalProperties: false required: - error - message properties: error: type: string enum: - combo_pnl_unavailable message: type: string enum: - Combo P&L is temporarily unavailable. V3ComboPnlLeaderboardRow: type: object additionalProperties: false required: - rank - wallet_address - realized_pnl - unrealized_pnl - total_pnl - open_combo_count - closed_combo_count - position_count - event_count - last_activity_at - win_count - loss_count - resolved_count - win_rate properties: rank: type: integer minimum: 1 wallet_address: type: string pattern: ^0x[a-fA-F0-9]{40}$ realized_pnl: $ref: '#/components/schemas/V3SignedDecimalString' unrealized_pnl: description: All Time marked P&L, or null for realized-only windows. anyOf: - $ref: '#/components/schemas/V3SignedDecimalString' - type: 'null' total_pnl: description: >- All Time realized plus unrealized P&L, or null for realized-only windows. anyOf: - $ref: '#/components/schemas/V3SignedDecimalString' - type: 'null' open_combo_count: type: integer minimum: 0 description: Current eligible open Combo positions; not window-scoped. closed_combo_count: type: integer minimum: 0 description: Current eligible closed Combo positions; not window-scoped. position_count: type: integer minimum: 0 description: Current eligible Combo position snapshot count; not window-scoped. event_count: type: integer minimum: 0 description: >- Eligible direct-basis event count in the realized window, or across all eligible history for All Time. last_activity_at: type: - string - 'null' format: date-time win_count: type: integer minimum: 0 description: >- Resolved Combo positions the wallet won, all time, not window-scoped. loss_count: type: integer minimum: 0 description: >- Resolved Combo positions the wallet lost, all time, not window-scoped. resolved_count: type: integer minimum: 0 description: win_count + loss_count. win_rate: type: - string - 'null' description: >- win_count / resolved_count as a 4-decimal fraction string, or null when the wallet has no resolved Combo. V3ComboPnlLeaderboardPeriod: type: string enum: - all - 1d - 7d - 30d - custom V3ComboPnlLeaderboardWindow: type: object additionalProperties: false required: - after - before properties: after: type: - integer - 'null' format: int64 description: >- Inclusive resolved lower bound in Unix seconds. All Time returns null; an omitted custom side remains null. before: type: - integer - 'null' format: int64 description: >- Exclusive resolved upper bound in Unix seconds. All Time returns null; an omitted custom side remains null. V3ComboPnlLeaderboardCoverage: type: object additionalProperties: false required: - status - raw_wallet_transfers_included - eligible_wallet_count - excluded_wallet_count - transfer_incomplete_wallet_count - unmarked_wallet_count properties: status: type: string enum: - direct_cost_basis_only raw_wallet_transfers_included: type: boolean enum: - false description: Arbitrary wallet-to-wallet transfer basis is not inferred or ranked. eligible_wallet_count: type: integer minimum: 0 excluded_wallet_count: type: integer minimum: 0 description: >- Wallets omitted from data because direct cost basis or a required mark is incomplete. transfer_incomplete_wallet_count: type: integer minimum: 0 unmarked_wallet_count: type: integer minimum: 0 V3SignedDecimalString: type: string pattern: ^-?[0-9]+(?:[.][0-9]+)?$ description: An exact signed decimal encoded as a string. securitySchemes: api_key: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.