BYOB — Leaderboard

GET https://api.polynode.dev/v2/copy-pnl/leaderboard

Query the precomputed leaderboard over your private wallet pool. All reads come from cache — sub-second latency regardless of pool size or window. Sort by any output field, filter out toxic wallets or low-volume traders, paginate.

Query parameters

string

default:"30d"

Time window the scores were computed against. One of: 7d, 14d, 30d, 60d, 90d, 180d. Scores are precomputed for all six periods so any choice is sub-second.

string

default:"backtest_copy_pnl_usdc"

Field to sort by. One of: backtest_copy_pnl_usdc, actual_pnl_usdc, slippage_amount_usdc, slippage_cost_rate_pct, trade_count.

string

default:"desc"

asc or desc. Wallets with null slippage_cost_rate_pct (when abs(actual_pnl) < 1) always sort last regardless of direction.

int

default:"100"

Max results to return. 1 to 1000.

int

default:"0"

Skip the first N results. Useful for paginating beyond limit.

int

default:"0"

Filter out wallets with fewer than N fills in the window. Useful to drop sample-too-small noise.

boolean

default:"false"

When true, drops wallets where slippage_cost_rate_pct > 15. The leader-selection power filter.

Response shape

Field	Type	Description
`period`	string	Echo of the requested period
`sort_by`	string	Echo of the sort field
`order`	string	Echo of the sort direction
`filters`	object	`{min_trade_count, exclude_toxic}` echo
`total_in_pool`	int	Total wallets in your pool
`scored`	int	Wallets with a score for this period
`filtered_in`	int	Wallets that passed the `min_trade_count` + `exclude_toxic` filters
`pending`	int	Wallets in your pool with no score yet (newly added or queued for next refresh)
`errored`	int	Wallets whose last refresh attempt failed (typically heavy whales hitting timeout on long windows)
`offset`	int	Echo
`limit`	int	Echo
`last_refresh`	int (unix) \| null	When the last full refresh cycle completed
`results`	array	Top N matching rows after filters and sort
`errored_sample`	array	Up to 10 errored wallets with their last-error message — only present when `errored > 0`
`pending_sample`	array	Up to 10 pending wallet addresses — only present when `pending > 0`

Per-result row

Field	Type	Description
`local_rank`	int	1-indexed rank within your pool (after offset)
`wallet`	string	Lowercased address
`actual_pnl_usdc`	number	Cashflow PnL over the period
`backtest_copy_pnl_usdc`	number	Same walk with 2% slippage
`slippage_amount_usdc`	number	Dollar friction the copier eats
`slippage_cost_rate_pct`	number \| null	Friction as % of actual PnL (null when \|actual\| < $1)
`toxic_for_copying`	bool	`true` when rate > 15%
`trade_count`	int	Number of fills in the window
`partial`	bool	`true` if the underlying walk hit the per-wallet 180s budget
`computed_at`	int (unix)	When this specific score was last refreshed — surface this in your UI as freshness signal

Example: top 3 by actual_pnl_usdc desc

curl -H "x-api-key: $YOUR_KEY" \
  "https://api.polynode.dev/v2/copy-pnl/leaderboard?period=30d&sort_by=actual_pnl_usdc&order=desc&limit=3"

Response (200 OK):

{
  "period": "30d",
  "sort_by": "actual_pnl_usdc",
  "order": "desc",
  "filters": { "min_trade_count": 0, "exclude_toxic": false },
  "total_in_pool": 108,
  "scored": 104,
  "filtered_in": 104,
  "pending": 1,
  "errored": 3,
  "offset": 0,
  "limit": 3,
  "last_refresh": 1777521943,
  "results": [
    {
      "local_rank": 1,
      "wallet": "0x492442eab586f242b53bda933fd5de859c8a3782",
      "actual_pnl_usdc": 22915787.92,
      "backtest_copy_pnl_usdc": 22129678.06,
      "slippage_amount_usdc": 786109.86,
      "slippage_cost_rate_pct": 3.43,
      "toxic_for_copying": false,
      "trade_count": 8045,
      "partial": false,
      "computed_at": 1777522146
    }
  ]
}

