---
title: "Ranked entities with filters"
method: GET
path: "/v1/leaderboard"
tags: ["Board"]
---

# Ranked entities with filters

`GET /v1/leaderboard`

## Request

- Base URL: `https://api.pmwallets.com`
- URL: `https://api.pmwallets.com/v1/leaderboard`
- Auth: one of:
  - none
  - API key in header `x-api-key`

Entities ranked by PnL. Unbought entities appear as handles with their unlock price (revealCents). No key: 20-row sample. With a key: up to 200 rows a call; each call spends `limit` rows of a 20,000/day allowance (403 when used up). mine=1 lists your unlocked addresses, free. Never charges.

## Query parameters

- `period` string
- `sort` 'realizedPnl' | 'roiOnBuys' | 'eligible' | 'winsLosses' | 'nFills' | 'conditions' | 'grossBuyUsdc' | 'unrealizedPnl' | 'winLo' | 'fillsPerDay' | 'lastFill'
- `dir` 'asc' | 'desc'
- `limit` integer
- `offset` integer
- `mine` '1'
- `minEligible` integer
- `minWinsLosses` integer
- `minPnl` number
- `minRoi` number
- `minWinLo` number
- `maxWallets` number
- `minFills` number
- `minVolume` number
- `status` 'active' | 'quiet' | 'dormant'
- `style` 'maker' | 'taker' | 'two-sided'
- `category` 'crypto-updown' | 'crypto' | 'esports' | 'sports' | 'politics' | 'economy' | 'geopolitics' | 'science-tech' | 'culture' | 'other' | 'unknown'
- `minCategoryShare` number
- `bands` integer[]

## Response `200`

OK

- Leaderboard
  - `periodId` string
  - `tier` 'anon' | 'free' | 'subscriber': anon = no valid key; subscriber = an active push subscription or active plan.
  - `plan` PlanUsage: The caller's plan and what is left of its unlock allowance (present when signed in).
    - `state` 'active' | 'grace' | 'none'
    - `tier` string, nullable
    - `graceUntil` string, nullable
    - `daily` integer
    - `dailyUsed` integer
    - `monthly` integer
    - `monthlyUsed` integer
    - `pushSlots` integer
    - `pushActive` integer
  - `sampled` boolean: true for the anonymous 20-row sample.
  - `filters` object: The filters actually applied.
  - `sort` 'realizedPnl' | 'roiOnBuys' | 'eligible' | 'winsLosses' | 'nFills' | 'conditions' | 'grossBuyUsdc' | 'unrealizedPnl' | 'winLo' | 'fillsPerDay' | 'lastFill'
  - `dir` 'asc' | 'desc'
  - `sorts` string[]
  - `historyFrom` string, nullable: First UTC day of the ledger behind this window.
  - `refresh` object
    - `everyBlocks` integer
    - `maxIdleMin` integer
    - `blockSec` number
  - `pricing` object
    - `revealCents` integer: Price of the cheapest paid band.
    - `subscriptionCentsPerHour` integer
    - `bands` object[]
      - `band` integer
      - `from` number, nullable: pnlExTop where the band starts; null = no floor.
      - `cents` integer
  - `limits` object
    - `maxRows` integer
    - `maxOffset` integer
    - `capped` boolean: limit/offset were reduced to the tier maximum.
    - `dailyRows` integer
    - `usedToday` integer
  - `tracked` integer: Entities in the window (independent of filters). With mine=1: how many addresses you have unlocked.
  - `rows` LeaderboardRow[]
    - `entityId` string: Handle until you hold the address, then the 0x address. Pass it back to other endpoints as-is.
    - `label` string: Masked address (0x4b96…984e) until you hold it, then the full address.
    - `revealed` boolean: You hold the address (paid unlock, a still-free free unlock, or an active plan unlock).
    - `revealCents` integer: What unlocking this address costs now (0 = free band). Absent when not for sale (prices not published for the window).
    - `subscribed` boolean: You have an active push subscription to it.
    - `subscriptionId` string: Present when subscribed.
    - `viaPlan` boolean: Held only through your plan; masked again when the plan ends.
    - `unlockedBy` 'paid' | 'free' | 'plan' | 'null', nullable: mine=1 only: how you hold it; null = lapsed (masked again).
    - `pausedReason` string: mine=1 only: your subscription to it is paused for this reason.
    - `wallets` integer: Addresses of the entity that traded in the window.
    - `conditions` integer: Markets traded in the window.
    - `eligible` integer: Settled markets counted (wins + losses + breakevens).
    - `wins` integer
    - `losses` integer
    - `breakevens` integer
    - `excludedConditions` integer
    - `realizedPnl` number: Dollars.
    - `unrealizedPnl` number: Dollars.
    - `totalPnl` number: Dollars.
    - `grossBuyUsdc` number: Dollars spent buying in the window.
    - `feeUsdc` number
    - `roiOnBuys` number: realizedPnl / grossBuyUsdc (0.2 = 20%).
    - `nFills` integer
    - `pnlExTop` number: Realised PnL minus its single best settled market; decides the price band.
    - `pricePnlExTop` number, nullable
    - `wr` number, nullable
    - `lo` number, nullable
    - `hi` number, nullable
    - `status` 'active' | 'quiet' | 'dormant': Last fill <24h / <7d / older.
    - `statusAsOf` string, nullable
    - `style` 'maker' | 'taker' | 'two-sided' | 'null', nullable: By share of traded value made as maker (>=0.8 maker, <=0.2 taker).
    - `makerShare` number, nullable
    - `categories` object[]
      - `category` 'crypto-updown' | 'crypto' | 'esports' | 'sports' | 'politics' | 'economy' | 'geopolitics' | 'science-tech' | 'culture' | 'other' | 'unknown'
      - `share` number
    - `activity` Activity
      - `nFills` integer
      - `firstFillTs` string, nullable
      - `lastFillTs` string, nullable
      - `lastFillBlock` integer
      - `activeDays` integer
      - `fills24h` integer
      - `fills7d` integer
      - `windowEndTs` string, nullable
      - `makerFills` number, nullable
      - `makerUsdc` number, nullable
      - `usdc` number, nullable
    - `dataSource` 'live' | 'frozen'
    - `dataPeriodId` string
    - `dataAsOf` string, nullable
  - `outside` object[]: mine=1, first page only: your unlocked addresses with no fill in this window.
    - `entityId` string
    - `label` string
    - `revealed` boolean
    - `subscribed` boolean
    - `unlockedBy` string, nullable
    - `pausedReason` string

## Other responses

- `400`: Invalid parameter or body; `message` names what was expected.
- `401`: mine=1 without a valid key.
- `403`: Daily row allowance used up; resets 00:00 UTC.
- `404`: No published stats yet.
- `429`: Rate limited. Per IP 240/min overall and 180/min on the board and entity routes; per account 120/min (anonymous 60/min per IP) on board, entity and market reads. A `retry-after` header may be set.

---

[API](https://skmtc.dev/pmwallets/apis/pmwallets-api.md) · [All operations](https://skmtc.dev/pmwallets/apis/pmwallets-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pmwallets/apis/pmwallets-api/revisions/d5023fb40430?raw)