Example: leader screening — best non-toxic, min volume

curl -H "x-api-key: $YOUR_KEY" \
  "https://api.polynode.dev/v2/copy-pnl/leaderboard?period=30d&sort_by=slippage_cost_rate_pct&order=asc&exclude_toxic=true&min_trade_count=1000&limit=3"

Response (200 OK):

{
  "period": "30d",
  "sort_by": "slippage_cost_rate_pct",
  "order": "asc",
  "filters": { "min_trade_count": 1000, "exclude_toxic": true },
  "total_in_pool": 108,
  "scored": 104,
  "filtered_in": 50,
  "pending": 2,
  "errored": 2,
  "offset": 0,
  "limit": 3,
  "results": [
    {
      "local_rank": 1,
      "wallet": "0x9c16127eccf031df45461ef1e04b52ea286a09cb",
      "actual_pnl_usdc": 102171.68,
      "backtest_copy_pnl_usdc": 101643.41,
      "slippage_amount_usdc": 528.27,
      "slippage_cost_rate_pct": 0.52,
      "toxic_for_copying": false,
      "trade_count": 9472,
      "partial": false,
      "computed_at": 1777521515
    }
  ]
}

This is the canonical “find good leaders to copy” query: lowest slippage rate, but only among wallets that have actually traded enough (min_trade_count: 1000) and aren’t already flagged toxic.

Example: pagination (offset)

curl -H "x-api-key: $YOUR_KEY" \
  "https://api.polynode.dev/v2/copy-pnl/leaderboard?period=30d&offset=10&limit=3"

Response includes results with local_rank: 11, 12, 13 — i.e. ranks within your pool start at offset + 1. The default sort is backtest_copy_pnl_usdc desc.

Errors

400 Invalid period:

{ "error": "Invalid period. Allowed: 7d, 14d, 30d, 60d, 90d, 180d" }

400 Invalid sort_by:

{ "error": "Invalid sort_by. Allowed: backtest_copy_pnl_usdc, actual_pnl_usdc, slippage_amount_usdc, slippage_cost_rate_pct, trade_count" }

400 Invalid order:

{ "error": "Invalid order. Allowed: asc | desc" }

Auth/rate-limit errors mirror the rest of the /v2/copy-pnl/* family.

Notes

Sub-second. All scores are precomputed and served from cache. Even a 1000-wallet pool with all six periods scored returns in under 100ms.
pending and errored aren’t included in results. Use pending_sample and errored_sample to identify which specific wallets need attention. The errored_sample includes the upstream error message — typically timeout_180s for the heaviest whales on long windows.
computed_at per row. Use this to render “as of X minutes ago” in your UI. Newly-added wallets (via on-add freshening) typically have a computed_at within ~30s of the add. Periodic refresh updates it once per chunk slot.
last_refresh at top level. When the most recent full refresh cycle completed. Individual wallets may have been refreshed earlier or later within the cycle — use the per-row computed_at field for exact freshness.
Sort ties + nulls. When two wallets share the exact sort_by value, secondary order is undefined. Wallets with null slippage_cost_rate_pct always sort last when sorting on that field.

Overview

V3 Data API

Wallet P&L

Wallet Activity

Credits

Identity

Fees

Combos

Rewards

Markets & Search

Orderbook

Leaderboard & Tags

Builders

Polymarket Profiles

Global

Tokens

Perps

Perps Market Data

Perps Wallets

Perps Analytics

Perps On-Chain

Perps Streaming

Crypto

Sports

BYOL

Backtesting

Market Card

System

Search & Context

Onchain V2 (legacy)

BYOB — Leaderboard

Query parameters

Response shape

Per-result row

Example: top 3 by actual_pnl_usdc desc

Example: leader screening — best non-toxic, min volume

Errors

Notes

​Query parameters

​Response shape

​Per-result row

​Example: top 3 by actual_pnl_usdc desc

​Example: leader screening — best non-toxic, min volume

​Example: pagination (offset)

​Errors

​Notes

Query parameters

Response shape

Per-result row

Example: top 3 by actual_pnl_usdc desc

Example: leader screening — best non-toxic, min volume

Example: pagination (offset)

Errors

Notes